X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=0a119452bf3210b7babbe1229a4d3e76f829c23f;hb=cb0a5b5c946748a0ce5472032178d97c33e21b33;hp=9f9d0ef15e840146b8487617c7e82e05a90f4990;hpb=dba10f866414a256f0b1a50bcb5bde2c3d2a8e78;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 9f9d0ef..0a11945 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -17,6 +17,85 @@ unadorned names, but this support may be disabled in a future release. The listing is alphabetical, case insensitive. + +=head1 "Gimme" Values + +=over 8 + +=item GIMME + +A backward-compatible version of C which can only return +C or C; in a void context, it returns C. +Deprecated. Use C instead. + + U32 GIMME + +=for hackers +Found in file op.h + +=item GIMME_V + +The XSUB-writer's equivalent to Perl's C. Returns C, +C or C for void, scalar or list context, +respectively. + + U32 GIMME_V + +=for hackers +Found in file op.h + +=item G_ARRAY + +Used to indicate list context. See C, C and +L. + +=for hackers +Found in file cop.h + +=item G_DISCARD + +Indicates that arguments returned from a callback should be discarded. See +L. + +=for hackers +Found in file cop.h + +=item G_EVAL + +Used to force a Perl C wrapper around a callback. See +L. + +=for hackers +Found in file cop.h + +=item G_NOARGS + +Indicates that no arguments are being sent to a callback. See +L. + +=for hackers +Found in file cop.h + +=item G_SCALAR + +Used to indicate scalar context. See C, C, and +L. + +=for hackers +Found in file cop.h + +=item G_VOID + +Used to indicate void context. See C and L. + +=for hackers +Found in file cop.h + + +=back + +=head1 Array Manipulation Functions + =over 8 =item AvFILL @@ -182,47 +261,53 @@ must then use C to assign values to these new elements. =for hackers Found in file av.c -=item ax +=item get_av -Variable which is setup by C to indicate the stack base offset, -used by the C, C and C macros. The C macro -must be called prior to setup the C variable. +Returns the AV of the specified Perl array. If C is set and the +Perl variable does not exist then it will be created. If C is not +set and the variable does not exist then NULL is returned. - I32 ax +NOTE: the perl_ form of this function is deprecated. + + AV* get_av(const char* name, I32 create) =for hackers -Found in file XSUB.h +Found in file perl.c -=item bytes_from_utf8 +=item newAV -Converts a string C of length C from UTF8 into byte encoding. -Unlike but like C, returns a pointer to -the newly-created string, and updates C to contain the new -length. Returns the original string if no conversion occurs, C -is unchanged. Do nothing if C points to 0. Sets C to -0 if C is converted or contains all 7bit characters. +Creates a new AV. The reference count is set to 1. -NOTE: this function is experimental and may change or be -removed without notice. + AV* newAV() + +=for hackers +Found in file av.c + +=item Nullav + +Null AV pointer. - U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) =for hackers -Found in file utf8.c +Found in file av.h -=item bytes_to_utf8 +=item sortsv -Converts a string C of length C from ASCII into UTF8 encoding. -Returns a pointer to the newly-created string, and sets C to -reflect the new length. +Sort an array. Here is an example: -NOTE: this function is experimental and may change or be -removed without notice. + sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); - U8* bytes_to_utf8(U8 *s, STRLEN *len) + void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) =for hackers -Found in file utf8.c +Found in file pp_sort.c + + +=back + +=head1 Callback Functions + +=over 8 =item call_argv @@ -270,328 +355,387 @@ NOTE: the perl_ form of this function is deprecated. =for hackers Found in file perl.c -=item CLASS +=item ENTER -Variable which is setup by C to indicate the -class name for a C++ XS constructor. This is always a C. See C. +Opening bracket on a callback. See C and L. - char* CLASS + ENTER; =for hackers -Found in file XSUB.h +Found in file scope.h -=item Copy +=item eval_pv -The XSUB-writer's interface to the C C function. The C is the -source, C is the destination, C is the number of items, and C is -the type. May fail on overlapping copies. See also C. +Tells Perl to C the given string and return an SV* result. - void Copy(void* src, void* dest, int nitems, type) +NOTE: the perl_ form of this function is deprecated. -=for hackers -Found in file handy.h + SV* eval_pv(const char* p, I32 croak_on_error) -=item croak +=for hackers +Found in file perl.c -This is the XSUB-writer's interface to Perl's C function. -Normally use this function the same way you use the C C -function. See C. +=item eval_sv -If you want to throw an exception object, assign the object to -C<$@> and then pass C to croak(): +Tells Perl to C the string in the SV. - errsv = get_sv("@", TRUE); - sv_setsv(errsv, exception_object); - croak(Nullch); +NOTE: the perl_ form of this function is deprecated. - void croak(const char* pat, ...) + I32 eval_sv(SV* sv, I32 flags) =for hackers -Found in file util.c +Found in file perl.c -=item CvSTASH +=item FREETMPS -Returns the stash of the CV. +Closing bracket for temporaries on a callback. See C and +L. - HV* CvSTASH(CV* cv) + FREETMPS; =for hackers -Found in file cv.h - -=item cv_const_sv +Found in file scope.h -If C is a constant sub eligible for inlining. returns the constant -value returned by the sub. Otherwise, returns NULL. +=item LEAVE -Constant subs can be created with C or as described in -L. +Closing bracket on a callback. See C and L. - SV* cv_const_sv(CV* cv) + LEAVE; =for hackers -Found in file op.c +Found in file scope.h -=item dAX +=item SAVETMPS -Sets up the C variable. -This is usually handled automatically by C by calling C. +Opening bracket for temporaries on a callback. See C and +L. - dAX; + SAVETMPS; =for hackers -Found in file XSUB.h +Found in file scope.h -=item dITEMS -Sets up the C variable. -This is usually handled automatically by C by calling C. +=back - dITEMS; +=head1 Character classes -=for hackers -Found in file XSUB.h +=over 8 -=item dMARK +=item isALNUM -Declare a stack marker variable, C, for the XSUB. See C and -C. +Returns a boolean indicating whether the C C is an ASCII alphanumeric +character (including underscore) or digit. - dMARK; + bool isALNUM(char ch) =for hackers -Found in file pp.h +Found in file handy.h -=item dORIGMARK +=item isALPHA -Saves the original stack mark for the XSUB. See C. +Returns a boolean indicating whether the C C is an ASCII alphabetic +character. - dORIGMARK; + bool isALPHA(char ch) =for hackers -Found in file pp.h +Found in file handy.h -=item dSP +=item isDIGIT -Declares a local copy of perl's stack pointer for the XSUB, available via -the C macro. See C. +Returns a boolean indicating whether the C C is an ASCII +digit. - dSP; + bool isDIGIT(char ch) =for hackers -Found in file pp.h +Found in file handy.h -=item dXSARGS +=item isLOWER -Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. -Sets up the C and C variables by calling C and C. -This is usually handled automatically by C. +Returns a boolean indicating whether the C C is a lowercase +character. - dXSARGS; + bool isLOWER(char ch) =for hackers -Found in file XSUB.h +Found in file handy.h -=item dXSI32 +=item isSPACE -Sets up the C variable for an XSUB which has aliases. This is usually -handled automatically by C. +Returns a boolean indicating whether the C C is whitespace. - dXSI32; + bool isSPACE(char ch) =for hackers -Found in file XSUB.h +Found in file handy.h -=item ENTER +=item isUPPER -Opening bracket on a callback. See C and L. +Returns a boolean indicating whether the C C is an uppercase +character. - ENTER; + bool isUPPER(char ch) =for hackers -Found in file scope.h +Found in file handy.h -=item eval_pv +=item toLOWER -Tells Perl to C the given string and return an SV* result. +Converts the specified character to lowercase. -NOTE: the perl_ form of this function is deprecated. + char toLOWER(char ch) - SV* eval_pv(const char* p, I32 croak_on_error) +=for hackers +Found in file handy.h + +=item toUPPER + +Converts the specified character to uppercase. + + char toUPPER(char ch) =for hackers -Found in file perl.c +Found in file handy.h -=item eval_sv -Tells Perl to C the string in the SV. +=back + +=head1 Cloning an interpreter + +=over 8 + +=item perl_clone + +Create and return a new interpreter by cloning the current one. + + PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) + +=for hackers +Found in file sv.c + + +=back + +=head1 CV Manipulation Functions + +=over 8 + +=item CvSTASH + +Returns the stash of the CV. + + HV* CvSTASH(CV* cv) + +=for hackers +Found in file cv.h + +=item get_cv + +Returns the CV of the specified Perl subroutine. If C is set and +the Perl subroutine does not exist then it will be declared (which has the +same effect as saying C). If C is not set and the +subroutine does not exist then NULL is returned. NOTE: the perl_ form of this function is deprecated. - I32 eval_sv(SV* sv, I32 flags) + CV* get_cv(const char* name, I32 create) =for hackers Found in file perl.c -=item EXTEND +=item Nullcv -Used to extend the argument stack for an XSUB's return values. Once -used, guarantees that there is room for at least C to be pushed -onto the stack. +Null CV pointer. - void EXTEND(SP, int nitems) =for hackers -Found in file pp.h +Found in file cv.h -=item fbm_compile -Analyses the string in order to make fast searches on it using fbm_instr() --- the Boyer-Moore algorithm. +=back - void fbm_compile(SV* sv, U32 flags) +=head1 Embedding Functions -=for hackers -Found in file util.c +=over 8 -=item fbm_instr +=item load_module -Returns the location of the SV in the string delimited by C and -C. It returns C if the string can't be found. The C -does not have to be fbm_compiled, but the search will not be as fast -then. +Loads the module whose name is pointed to by the string part of name. +Note that the actual module name, not its filename, should be given. +Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of +PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS +(or 0 for no flags). ver, if specified, provides version semantics +similar to C. The optional trailing SV* +arguments can be used to specify arguments to the module's import() +method, similar to C. - char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) + void load_module(U32 flags, SV* name, SV* ver, ...) =for hackers -Found in file util.c +Found in file op.c -=item FREETMPS +=item perl_alloc -Closing bracket for temporaries on a callback. See C and -L. +Allocates a new Perl interpreter. See L. - FREETMPS; + PerlInterpreter* perl_alloc() =for hackers -Found in file scope.h +Found in file perl.c -=item getcwd_sv +=item perl_construct -Fill the sv with current working directory +Initializes a new Perl interpreter. See L. - int getcwd_sv(SV* sv) + void perl_construct(PerlInterpreter* interp) =for hackers -Found in file util.c +Found in file perl.c -=item get_av +=item perl_destruct -Returns the AV of the specified Perl array. If C is set and the -Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then NULL is returned. +Shuts down a Perl interpreter. See L. -NOTE: the perl_ form of this function is deprecated. + int perl_destruct(PerlInterpreter* interp) - AV* get_av(const char* name, I32 create) +=for hackers +Found in file perl.c + +=item perl_free + +Releases a Perl interpreter. See L. + + void perl_free(PerlInterpreter* interp) =for hackers Found in file perl.c -=item get_cv +=item perl_parse -Returns the CV of the specified Perl subroutine. If C is set and -the Perl subroutine does not exist then it will be declared (which has the -same effect as saying C). If C is not set and the -subroutine does not exist then NULL is returned. +Tells a Perl interpreter to parse a Perl script. See L. -NOTE: the perl_ form of this function is deprecated. + int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) - CV* get_cv(const char* name, I32 create) +=for hackers +Found in file perl.c + +=item perl_run + +Tells a Perl interpreter to run. See L. + + int perl_run(PerlInterpreter* interp) =for hackers Found in file perl.c -=item get_hv +=item require_pv -Returns the HV of the specified Perl hash. If C is set and the -Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then NULL is returned. +Tells Perl to C the file named by the string argument. It is +analogous to the Perl code C. It's even +implemented that way; consider using Perl_load_module instead. NOTE: the perl_ form of this function is deprecated. - HV* get_hv(const char* name, I32 create) + void require_pv(const char* pv) =for hackers Found in file perl.c -=item get_sv -Returns the SV of the specified Perl scalar. If C is set and the -Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then NULL is returned. +=back -NOTE: the perl_ form of this function is deprecated. +=head1 Functions in file pp_pack.c - SV* get_sv(const char* name, I32 create) + +=over 8 + +=item pack_cat + +The engine implementing pack() Perl function. + + void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) =for hackers -Found in file perl.c +Found in file pp_pack.c -=item GIMME +=item unpack_str -A backward-compatible version of C which can only return -C or C; in a void context, it returns C. -Deprecated. Use C instead. +The engine implementing unpack() Perl function. - U32 GIMME + I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) =for hackers -Found in file op.h +Found in file pp_pack.c -=item GIMME_V -The XSUB-writer's equivalent to Perl's C. Returns C, -C or C for void, scalar or list context, -respectively. +=back - U32 GIMME_V +=head1 Global Variables + +=over 8 + +=item PL_modglobal + +C is a general purpose, interpreter global HV for use by +extensions that need to keep information on a per-interpreter basis. +In a pinch, it can also be used as a symbol table for extensions +to share data among each other. It is a good idea to use keys +prefixed by the package name of the extension that owns the data. + + HV* PL_modglobal =for hackers -Found in file op.h +Found in file intrpvar.h -=item grok_number +=item PL_na -Recognise (or not) a number. The type of the number is returned -(0 if unrecognised), otherwise it is a bit-ORed combination of -IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, -IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). +A convenience variable which is typically used with C when one +doesn't care about the length of the string. It is usually more efficient +to either declare a local variable and use that instead or to use the +C macro. -If the value of the number can fit an in UV, it is returned in the *valuep -IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV -will never be set unless *valuep is valid, but *valuep may have been assigned -to during processing even though IS_NUMBER_IN_UV is not set on return. -If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when -valuep is non-NULL, but no actual assignment (or SEGV) will occur. + STRLEN PL_na -IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were -seen (in which case *valuep gives the true value truncated to an integer), and -IS_NUMBER_NEG if the number is negative (in which case *valuep holds the -absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the -number is larger than a UV. +=for hackers +Found in file thrdvar.h - int grok_number(const char *pv, STRLEN len, UV *valuep) +=item PL_sv_no + +This is the C SV. See C. Always refer to this as +C<&PL_sv_no>. + + SV PL_sv_no =for hackers -Found in file numeric.c +Found in file intrpvar.h -=item grok_numeric_radix +=item PL_sv_undef -Scan and skip for a numeric decimal separator (radix). +This is the C SV. Always refer to this as C<&PL_sv_undef>. - bool grok_numeric_radix(const char **sp, const char *send) + SV PL_sv_undef =for hackers -Found in file numeric.c +Found in file intrpvar.h + +=item PL_sv_yes + +This is the C SV. See C. Always refer to this as +C<&PL_sv_yes>. + + SV PL_sv_yes + +=for hackers +Found in file intrpvar.h + + +=back + +=head1 GV Functions + +=over 8 =item GvSV @@ -662,9 +806,23 @@ C apply equally to these functions. =for hackers Found in file gv.c -=item gv_stashpv +=item gv_fetchmeth_autoload -Returns a pointer to the stash for a specified package. C should +Same as gv_fetchmeth(), but looks for autoloaded subroutines too. +Returns a glob for the subroutine. + +For an autoloaded subroutine without a GV, will create a GV even +if C. For an autoloaded subroutine without a stub, GvCV() +of the result may be zero. + + GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) + +=for hackers +Found in file gv.c + +=item gv_stashpv + +Returns a pointer to the stash for a specified package. C should be a valid UTF-8 string. If C is set then the package will be created if it does not already exist. If C is not set and the package does not exist then NULL is returned. @@ -684,61 +842,55 @@ valid UTF-8 string. See C. =for hackers Found in file gv.c -=item G_ARRAY -Used to indicate list context. See C, C and -L. +=back -=for hackers -Found in file cop.h +=head1 Handy Values -=item G_DISCARD +=over 8 -Indicates that arguments returned from a callback should be discarded. See -L. +=item HEf_SVKEY -=for hackers -Found in file cop.h +This flag, used in the length slot of hash entries and magic structures, +specifies the structure contains an C pointer where a C pointer +is to be expected. (For information only--not to be used). -=item G_EVAL -Used to force a Perl C wrapper around a callback. See -L. +=for hackers +Found in file hv.h + +=item Nullch +Null character pointer. =for hackers -Found in file cop.h +Found in file handy.h -=item G_NOARGS +=item Nullsv -Indicates that no arguments are being sent to a callback. See -L. +Null SV pointer. =for hackers -Found in file cop.h +Found in file handy.h -=item G_SCALAR -Used to indicate scalar context. See C, C, and -L. +=back -=for hackers -Found in file cop.h +=head1 Hash Manipulation Functions -=item G_VOID +=over 8 -Used to indicate void context. See C and L. +=item get_hv -=for hackers -Found in file cop.h +Returns the HV of the specified Perl hash. If C is set and the +Perl variable does not exist then it will be created. If C is not +set and the variable does not exist then NULL is returned. -=item HEf_SVKEY +NOTE: the perl_ form of this function is deprecated. -This flag, used in the length slot of hash entries and magic structures, -specifies the structure contains a C pointer where a C pointer -is to be expected. (For information only--not to be used). + HV* get_hv(const char* name, I32 create) =for hackers -Found in file hv.h +Found in file perl.c =item HeHASH @@ -898,7 +1050,7 @@ Found in file hv.c Returns the SV which corresponds to the specified key in the hash. The C is the length of the key. If C is set then the fetch will be part of a store. Check that the return value is non-null before -dereferencing it to a C. +dereferencing it to an C. See L for more information on how to use this function on tied hashes. @@ -1048,223 +1200,197 @@ Undefines the hash. =for hackers Found in file hv.c -=item isALNUM +=item newHV -Returns a boolean indicating whether the C C is an ASCII alphanumeric -character (including underscore) or digit. +Creates a new HV. The reference count is set to 1. - bool isALNUM(char ch) + HV* newHV() =for hackers -Found in file handy.h +Found in file hv.c -=item isALPHA +=item Nullhv -Returns a boolean indicating whether the C C is an ASCII alphabetic -character. +Null HV pointer. - bool isALPHA(char ch) =for hackers -Found in file handy.h +Found in file hv.h -=item isDIGIT -Returns a boolean indicating whether the C C is an ASCII -digit. +=back - bool isDIGIT(char ch) +=head1 Magical Functions -=for hackers -Found in file handy.h +=over 8 -=item isLOWER +=item mg_clear -Returns a boolean indicating whether the C C is a lowercase -character. +Clear something magical that the SV represents. See C. - bool isLOWER(char ch) + int mg_clear(SV* sv) =for hackers -Found in file handy.h +Found in file mg.c -=item isSPACE +=item mg_copy -Returns a boolean indicating whether the C C is whitespace. +Copies the magic from one SV to another. See C. - bool isSPACE(char ch) + int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) =for hackers -Found in file handy.h +Found in file mg.c -=item isUPPER +=item mg_find -Returns a boolean indicating whether the C C is an uppercase -character. +Finds the magic pointer for type matching the SV. See C. - bool isUPPER(char ch) + MAGIC* mg_find(SV* sv, int type) =for hackers -Found in file handy.h +Found in file mg.c -=item is_utf8_char +=item mg_free -Tests if some arbitrary number of bytes begins in a valid UTF-8 -character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character. -The actual number of bytes in the UTF-8 character will be returned if -it is valid, otherwise 0. +Free any magic storage used by the SV. See C. - STRLEN is_utf8_char(U8 *p) + int mg_free(SV* sv) =for hackers -Found in file utf8.c +Found in file mg.c -=item is_utf8_string +=item mg_get -Returns true if first C bytes of the given string form a valid UTF8 -string, false otherwise. Note that 'a valid UTF8 string' does not mean -'a string that contains UTF8' because a valid ASCII string is a valid -UTF8 string. +Do magic after a value is retrieved from the SV. See C. - bool is_utf8_string(U8 *s, STRLEN len) + int mg_get(SV* sv) =for hackers -Found in file utf8.c +Found in file mg.c -=item items +=item mg_length -Variable which is setup by C to indicate the number of -items on the stack. See L. +Report on the SV's length. See C. - I32 items + U32 mg_length(SV* sv) =for hackers -Found in file XSUB.h +Found in file mg.c -=item ix +=item mg_magical -Variable which is setup by C to indicate which of an -XSUB's aliases was used to invoke it. See L. +Turns on the magical status of an SV. See C. - I32 ix + void mg_magical(SV* sv) =for hackers -Found in file XSUB.h +Found in file mg.c -=item LEAVE +=item mg_set -Closing bracket on a callback. See C and L. +Do magic after a value is assigned to the SV. See C. - LEAVE; + int mg_set(SV* sv) =for hackers -Found in file scope.h +Found in file mg.c -=item load_module +=item SvGETMAGIC -Loads the module whose name is pointed to by the string part of name. -Note that the actual module name, not its filename, should be given. -Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of -PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS -(or 0 for no flags). ver, if specified, provides version semantics -similar to C. The optional trailing SV* -arguments can be used to specify arguments to the module's import() -method, similar to C. +Invokes C on an SV if it has 'get' magic. This macro evaluates its +argument more than once. - void load_module(U32 flags, SV* name, SV* ver, ...) + void SvGETMAGIC(SV* sv) =for hackers -Found in file op.c - -=item looks_like_number - -Test if the content of an SV looks like a number (or is a number). -C and C are treated as numbers (so will not issue a -non-numeric warning), even if your atof() doesn't grok them. - - I32 looks_like_number(SV* sv) +Found in file sv.h -=for hackers -Found in file sv.c +=item SvLOCK -=item MARK +Arranges for a mutual exclusion lock to be obtained on sv if a suitable module +has been loaded. -Stack marker variable for the XSUB. See C. + void SvLOCK(SV* sv) =for hackers -Found in file pp.h +Found in file sv.h -=item mg_clear +=item SvSETMAGIC -Clear something magical that the SV represents. See C. +Invokes C on an SV if it has 'set' magic. This macro evaluates its +argument more than once. - int mg_clear(SV* sv) + void SvSETMAGIC(SV* sv) =for hackers -Found in file mg.c +Found in file sv.h -=item mg_copy +=item SvSetMagicSV -Copies the magic from one SV to another. See C. +Like C, but does any set magic required afterwards. - int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) + void SvSetMagicSV(SV* dsb, SV* ssv) =for hackers -Found in file mg.c +Found in file sv.h -=item mg_find +=item SvSetMagicSV_nosteal -Finds the magic pointer for type matching the SV. See C. +Like C, but does any set magic required afterwards. - MAGIC* mg_find(SV* sv, int type) + void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) =for hackers -Found in file mg.c +Found in file sv.h -=item mg_free +=item SvSetSV -Free any magic storage used by the SV. See C. +Calls C if dsv is not the same as ssv. May evaluate arguments +more than once. - int mg_free(SV* sv) + void SvSetSV(SV* dsb, SV* ssv) =for hackers -Found in file mg.c +Found in file sv.h -=item mg_get +=item SvSetSV_nosteal -Do magic after a value is retrieved from the SV. See C. +Calls a non-destructive version of C if dsv is not the same as +ssv. May evaluate arguments more than once. - int mg_get(SV* sv) + void SvSetSV_nosteal(SV* dsv, SV* ssv) =for hackers -Found in file mg.c +Found in file sv.h -=item mg_length +=item SvSHARE -Report on the SV's length. See C. +Arranges for sv to be shared between threads if a suitable module +has been loaded. - U32 mg_length(SV* sv) + void SvSHARE(SV* sv) =for hackers -Found in file mg.c +Found in file sv.h -=item mg_magical -Turns on the magical status of an SV. See C. +=back - void mg_magical(SV* sv) +=head1 Memory Management -=for hackers -Found in file mg.c +=over 8 -=item mg_set +=item Copy -Do magic after a value is assigned to the SV. See C. +The XSUB-writer's interface to the C C function. The C is the +source, C is the destination, C is the number of items, and C is +the type. May fail on overlapping copies. See also C. - int mg_set(SV* sv) + void Copy(void* src, void* dest, int nitems, type) =for hackers -Found in file mg.c +Found in file handy.h =item Move @@ -1286,371 +1412,481 @@ The XSUB-writer's interface to the C C function. =for hackers Found in file handy.h -=item newAV +=item Newc -Creates a new AV. The reference count is set to 1. +The XSUB-writer's interface to the C C function, with +cast. - AV* newAV() + void Newc(int id, void* ptr, int nitems, type, cast) =for hackers -Found in file av.c +Found in file handy.h -=item Newc +=item NEWSV -The XSUB-writer's interface to the C C function, with -cast. +Creates a new SV. A non-zero C parameter indicates the number of +bytes of preallocated string space the SV should have. An extra byte for a +tailing NUL is also reserved. (SvPOK is not set for the SV even if string +space is allocated.) The reference count for the new SV is set to 1. +C is an integer id between 0 and 1299 (used to identify leaks). - void Newc(int id, void* ptr, int nitems, type, cast) + + SV* NEWSV(int id, STRLEN len) =for hackers Found in file handy.h -=item newCONSTSUB +=item Newz -Creates a constant sub equivalent to Perl C which is -eligible for inlining at compile-time. +The XSUB-writer's interface to the C C function. The allocated +memory is zeroed with C. - CV* newCONSTSUB(HV* stash, char* name, SV* sv) + void Newz(int id, void* ptr, int nitems, type) =for hackers -Found in file op.c +Found in file handy.h -=item newHV +=item Renew -Creates a new HV. The reference count is set to 1. +The XSUB-writer's interface to the C C function. - HV* newHV() + void Renew(void* ptr, int nitems, type) =for hackers -Found in file hv.c +Found in file handy.h -=item newRV_inc +=item Renewc -Creates an RV wrapper for an SV. The reference count for the original SV is -incremented. +The XSUB-writer's interface to the C C function, with +cast. - SV* newRV_inc(SV* sv) + void Renewc(void* ptr, int nitems, type, cast) =for hackers -Found in file sv.h +Found in file handy.h -=item newRV_noinc +=item Safefree -Creates an RV wrapper for an SV. The reference count for the original -SV is B incremented. +The XSUB-writer's interface to the C C function. - SV* newRV_noinc(SV *sv) + void Safefree(void* ptr) =for hackers -Found in file sv.c +Found in file handy.h -=item newSV +=item savepv -Create a new null SV, or if len > 0, create a new empty SVt_PV type SV -with an initial PV allocation of len+1. Normally accessed via the C -macro. +Copy a string to a safe spot. This does not use an SV. - SV* newSV(STRLEN len) + char* savepv(const char* sv) =for hackers -Found in file sv.c +Found in file util.c -=item NEWSV +=item savepvn -Creates a new SV. A non-zero C parameter indicates the number of -bytes of preallocated string space the SV should have. An extra byte for a -tailing NUL is also reserved. (SvPOK is not set for the SV even if string -space is allocated.) The reference count for the new SV is set to 1. -C is an integer id between 0 and 1299 (used to identify leaks). +Copy a string to a safe spot. The C indicates number of bytes to +copy. If pointer is NULL allocate space for a string of size specified. +This does not use an SV. - SV* NEWSV(int id, STRLEN len) + char* savepvn(const char* sv, I32 len) =for hackers -Found in file handy.h +Found in file util.c -=item newSViv +=item savesharedpv -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. +Copy a string to a safe spot in memory shared between threads. +This does not use an SV. - SV* newSViv(IV i) + char* savesharedpv(const char* sv) =for hackers -Found in file sv.c +Found in file util.c -=item newSVnv +=item StructCopy -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. +This is an architecture-independent macro to copy one structure to another. - SV* newSVnv(NV n) + void StructCopy(type src, type dest, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVpv +=item Zero -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. If C is zero, Perl will compute the length using -strlen(). For efficiency, consider using C instead. +The XSUB-writer's interface to the C C function. The C is the +destination, C is the number of items, and C is the type. - SV* newSVpv(const char* s, STRLEN len) + void Zero(void* dest, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVpvf -Creates a new SV and initializes it with the string formatted like -C. +=back - SV* newSVpvf(const char* pat, ...) +=head1 Miscellaneous Functions + +=over 8 + +=item fbm_compile + +Analyses the string in order to make fast searches on it using fbm_instr() +-- the Boyer-Moore algorithm. + + void fbm_compile(SV* sv, U32 flags) =for hackers -Found in file sv.c +Found in file util.c -=item newSVpvn +=item fbm_instr -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C bytes long. +Returns the location of the SV in the string delimited by C and +C. It returns C if the string can't be found. The C +does not have to be fbm_compiled, but the search will not be as fast +then. - SV* newSVpvn(const char* s, STRLEN len) + char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) =for hackers -Found in file sv.c +Found in file util.c -=item newSVpvn_share +=item form -Creates a new SV with its SvPVX pointing to a shared string in the string -table. If the string does not already exist in the table, it is created -first. Turns on READONLY and FAKE. The string's hash is stored in the UV -slot of the SV; if the C parameter is non-zero, that value is used; -otherwise the hash is computed. The idea here is that as the string table -is used for shared hash keys these strings will have SvPVX == HeKEY and -hash lookup will avoid string compare. +Takes a sprintf-style format pattern and conventional +(non-SV) arguments and returns the formatted string. - SV* newSVpvn_share(const char* s, I32 len, U32 hash) + (char *) Perl_form(pTHX_ const char* pat, ...) + +can be used any place a string (char *) is required: + + char * s = Perl_form("%d.%d",major,minor); + +Uses a single private buffer so if you want to format several strings you +must explicitly copy the earlier strings away (and free the copies when you +are done). + + char* form(const char* pat, ...) =for hackers -Found in file sv.c +Found in file util.c -=item newSVrv +=item getcwd_sv -Creates a new SV for the RV, C, to point to. If C is not an RV then -it will be upgraded to one. If C is non-null then the new SV will -be blessed in the specified package. The new SV is returned and its -reference count is 1. +Fill the sv with current working directory - SV* newSVrv(SV* rv, const char* classname) + int getcwd_sv(SV* sv) =for hackers -Found in file sv.c +Found in file util.c -=item newSVsv +=item strEQ -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). +Test two strings to see if they are equal. Returns true or false. - SV* newSVsv(SV* old) + bool strEQ(char* s1, char* s2) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVuv +=item strGE -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. +Test two strings to see if the first, C, is greater than or equal to +the second, C. Returns true or false. - SV* newSVuv(UV u) + bool strGE(char* s1, char* s2) =for hackers -Found in file sv.c +Found in file handy.h -=item newXS +=item strGT -Used by C to hook up XSUBs as Perl subs. +Test two strings to see if the first, C, is greater than the second, +C. Returns true or false. + + bool strGT(char* s1, char* s2) =for hackers -Found in file op.c +Found in file handy.h -=item newXSproto +=item strLE -Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to -the subs. +Test two strings to see if the first, C, is less than or equal to the +second, C. Returns true or false. + + bool strLE(char* s1, char* s2) =for hackers -Found in file XSUB.h +Found in file handy.h -=item Newz +=item strLT -The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. +Test two strings to see if the first, C, is less than the second, +C. Returns true or false. - void Newz(int id, void* ptr, int nitems, type) + bool strLT(char* s1, char* s2) =for hackers Found in file handy.h -=item Nullav +=item strNE -Null AV pointer. +Test two strings to see if they are different. Returns true or +false. + + bool strNE(char* s1, char* s2) =for hackers -Found in file av.h +Found in file handy.h -=item Nullch +=item strnEQ -Null character pointer. +Test two strings to see if they are equal. The C parameter indicates +the number of bytes to compare. Returns true or false. (A wrapper for +C). + + bool strnEQ(char* s1, char* s2, STRLEN len) =for hackers Found in file handy.h -=item Nullcv +=item strnNE -Null CV pointer. +Test two strings to see if they are different. The C parameter +indicates the number of bytes to compare. Returns true or false. (A +wrapper for C). + + bool strnNE(char* s1, char* s2, STRLEN len) =for hackers -Found in file cv.h +Found in file handy.h -=item Nullhv -Null HV pointer. +=back + +=head1 Numeric functions + +=over 8 + +=item grok_bin + +converts a string representing a binary number to numeric form. + +On entry I and I<*len> give the string to scan, I<*flags> gives +conversion flags, and I should be NULL or a pointer to an NV. +The scan stops at the end of the string, or the first invalid character. +On return I<*len> is set to the length scanned string, and I<*flags> gives +output flags. + +If the value is <= UV_MAX it is returned as a UV, the output flags are clear, +and nothing is written to I<*result>. If the value is > UV_MAX C +returns UV_MAX, sets C in the output flags, +and writes the value to I<*result> (or the value is discarded if I +is NULL). + +The hex number may optionally be prefixed with "0b" or "b" unless +C is set in I<*flags> on entry. If +C is set in I<*flags> then the binary +number may use '_' characters to separate digits. + + UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file hv.h +Found in file numeric.c -=item Nullsv +=item grok_hex -Null SV pointer. +converts a string representing a hex number to numeric form. + +On entry I and I<*len> give the string to scan, I<*flags> gives +conversion flags, and I should be NULL or a pointer to an NV. +The scan stops at the end of the string, or the first non-hex-digit character. +On return I<*len> is set to the length scanned string, and I<*flags> gives +output flags. + +If the value is <= UV_MAX it is returned as a UV, the output flags are clear, +and nothing is written to I<*result>. If the value is > UV_MAX C +returns UV_MAX, sets C in the output flags, +and writes the value to I<*result> (or the value is discarded if I +is NULL). + +The hex number may optionally be prefixed with "0x" or "x" unless +C is set in I<*flags> on entry. If +C is set in I<*flags> then the hex +number may use '_' characters to separate digits. + + UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file handy.h +Found in file numeric.c -=item ORIGMARK +=item grok_number -The original stack mark for the XSUB. See C. +Recognise (or not) a number. The type of the number is returned +(0 if unrecognised), otherwise it is a bit-ORed combination of +IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, +IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). + +If the value of the number can fit an in UV, it is returned in the *valuep +IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV +will never be set unless *valuep is valid, but *valuep may have been assigned +to during processing even though IS_NUMBER_IN_UV is not set on return. +If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when +valuep is non-NULL, but no actual assignment (or SEGV) will occur. + +IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were +seen (in which case *valuep gives the true value truncated to an integer), and +IS_NUMBER_NEG if the number is negative (in which case *valuep holds the +absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the +number is larger than a UV. + + int grok_number(const char *pv, STRLEN len, UV *valuep) =for hackers -Found in file pp.h +Found in file numeric.c -=item perl_alloc +=item grok_numeric_radix -Allocates a new Perl interpreter. See L. +Scan and skip for a numeric decimal separator (radix). - PerlInterpreter* perl_alloc() + bool grok_numeric_radix(const char **sp, const char *send) =for hackers -Found in file perl.c +Found in file numeric.c -=item perl_clone +=item grok_oct -Create and return a new interpreter by cloning the current one. - PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) + UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file sv.c +Found in file numeric.c -=item perl_construct +=item scan_bin -Initializes a new Perl interpreter. See L. +For backwards compatibility. Use C instead. - void perl_construct(PerlInterpreter* interp) + NV scan_bin(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file perl.c +Found in file numeric.c -=item perl_destruct +=item scan_hex -Shuts down a Perl interpreter. See L. +For backwards compatibility. Use C instead. - void perl_destruct(PerlInterpreter* interp) + NV scan_hex(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file perl.c +Found in file numeric.c -=item perl_free +=item scan_oct -Releases a Perl interpreter. See L. +For backwards compatibility. Use C instead. - void perl_free(PerlInterpreter* interp) + NV scan_oct(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file perl.c +Found in file numeric.c -=item perl_parse -Tells a Perl interpreter to parse a Perl script. See L. +=back - int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) +=head1 Optree Manipulation Functions + +=over 8 + +=item cv_const_sv + +If C is a constant sub eligible for inlining. returns the constant +value returned by the sub. Otherwise, returns NULL. + +Constant subs can be created with C or as described in +L. + + SV* cv_const_sv(CV* cv) =for hackers -Found in file perl.c +Found in file op.c -=item perl_run +=item newCONSTSUB -Tells a Perl interpreter to run. See L. +Creates a constant sub equivalent to Perl C which is +eligible for inlining at compile-time. - int perl_run(PerlInterpreter* interp) + CV* newCONSTSUB(HV* stash, char* name, SV* sv) + +=for hackers +Found in file op.c + +=item newXS + +Used by C to hook up XSUBs as Perl subs. + +=for hackers +Found in file op.c + + +=back + +=head1 Stack Manipulation Macros + +=over 8 + +=item dMARK + +Declare a stack marker variable, C, for the XSUB. See C and +C. + + dMARK; =for hackers -Found in file perl.c +Found in file pp.h -=item PL_modglobal +=item dORIGMARK -C is a general purpose, interpreter global HV for use by -extensions that need to keep information on a per-interpreter basis. -In a pinch, it can also be used as a symbol table for extensions -to share data among each other. It is a good idea to use keys -prefixed by the package name of the extension that owns the data. +Saves the original stack mark for the XSUB. See C. - HV* PL_modglobal + dORIGMARK; =for hackers -Found in file intrpvar.h +Found in file pp.h -=item PL_na +=item dSP -A convenience variable which is typically used with C when one -doesn't care about the length of the string. It is usually more efficient -to either declare a local variable and use that instead or to use the -C macro. +Declares a local copy of perl's stack pointer for the XSUB, available via +the C macro. See C. - STRLEN PL_na + dSP; =for hackers -Found in file thrdvar.h +Found in file pp.h -=item PL_sv_no +=item EXTEND -This is the C SV. See C. Always refer to this as -C<&PL_sv_no>. +Used to extend the argument stack for an XSUB's return values. Once +used, guarantees that there is room for at least C to be pushed +onto the stack. - SV PL_sv_no + void EXTEND(SP, int nitems) =for hackers -Found in file intrpvar.h - -=item PL_sv_undef +Found in file pp.h -This is the C SV. Always refer to this as C<&PL_sv_undef>. +=item MARK - SV PL_sv_undef +Stack marker variable for the XSUB. See C. =for hackers -Found in file intrpvar.h - -=item PL_sv_yes +Found in file pp.h -This is the C SV. See C. Always refer to this as -C<&PL_sv_yes>. +=item ORIGMARK - SV PL_sv_yes +The original stack mark for the XSUB. See C. =for hackers -Found in file intrpvar.h +Found in file pp.h =item POPi @@ -1789,266 +2025,441 @@ See C and L for other uses. =for hackers Found in file pp.h -=item Renew +=item SP -The XSUB-writer's interface to the C C function. +Stack pointer. This is usually handled by C. See C and +C. - void Renew(void* ptr, int nitems, type) +=for hackers +Found in file pp.h + +=item SPAGAIN + +Refetch the stack pointer. Used after a callback. See L. + + SPAGAIN; =for hackers -Found in file handy.h +Found in file pp.h -=item Renewc +=item XPUSHi -The XSUB-writer's interface to the C C function, with -cast. +Push an integer onto the stack, extending the stack if necessary. Handles +'set' magic. See C. - void Renewc(void* ptr, int nitems, type, cast) + void XPUSHi(IV iv) =for hackers -Found in file handy.h +Found in file pp.h -=item require_pv +=item XPUSHn -Tells Perl to C the file named by the string argument. It is -analogous to the Perl code C. It's even -implemented that way; consider using Perl_load_module instead. +Push a double onto the stack, extending the stack if necessary. Handles +'set' magic. See C. -NOTE: the perl_ form of this function is deprecated. + void XPUSHn(NV nv) - void require_pv(const char* pv) +=for hackers +Found in file pp.h + +=item XPUSHp + +Push a string onto the stack, extending the stack if necessary. The C +indicates the length of the string. Handles 'set' magic. See +C. + + void XPUSHp(char* str, STRLEN len) =for hackers -Found in file perl.c +Found in file pp.h -=item RETVAL +=item XPUSHs -Variable which is setup by C to hold the return value for an -XSUB. This is always the proper type for the XSUB. See -L. +Push an SV onto the stack, extending the stack if necessary. Does not +handle 'set' magic. See C. + + void XPUSHs(SV* sv) + +=for hackers +Found in file pp.h + +=item XPUSHu + +Push an unsigned integer onto the stack, extending the stack if necessary. +See C. + + void XPUSHu(UV uv) + +=for hackers +Found in file pp.h + +=item XSRETURN + +Return from XSUB, indicating number of items on the stack. This is usually +handled by C. + + void XSRETURN(int nitems) + +=for hackers +Found in file XSUB.h + +=item XSRETURN_IV + +Return an integer from an XSUB immediately. Uses C. + + void XSRETURN_IV(IV iv) + +=for hackers +Found in file XSUB.h + +=item XSRETURN_NO + +Return C<&PL_sv_no> from an XSUB immediately. Uses C. + + XSRETURN_NO; + +=for hackers +Found in file XSUB.h + +=item XSRETURN_NV + +Return a double from an XSUB immediately. Uses C. + + void XSRETURN_NV(NV nv) + +=for hackers +Found in file XSUB.h + +=item XSRETURN_PV + +Return a copy of a string from an XSUB immediately. Uses C. + + void XSRETURN_PV(char* str) + +=for hackers +Found in file XSUB.h + +=item XSRETURN_UNDEF + +Return C<&PL_sv_undef> from an XSUB immediately. Uses C. + + XSRETURN_UNDEF; + +=for hackers +Found in file XSUB.h + +=item XSRETURN_YES + +Return C<&PL_sv_yes> from an XSUB immediately. Uses C. + + XSRETURN_YES; + +=for hackers +Found in file XSUB.h + +=item XST_mIV + +Place an integer into the specified position C on the stack. The +value is stored in a new mortal SV. + + void XST_mIV(int pos, IV iv) + +=for hackers +Found in file XSUB.h + +=item XST_mNO + +Place C<&PL_sv_no> into the specified position C on the +stack. + + void XST_mNO(int pos) + +=for hackers +Found in file XSUB.h + +=item XST_mNV + +Place a double into the specified position C on the stack. The value +is stored in a new mortal SV. + + void XST_mNV(int pos, NV nv) + +=for hackers +Found in file XSUB.h + +=item XST_mPV + +Place a copy of a string into the specified position C on the stack. +The value is stored in a new mortal SV. + + void XST_mPV(int pos, char* str) + +=for hackers +Found in file XSUB.h + +=item XST_mUNDEF + +Place C<&PL_sv_undef> into the specified position C on the +stack. + + void XST_mUNDEF(int pos) + +=for hackers +Found in file XSUB.h + +=item XST_mYES + +Place C<&PL_sv_yes> into the specified position C on the +stack. + + void XST_mYES(int pos) + +=for hackers +Found in file XSUB.h + + +=back + +=head1 SV Flags + +=over 8 + +=item svtype - (whatever) RETVAL +An enum of flags for Perl types. These are found in the file B +in the C enum. Test these flags with the C macro. =for hackers -Found in file XSUB.h - -=item Safefree +Found in file sv.h -The XSUB-writer's interface to the C C function. +=item SVt_IV - void Safefree(void* ptr) +Integer type flag for scalars. See C. =for hackers -Found in file handy.h - -=item savepv +Found in file sv.h -Copy a string to a safe spot. This does not use an SV. +=item SVt_NV - char* savepv(const char* sv) +Double type flag for scalars. See C. =for hackers -Found in file util.c - -=item savepvn +Found in file sv.h -Copy a string to a safe spot. The C indicates number of bytes to -copy. This does not use an SV. +=item SVt_PV - char* savepvn(const char* sv, I32 len) +Pointer type flag for scalars. See C. =for hackers -Found in file util.c - -=item SAVETMPS +Found in file sv.h -Opening bracket for temporaries on a callback. See C and -L. +=item SVt_PVAV - SAVETMPS; +Type flag for arrays. See C. =for hackers -Found in file scope.h - -=item sharedsv_find +Found in file sv.h -Tries to find if a given SV has a shared backend, either by -looking at magic, or by checking if it is tied again threads::shared. +=item SVt_PVCV - shared_sv* sharedsv_find(SV* sv) +Type flag for code refs. See C. =for hackers -Found in file sharedsv.c - -=item sharedsv_init +Found in file sv.h -Saves a space for keeping SVs wider than an interpreter, -currently only stores a pointer to the first interpreter. +=item SVt_PVHV - void sharedsv_init() +Type flag for hashes. See C. =for hackers -Found in file sharedsv.c +Found in file sv.h -=item sharedsv_lock +=item SVt_PVMG -Recursive locks on a sharedsv. -Locks are dynamicly scoped at the level of the first lock. - void sharedsv_lock(shared_sv* ssv) +Type flag for blessed scalars. See C. =for hackers -Found in file sharedsv.c +Found in file sv.h -=item sharedsv_new -Allocates a new shared sv struct, you must yourself create the SV/AV/HV. - shared_sv* sharedsv_new() +=back -=for hackers -Found in file sharedsv.c +=head1 SV Manipulation Functions + +=over 8 -=item sharedsv_thrcnt_dec +=item get_sv + +Returns the SV of the specified Perl scalar. If C is set and the +Perl variable does not exist then it will be created. If C is not +set and the variable does not exist then NULL is returned. -Decrements the threadcount of a shared sv. When a threads frontend is freed -this function should be called. +NOTE: the perl_ form of this function is deprecated. - void sharedsv_thrcnt_dec(shared_sv* ssv) + SV* get_sv(const char* name, I32 create) =for hackers -Found in file sharedsv.c +Found in file perl.c -=item sharedsv_thrcnt_inc +=item looks_like_number + +Test if the content of an SV looks like a number (or is a number). +C and C are treated as numbers (so will not issue a +non-numeric warning), even if your atof() doesn't grok them. -Increments the threadcount of a sharedsv. - void sharedsv_thrcnt_inc(shared_sv* ssv) + I32 looks_like_number(SV* sv) =for hackers -Found in file sharedsv.c +Found in file sv.c -=item sharedsv_unlock +=item newRV_inc -Recursively unlocks a shared sv. +Creates an RV wrapper for an SV. The reference count for the original SV is +incremented. - void sharedsv_unlock(shared_sv* ssv) + SV* newRV_inc(SV* sv) =for hackers -Found in file sharedsv.c +Found in file sv.h -=item SP +=item newRV_noinc -Stack pointer. This is usually handled by C. See C and -C. +Creates an RV wrapper for an SV. The reference count for the original +SV is B incremented. + + SV* newRV_noinc(SV *sv) =for hackers -Found in file pp.h +Found in file sv.c -=item SPAGAIN +=item newSV -Refetch the stack pointer. Used after a callback. See L. +Create a new null SV, or if len > 0, create a new empty SVt_PV type SV +with an initial PV allocation of len+1. Normally accessed via the C +macro. - SPAGAIN; + SV* newSV(STRLEN len) =for hackers -Found in file pp.h +Found in file sv.c -=item ST +=item newSViv -Used to access elements on the XSUB's stack. +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. - SV* ST(int ix) + SV* newSViv(IV i) =for hackers -Found in file XSUB.h +Found in file sv.c -=item strEQ +=item newSVnv -Test two strings to see if they are equal. Returns true or false. +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. - bool strEQ(char* s1, char* s2) + SV* newSVnv(NV n) =for hackers -Found in file handy.h +Found in file sv.c -=item strGE +=item newSVpv -Test two strings to see if the first, C, is greater than or equal to -the second, C. Returns true or false. +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. If C is zero, Perl will compute the length using +strlen(). For efficiency, consider using C instead. - bool strGE(char* s1, char* s2) + SV* newSVpv(const char* s, STRLEN len) =for hackers -Found in file handy.h +Found in file sv.c -=item strGT +=item newSVpvf -Test two strings to see if the first, C, is greater than the second, -C. Returns true or false. +Creates a new SV and initializes it with the string formatted like +C. - bool strGT(char* s1, char* s2) + SV* newSVpvf(const char* pat, ...) =for hackers -Found in file handy.h +Found in file sv.c -=item strLE +=item newSVpvn -Test two strings to see if the first, C, is less than or equal to the -second, C. Returns true or false. +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. Note that if C is zero, Perl will create a zero length +string. You are responsible for ensuring that the source string is at least +C bytes long. - bool strLE(char* s1, char* s2) + SV* newSVpvn(const char* s, STRLEN len) =for hackers -Found in file handy.h +Found in file sv.c -=item strLT +=item newSVpvn_share -Test two strings to see if the first, C, is less than the second, -C. Returns true or false. +Creates a new SV with its SvPVX pointing to a shared string in the string +table. If the string does not already exist in the table, it is created +first. Turns on READONLY and FAKE. The string's hash is stored in the UV +slot of the SV; if the C parameter is non-zero, that value is used; +otherwise the hash is computed. The idea here is that as the string table +is used for shared hash keys these strings will have SvPVX == HeKEY and +hash lookup will avoid string compare. - bool strLT(char* s1, char* s2) + SV* newSVpvn_share(const char* s, I32 len, U32 hash) =for hackers -Found in file handy.h +Found in file sv.c -=item strNE +=item newSVrv -Test two strings to see if they are different. Returns true or -false. +Creates a new SV for the RV, C, to point to. If C is not an RV then +it will be upgraded to one. If C is non-null then the new SV will +be blessed in the specified package. The new SV is returned and its +reference count is 1. - bool strNE(char* s1, char* s2) + SV* newSVrv(SV* rv, const char* classname) =for hackers -Found in file handy.h +Found in file sv.c -=item strnEQ +=item newSVsv -Test two strings to see if they are equal. The C parameter indicates -the number of bytes to compare. Returns true or false. (A wrapper for -C). +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). - bool strnEQ(char* s1, char* s2, STRLEN len) + SV* newSVsv(SV* old) =for hackers -Found in file handy.h +Found in file sv.c -=item strnNE +=item newSVuv -Test two strings to see if they are different. The C parameter -indicates the number of bytes to compare. Returns true or false. (A -wrapper for C). +Creates a new SV and copies an unsigned integer into it. +The reference count for the SV is set to 1. - bool strnNE(char* s1, char* s2, STRLEN len) + SV* newSVuv(UV u) =for hackers -Found in file handy.h +Found in file sv.c -=item StructCopy +=item new_vstring -This is an architecture-independent macro to copy one structure to another. +Returns a pointer to the next character after the parsed +vstring, as well as updating the passed in sv. - void StructCopy(type src, type dest, type) +Function must be called like + + sv = NEWSV(92,5); + s = new_vstring(s,sv); + +The sv must already be large enough to store the vstring +passed in. + + char* new_vstring(char *vstr, SV *sv) =for hackers -Found in file handy.h +Found in file util.c =item SvCUR @@ -2078,21 +2489,11 @@ See C. Access the character as *(SvEND(sv)). =for hackers Found in file sv.h -=item SvGETMAGIC - -Invokes C on an SV if it has 'get' magic. This macro evaluates its -argument more than once. - - void SvGETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - =item SvGROW Expands the character buffer in the SV so that it has room for the indicated number of bytes (remember to reserve space for an extra trailing -NUL character). Calls C to perform the expansion if necessary. +NUL character). Calls C to perform the expansion if necessary. Returns a pointer to the character buffer. char * SvGROW(SV* sv, STRLEN len) @@ -2121,7 +2522,7 @@ Found in file sv.h =item SvIOK_notUV -Returns a boolean indicating whether the SV contains an signed integer. +Returns a boolean indicating whether the SV contains a signed integer. void SvIOK_notUV(SV* sv) @@ -2196,7 +2597,7 @@ Found in file sv.h =item SvIVx Coerces the given SV to an integer and returns it. Guarantees to evaluate -sv only once. Use the more efficent C otherwise. +sv only once. Use the more efficient C otherwise. IV SvIVx(SV* sv) @@ -2301,7 +2702,7 @@ Found in file sv.h =item SvNVx Coerces the given SV to a double and returns it. Guarantees to evaluate -sv only once. Use the more efficent C otherwise. +sv only once. Use the more efficient C otherwise. NV SvNVx(SV* sv) @@ -2399,8 +2800,9 @@ Found in file sv.h =item SvPV -Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. Handles 'get' magic. See also +Returns a pointer to the string in the SV, or a stringified form of +the SV if the SV does not contain a string. The SV may cache the +stringified version becoming C. Handles 'get' magic. See also C for a version which guarantees to evaluate sv only once. char* SvPV(SV* sv, STRLEN len) @@ -2420,7 +2822,7 @@ Found in file sv.h =item SvPVbytex Like C, but converts sv to byte representation first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Guarantees to evaluate sv only once; use the more efficient C otherwise. @@ -2432,7 +2834,7 @@ Found in file sv.h =item SvPVbytex_force Like C, but converts sv to byte representation first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Guarantees to evaluate sv only once; use the more efficient C otherwise. char* SvPVbytex_force(SV* sv, STRLEN len) @@ -2453,14 +2855,14 @@ Found in file sv.h Like C, but converts sv to byte representation first if necessary. - char* SvPVbyte_nolen(SV* sv, STRLEN len) + char* SvPVbyte_nolen(SV* sv) =for hackers Found in file sv.h =item SvPVutf8 -Like C, but converts sv to uft8 first if necessary. +Like C, but converts sv to utf8 first if necessary. char* SvPVutf8(SV* sv, STRLEN len) @@ -2469,8 +2871,8 @@ Found in file sv.h =item SvPVutf8x -Like C, but converts sv to uft8 first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Like C, but converts sv to utf8 first if necessary. +Guarantees to evaluate sv only once; use the more efficient C otherwise. char* SvPVutf8x(SV* sv, STRLEN len) @@ -2480,8 +2882,8 @@ Found in file sv.h =item SvPVutf8x_force -Like C, but converts sv to uft8 first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Like C, but converts sv to utf8 first if necessary. +Guarantees to evaluate sv only once; use the more efficient C otherwise. char* SvPVutf8x_force(SV* sv, STRLEN len) @@ -2491,7 +2893,7 @@ Found in file sv.h =item SvPVutf8_force -Like C, but converts sv to uft8 first if necessary. +Like C, but converts sv to utf8 first if necessary. char* SvPVutf8_force(SV* sv, STRLEN len) @@ -2500,9 +2902,9 @@ Found in file sv.h =item SvPVutf8_nolen -Like C, but converts sv to uft8 first if necessary. +Like C, but converts sv to utf8 first if necessary. - char* SvPVutf8_nolen(SV* sv, STRLEN len) + char* SvPVutf8_nolen(SV* sv) =for hackers Found in file sv.h @@ -2528,8 +2930,9 @@ Found in file sv.h =item SvPV_force -Like but will force the SV into becoming a string (SvPOK). You want -force if you are going to update the SvPVX directly. +Like C but will force the SV into containing just a string +(C). You want force if you are going to update the C +directly. char* SvPV_force(SV* sv, STRLEN len) @@ -2538,8 +2941,9 @@ Found in file sv.h =item SvPV_force_nomg -Like but will force the SV into becoming a string (SvPOK). You want -force if you are going to update the SvPVX directly. Doesn't process magic. +Like C but will force the SV into containing just a string +(C). You want force if you are going to update the C +directly. Doesn't process magic. char* SvPV_force_nomg(SV* sv, STRLEN len) @@ -2548,8 +2952,9 @@ Found in file sv.h =item SvPV_nolen -Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. Handles 'get' magic. +Returns a pointer to the string in the SV, or a stringified form of +the SV if the SV does not contain a string. The SV may cache the +stringified form becoming C. Handles 'get' magic. char* SvPV_nolen(SV* sv) @@ -2560,109 +2965,61 @@ Found in file sv.h Returns the value of the object's reference count. - U32 SvREFCNT(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_dec - -Decrements the reference count of the given SV. - - void SvREFCNT_dec(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc - -Increments the reference count of the given SV. - - SV* SvREFCNT_inc(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK - -Tests if the SV is an RV. - - bool SvROK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK_off - -Unsets the RV status of an SV. - - void SvROK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK_on - -Tells an SV that it is an RV. - - void SvROK_on(SV* sv) + U32 SvREFCNT(SV* sv) =for hackers Found in file sv.h -=item SvRV +=item SvREFCNT_dec -Dereferences an RV to return the SV. +Decrements the reference count of the given SV. - SV* SvRV(SV* sv) + void SvREFCNT_dec(SV* sv) =for hackers Found in file sv.h -=item SvSETMAGIC +=item SvREFCNT_inc -Invokes C on an SV if it has 'set' magic. This macro evaluates its -argument more than once. +Increments the reference count of the given SV. - void SvSETMAGIC(SV* sv) + SV* SvREFCNT_inc(SV* sv) =for hackers Found in file sv.h -=item SvSetMagicSV +=item SvROK -Like C, but does any set magic required afterwards. +Tests if the SV is an RV. - void SvSetMagicSV(SV* dsb, SV* ssv) + bool SvROK(SV* sv) =for hackers Found in file sv.h -=item SvSetMagicSV_nosteal +=item SvROK_off -Like C, but does any set magic required afterwards. +Unsets the RV status of an SV. - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) + void SvROK_off(SV* sv) =for hackers Found in file sv.h -=item SvSetSV +=item SvROK_on -Calls C if dsv is not the same as ssv. May evaluate arguments -more than once. +Tells an SV that it is an RV. - void SvSetSV(SV* dsb, SV* ssv) + void SvROK_on(SV* sv) =for hackers Found in file sv.h -=item SvSetSV_nosteal +=item SvRV -Calls a non-destructive version of C if dsv is not the same as -ssv. May evaluate arguments more than once. +Dereferences an RV to return the SV. - void SvSetSV_nosteal(SV* dsv, SV* ssv) + SV* SvRV(SV* sv) =for hackers Found in file sv.h @@ -2728,14 +3085,6 @@ false, defined or undefined. Does not handle 'get' magic. =for hackers Found in file sv.h -=item svtype - -An enum of flags for Perl types. These are found in the file B -in the C enum. Test these flags with the C macro. - -=for hackers -Found in file sv.h - =item SvTYPE Returns the type of the SV. See C. @@ -2745,51 +3094,13 @@ Returns the type of the SV. See C. =for hackers Found in file sv.h -=item SVt_IV - -Integer type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_NV - -Double type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_PV - -Pointer type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVAV - -Type flag for arrays. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVCV - -Type flag for code refs. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVHV - -Type flag for hashes. See C. +=item SvUNLOCK -=for hackers -Found in file sv.h +Releases a mutual exclusion lock on sv if a suitable module +has been loaded. -=item SVt_PVMG -Type flag for blessed scalars. See C. + void SvUNLOCK(SV* sv) =for hackers Found in file sv.h @@ -2864,7 +3175,7 @@ Found in file sv.h =item SvUVx Coerces the given SV to an unsigned integer and returns it. Guarantees to -evaluate sv only once. Use the more efficent C otherwise. +evaluate sv only once. Use the more efficient C otherwise. UV SvUVx(SV* sv) @@ -2874,7 +3185,7 @@ Found in file sv.h =item sv_2bool This function is only called on magical items, and is only used by -sv_true() or its macro equivalent. +sv_true() or its macro equivalent. bool sv_2bool(SV* sv) @@ -3212,6 +3523,21 @@ settings. =for hackers Found in file sv.c +=item sv_copypv + +Copies a stringified representation of the source SV into the +destination SV. Automatically performs any necessary mg_get and +coercion of numeric values into strings. Guaranteed to preserve +UTF-8 flag even from overloaded objects. Similar in nature to +sv_2pv[_flags] but operates directly on an SV instead of just the +string. Mostly uses sv_2pv_flags to do its work, except when that +would lose the UTF-8'ness of the PV. + + void sv_copypv(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.c + =item sv_dec Auto-decrement of the value in the SV, doing string to numeric conversion @@ -3377,13 +3703,32 @@ Found in file sv.c Adds magic to an SV. First upgrades C to type C if necessary, then adds a new magic item of type C to the head of the magic list. -C is assumed to contain an C if C<(name && namelen == HEf_SVKEY)> - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers Found in file sv.c +=item sv_magicext + +Adds magic to an SV, upgrading it if necessary. Applies the +supplied vtable and returns pointer to the magic added. + +Note that sv_magicext will allow things that sv_magic will not. +In particular you can add magic to SvREADONLY SVs and and more than +one instance of the same 'how' + +I C is greater then zero then a savepvn() I of C is stored, +if C is zero then C is stored as-is and - as another special +case - if C<(name && namelen == HEf_SVKEY)> then C is assumed to contain +an C and has its REFCNT incremented + +(This is now used as a subroutine by sv_magic.) + + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) + +=for hackers +Found in file sv.c + =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). @@ -3418,6 +3763,39 @@ instead. =for hackers Found in file sv.c +=item sv_nolocking + +Dummy routine which "locks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nolocking(SV *) + +=for hackers +Found in file util.c + +=item sv_nosharing + +Dummy routine which "shares" an SV when there is no sharing module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nosharing(SV *) + +=for hackers +Found in file util.c + +=item sv_nounlocking + +Dummy routine which "unlocks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nounlocking(SV *) + +=for hackers +Found in file util.c + =item sv_nv A private implementation of the C macro for compilers which can't @@ -4001,6 +4379,9 @@ This may not be possible if the PV contains non-byte encoding characters; if this is the case, either returns false or, if C is not true, croaks. +This is not as a general purpose Unicode to byte encoding interface: +use the Encode extension for that. + NOTE: this function is experimental and may change or be removed without notice. @@ -4027,6 +4408,9 @@ Forces the SV to string form if it is not already. Always sets the SvUTF8 flag to avoid future validity checks even if all the bytes have hibit clear. +This is not as a general purpose byte encoding to Unicode interface: +use the Encode extension for that. + STRLEN sv_utf8_upgrade(SV *sv) =for hackers @@ -4041,76 +4425,284 @@ if all the bytes have hibit clear. If C has C bit set, will C on C if appropriate, else not. C and C are implemented in terms of this function. +This is not as a general purpose byte encoding to Unicode interface: +use the Encode extension for that. + STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags) =for hackers Found in file sv.c -=item sv_uv +=item sv_uv + +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. + + UV sv_uv(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_vcatpvfn + +Processes its arguments like C and appends the formatted output +to an SV. Uses an array of SVs if the C style variable argument list is +missing (NULL). When running with taint checks enabled, indicates via +C if results are untrustworthy (often due to the use of +locales). + +Usually used via one of its frontends C and C. + + void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + +=for hackers +Found in file sv.c + +=item sv_vsetpvfn + +Works like C but copies the text into the SV instead of +appending it. + +Usually used via one of its frontends C and C. + + void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + +=for hackers +Found in file sv.c + + +=back + +=head1 Unicode Support + +=over 8 + +=item bytes_from_utf8 + +Converts a string C of length C from UTF8 into byte encoding. +Unlike but like C, returns a pointer to +the newly-created string, and updates C to contain the new +length. Returns the original string if no conversion occurs, C +is unchanged. Do nothing if C points to 0. Sets C to +0 if C is converted or contains all 7bit characters. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) + +=for hackers +Found in file utf8.c + +=item bytes_to_utf8 + +Converts a string C of length C from ASCII into UTF8 encoding. +Returns a pointer to the newly-created string, and sets C to +reflect the new length. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* bytes_to_utf8(U8 *s, STRLEN *len) + +=for hackers +Found in file utf8.c + +=item ibcmp_utf8 + +Return true if the strings s1 and s2 differ case-insensitively, false +if not (if they are equal case-insensitively). If u1 is true, the +string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, +the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 +are false, the respective string is assumed to be in native 8-bit +encoding. + +If the pe1 and pe2 are non-NULL, the scanning pointers will be copied +in there (they will point at the beginning of the I character). +If the pointers behind pe1 or pe2 are non-NULL, they are the end +pointers beyond which scanning will not continue under any +circustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and +s2+l2 will be used as goal end pointers that will also stop the scan, +and which qualify towards defining a successful match: all the scans +that define an explicit length must reach their goal pointers for +a match to succeed). + +For case-insensitiveness, the "casefolding" of Unicode is used +instead of upper/lowercasing both the characters, see +http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). + + I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2) + +=for hackers +Found in file utf8.c + +=item is_utf8_char + +Tests if some arbitrary number of bytes begins in a valid UTF-8 +character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character. +The actual number of bytes in the UTF-8 character will be returned if +it is valid, otherwise 0. + + STRLEN is_utf8_char(U8 *p) + +=for hackers +Found in file utf8.c + +=item is_utf8_string + +Returns true if first C bytes of the given string form a valid UTF8 +string, false otherwise. Note that 'a valid UTF8 string' does not mean +'a string that contains UTF8' because a valid ASCII string is a valid +UTF8 string. + + bool is_utf8_string(U8 *s, STRLEN len) + +=for hackers +Found in file utf8.c + +=item pv_uni_display + +Build to the scalar dsv a displayable version of the string spv, +length len, the displayable version being at most pvlim bytes long +(if longer, the rest is truncated and "..." will be appended). + +The flags argument can have UNI_DISPLAY_ISPRINT set to display +isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH +to display the \\[nrfta\\] as the backslashed versions (like '\n') +(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). +UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both +UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on. + +The pointer to the PV of the dsv is returned. + + char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) + +=for hackers +Found in file utf8.c + +=item sv_recode_to_utf8 + +The encoding is assumed to be an Encode object, on entry the PV +of the sv is assumed to be octets in that encoding, and the sv +will be converted into Unicode (and UTF-8). + +If the sv already is UTF-8 (or if it is not POK), or if the encoding +is not a reference, nothing is done to the sv. If the encoding is not +an C Encoding object, bad things will happen. +(See F and L). + +The PV of the sv is returned. + + char* sv_recode_to_utf8(SV* sv, SV *encoding) + +=for hackers +Found in file sv.c + +=item sv_uni_display + +Build to the scalar dsv a displayable version of the scalar sv, +the displayable version being at most pvlim bytes long +(if longer, the rest is truncated and "..." will be appended). + +The flags argument is as in pv_uni_display(). + +The pointer to the PV of the dsv is returned. + + char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) + +=for hackers +Found in file utf8.c + +=item to_utf8_case -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. +The "p" contains the pointer to the UTF-8 string encoding +the character that is being converted. - UV sv_uv(SV* sv) +The "ustrp" is a pointer to the character buffer to put the +conversion result to. The "lenp" is a pointer to the length +of the result. -=for hackers -Found in file sv.c +The "swashp" is a pointer to the swash to use. -=item sv_vcatpvfn +Both the special and normal mappings are stored lib/unicore/To/Foo.pl, +and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually, +but not always, a multicharacter mapping), is tried first. -Processes its arguments like C and appends the formatted output -to an SV. Uses an array of SVs if the C style variable argument list is -missing (NULL). When running with taint checks enabled, indicates via -C if results are untrustworthy (often due to the use of -locales). +The "special" is a string like "utf8::ToSpecLower", which means the +hash %utf8::ToSpecLower. The access to the hash is through +Perl_to_utf8_case(). -Usually used via one of its frontends C and C. +The "normal" is a string like "ToLower" which means the swash +%utf8::ToLower. - void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special) =for hackers -Found in file sv.c +Found in file utf8.c -=item sv_vsetpvfn +=item to_utf8_fold -Works like C but copies the text into the SV instead of -appending it. +Convert the UTF-8 encoded character at p to its foldcase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the +foldcase version may be longer than the original character (up to +three characters). -Usually used via one of its frontends C and C. +The first character of the foldcased version is returned +(but note, as explained above, that there may be more.) - void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers -Found in file sv.c +Found in file utf8.c -=item THIS +=item to_utf8_lower -Variable which is setup by C to designate the object in a C++ -XSUB. This is always the proper type for the C++ object. See C and -L. +Convert the UTF-8 encoded character at p to its lowercase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the +lowercase version may be longer than the original character (up to two +characters). - (whatever) THIS +The first character of the lowercased version is returned +(but note, as explained above, that there may be more.) + + UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers -Found in file XSUB.h +Found in file utf8.c -=item toLOWER +=item to_utf8_title -Converts the specified character to lowercase. +Convert the UTF-8 encoded character at p to its titlecase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the +titlecase version may be longer than the original character (up to two +characters). - char toLOWER(char ch) +The first character of the titlecased version is returned +(but note, as explained above, that there may be more.) + + UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers -Found in file handy.h +Found in file utf8.c -=item toUPPER +=item to_utf8_upper -Converts the specified character to uppercase. +Convert the UTF-8 encoded character at p to its uppercase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the +uppercase version may be longer than the original character (up to two +characters). - char toUPPER(char ch) +The first character of the uppercased version is returned +(but note, as explained above, that there may be more.) + + UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers -Found in file handy.h +Found in file utf8.c =item utf8n_to_uvchr @@ -4252,223 +4844,174 @@ is the recommended wide native character-aware way of saying =for hackers Found in file utf8.c -=item uvuni_to_utf8 +=item uvuni_to_utf8_flags Adds the UTF8 representation of the Unicode codepoint C to the end of the string C; C should be have at least C free bytes available. The return value is the pointer to the byte after the end of the new character. In other words, - d = uvuni_to_utf8(d, uv); - -is the recommended Unicode-aware way of saying - - *(d++) = uv; - - U8* uvuni_to_utf8(U8 *d, UV uv) - -=for hackers -Found in file utf8.c - -=item warn - -This is the XSUB-writer's interface to Perl's C function. Use this -function the same way you use the C C function. See -C. - - void warn(const char* pat, ...) - -=for hackers -Found in file util.c - -=item XPUSHi - -Push an integer onto the stack, extending the stack if necessary. Handles -'set' magic. See C. - - void XPUSHi(IV iv) - -=for hackers -Found in file pp.h + d = uvuni_to_utf8_flags(d, uv, flags); -=item XPUSHn +or, in most cases, -Push a double onto the stack, extending the stack if necessary. Handles -'set' magic. See C. + d = uvuni_to_utf8(d, uv); - void XPUSHn(NV nv) +(which is equivalent to) -=for hackers -Found in file pp.h + d = uvuni_to_utf8_flags(d, uv, 0); -=item XPUSHp +is the recommended Unicode-aware way of saying -Push a string onto the stack, extending the stack if necessary. The C -indicates the length of the string. Handles 'set' magic. See -C. + *(d++) = uv; - void XPUSHp(char* str, STRLEN len) + U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) =for hackers -Found in file pp.h - -=item XPUSHs - -Push an SV onto the stack, extending the stack if necessary. Does not -handle 'set' magic. See C. - - void XPUSHs(SV* sv) +Found in file utf8.c -=for hackers -Found in file pp.h -=item XPUSHu +=back -Push an unsigned integer onto the stack, extending the stack if necessary. -See C. +=head1 Variables created by C and C internal functions - void XPUSHu(UV uv) +=over 8 -=for hackers -Found in file pp.h +=item ax -=item XS +Variable which is setup by C to indicate the stack base offset, +used by the C, C and C macros. The C macro +must be called prior to setup the C variable. -Macro to declare an XSUB and its C parameter list. This is handled by -C. + I32 ax =for hackers Found in file XSUB.h -=item XSRETURN +=item CLASS -Return from XSUB, indicating number of items on the stack. This is usually -handled by C. +Variable which is setup by C to indicate the +class name for a C++ XS constructor. This is always a C. See C. - void XSRETURN(int nitems) + char* CLASS =for hackers Found in file XSUB.h -=item XSRETURN_EMPTY +=item dAX -Return an empty list from an XSUB immediately. +Sets up the C variable. +This is usually handled automatically by C by calling C. - XSRETURN_EMPTY; + dAX; =for hackers Found in file XSUB.h -=item XSRETURN_IV +=item dITEMS -Return an integer from an XSUB immediately. Uses C. +Sets up the C variable. +This is usually handled automatically by C by calling C. - void XSRETURN_IV(IV iv) + dITEMS; =for hackers Found in file XSUB.h -=item XSRETURN_NO +=item dXSARGS -Return C<&PL_sv_no> from an XSUB immediately. Uses C. +Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. +Sets up the C and C variables by calling C and C. +This is usually handled automatically by C. - XSRETURN_NO; + dXSARGS; =for hackers Found in file XSUB.h -=item XSRETURN_NV +=item dXSI32 -Return an double from an XSUB immediately. Uses C. +Sets up the C variable for an XSUB which has aliases. This is usually +handled automatically by C. - void XSRETURN_NV(NV nv) + dXSI32; =for hackers Found in file XSUB.h -=item XSRETURN_PV +=item items -Return a copy of a string from an XSUB immediately. Uses C. +Variable which is setup by C to indicate the number of +items on the stack. See L. - void XSRETURN_PV(char* str) + I32 items =for hackers Found in file XSUB.h -=item XSRETURN_UNDEF +=item ix -Return C<&PL_sv_undef> from an XSUB immediately. Uses C. +Variable which is setup by C to indicate which of an +XSUB's aliases was used to invoke it. See L. - XSRETURN_UNDEF; + I32 ix =for hackers Found in file XSUB.h -=item XSRETURN_YES - -Return C<&PL_sv_yes> from an XSUB immediately. Uses C. +=item newXSproto - XSRETURN_YES; +Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to +the subs. =for hackers Found in file XSUB.h -=item XST_mIV +=item RETVAL -Place an integer into the specified position C on the stack. The -value is stored in a new mortal SV. +Variable which is setup by C to hold the return value for an +XSUB. This is always the proper type for the XSUB. See +L. - void XST_mIV(int pos, IV iv) + (whatever) RETVAL =for hackers Found in file XSUB.h -=item XST_mNO +=item ST -Place C<&PL_sv_no> into the specified position C on the -stack. +Used to access elements on the XSUB's stack. - void XST_mNO(int pos) + SV* ST(int ix) =for hackers Found in file XSUB.h -=item XST_mNV +=item THIS -Place a double into the specified position C on the stack. The value -is stored in a new mortal SV. +Variable which is setup by C to designate the object in a C++ +XSUB. This is always the proper type for the C++ object. See C and +L. - void XST_mNV(int pos, NV nv) + (whatever) THIS =for hackers Found in file XSUB.h -=item XST_mPV - -Place a copy of a string into the specified position C on the stack. -The value is stored in a new mortal SV. +=item XS - void XST_mPV(int pos, char* str) +Macro to declare an XSUB and its C parameter list. This is handled by +C. =for hackers Found in file XSUB.h -=item XST_mUNDEF - -Place C<&PL_sv_undef> into the specified position C on the -stack. - - void XST_mUNDEF(int pos) - -=for hackers -Found in file XSUB.h +=item XSRETURN_EMPTY -=item XST_mYES +Return an empty list from an XSUB immediately. -Place C<&PL_sv_yes> into the specified position C on the -stack. - void XST_mYES(int pos) + XSRETURN_EMPTY; =for hackers Found in file XSUB.h @@ -4492,15 +5035,42 @@ C. See L. =for hackers Found in file XSUB.h -=item Zero -The XSUB-writer's interface to the C C function. The C is the -destination, C is the number of items, and C is the type. +=back - void Zero(void* dest, int nitems, type) +=head1 Warning and Dieing + +=over 8 + +=item croak + +This is the XSUB-writer's interface to Perl's C function. +Normally use this function the same way you use the C C +function. See C. + +If you want to throw an exception object, assign the object to +C<$@> and then pass C to croak(): + + errsv = get_sv("@", TRUE); + sv_setsv(errsv, exception_object); + croak(Nullch); + + void croak(const char* pat, ...) =for hackers -Found in file handy.h +Found in file util.c + +=item warn + +This is the XSUB-writer's interface to Perl's C function. Use this +function the same way you use the C C function. See +C. + + void warn(const char* pat, ...) + +=for hackers +Found in file util.c + =back