X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=d55b88a13af2565cefced6b73ca0999a20681208;hb=20ba30f468d23a62870c0f5047a078529d917e5a;hp=4872a9fbc3fef7cf287cf5f8f409a5facbbeeee6;hpb=894237640a8731055a749592e01318892443c38d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 4872a9f..d55b88a 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,361 @@ 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 -NOTE: the perl_ form of this function is deprecated. +=head1 Cloning an interpreter - I32 eval_sv(SV* sv, I32 flags) +=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 perl.c +Found in file sv.c -=item EXTEND -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. +=back - void EXTEND(SP, int nitems) +=head1 CV Manipulation Functions -=for hackers -Found in file pp.h +=over 8 -=item fbm_compile +=item CvSTASH -Analyses the string in order to make fast searches on it using fbm_instr() --- the Boyer-Moore algorithm. +Returns the stash of the CV. - void fbm_compile(SV* sv, U32 flags) + HV* CvSTASH(CV* cv) =for hackers -Found in file util.c +Found in file cv.h -=item fbm_instr +=item get_cv -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. +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. - char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) +NOTE: the perl_ form of this function is deprecated. + + CV* get_cv(const char* name, I32 create) =for hackers -Found in file util.c +Found in file perl.c -=item FREETMPS +=item Nullcv -Closing bracket for temporaries on a callback. See C and -L. +Null CV pointer. - FREETMPS; =for hackers -Found in file scope.h +Found in file cv.h -=item getcwd_sv -Fill the sv with current working directory +=back - int getcwd_sv(SV* sv) +=head1 Embedding Functions + +=over 8 + +=item load_module + +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. + + void load_module(U32 flags, SV* name, SV* ver, ...) =for hackers -Found in file util.c +Found in file op.c -=item get_av +=item perl_alloc -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. +Allocates a new Perl interpreter. See L. -NOTE: the perl_ form of this function is deprecated. + PerlInterpreter* perl_alloc() - AV* get_av(const char* name, I32 create) +=for hackers +Found in file perl.c + +=item perl_construct + +Initializes a new Perl interpreter. See L. + + void perl_construct(PerlInterpreter* interp) =for hackers Found in file perl.c -=item get_cv +=item perl_destruct -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. +Shuts down a Perl interpreter. See L. -NOTE: the perl_ form of this function is deprecated. + int perl_destruct(PerlInterpreter* interp) - CV* get_cv(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_hv +=item perl_parse -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 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) - HV* get_hv(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_sv +=item require_pv -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. +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. - SV* get_sv(const char* name, I32 create) + void require_pv(const char* pv) =for hackers Found in file perl.c -=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. +=back - U32 GIMME +=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 GIMME_V +=item PL_na -The XSUB-writer's equivalent to Perl's C. Returns C, -C or C for void, scalar or list context, -respectively. +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. - U32 GIMME_V + STRLEN PL_na =for hackers -Found in file op.h +Found in file thrdvar.h -=item grok_number +=item PL_sv_no -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 (defined in perl.h). +This is the C SV. See C. Always refer to this as +C<&PL_sv_no>. -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. + SV PL_sv_no -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 intrpvar.h - int grok_number(const char *pv, STRLEN len, UV *valuep) +=item PL_sv_undef + +This is the C SV. Always refer to this as C<&PL_sv_undef>. + + SV PL_sv_undef =for hackers -Found in file numeric.c +Found in file intrpvar.h -=item grok_numeric_radix +=item PL_sv_yes -Scan and skip for a numeric decimal separator (radix). +This is the C SV. See C. Always refer to this as +C<&PL_sv_yes>. - bool grok_numeric_radix(const char **sp, const char *send) + SV PL_sv_yes =for hackers -Found in file numeric.c +Found in file intrpvar.h + + +=back + +=head1 GV Functions + +=over 8 =item GvSV @@ -684,61 +802,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 + +=item HEf_SVKEY + +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). -Indicates that arguments returned from a callback should be discarded. See -L. =for hackers -Found in file cop.h +Found in file hv.h -=item G_EVAL - -Used to force a Perl C wrapper around a callback. See -L. +=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 +1010,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,151 +1160,29 @@ Undefines the hash. =for hackers Found in file hv.c -=item isALNUM - -Returns a boolean indicating whether the C C is an ASCII alphanumeric -character (including underscore) or digit. - - bool isALNUM(char ch) - -=for hackers -Found in file handy.h - -=item isALPHA - -Returns a boolean indicating whether the C C is an ASCII alphabetic -character. - - bool isALPHA(char ch) - -=for hackers -Found in file handy.h - -=item isDIGIT - -Returns a boolean indicating whether the C C is an ASCII -digit. - - bool isDIGIT(char ch) - -=for hackers -Found in file handy.h - -=item isLOWER - -Returns a boolean indicating whether the C C is a lowercase -character. - - bool isLOWER(char ch) - -=for hackers -Found in file handy.h - -=item isSPACE - -Returns a boolean indicating whether the C C is whitespace. - - bool isSPACE(char ch) - -=for hackers -Found in file handy.h - -=item isUPPER - -Returns a boolean indicating whether the C C is an uppercase -character. - - bool isUPPER(char ch) - -=for hackers -Found in file handy.h - -=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 items - -Variable which is setup by C to indicate the number of -items on the stack. See L. - - I32 items - -=for hackers -Found in file XSUB.h - -=item ix - -Variable which is setup by C to indicate which of an -XSUB's aliases was used to invoke it. See L. - - I32 ix - -=for hackers -Found in file XSUB.h - -=item LEAVE +=item newHV -Closing bracket on a callback. See C and L. +Creates a new HV. The reference count is set to 1. - LEAVE; + HV* newHV() =for hackers -Found in file scope.h +Found in file hv.c -=item load_module +=item Nullhv -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. +Null HV pointer. - void load_module(U32 flags, SV* name, SV* ver, ...) =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 hv.h -=for hackers -Found in file sv.c -=item MARK +=back -Stack marker variable for the XSUB. See C. +=head1 Magical Functions -=for hackers -Found in file pp.h +=over 8 =item mg_clear @@ -1266,94 +1256,102 @@ Do magic after a value is assigned to the SV. See C. =for hackers Found in file mg.c -=item Move +=item SvGETMAGIC -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. Can do overlapping moves. See also C. +Invokes C on an SV if it has 'get' magic. This macro evaluates its +argument more than once. - void Move(void* src, void* dest, int nitems, type) + void SvGETMAGIC(SV* sv) =for hackers -Found in file handy.h +Found in file sv.h -=item New +=item SvSETMAGIC -The XSUB-writer's interface to the C C function. +Invokes C on an SV if it has 'set' magic. This macro evaluates its +argument more than once. - void New(int id, void* ptr, int nitems, type) + void SvSETMAGIC(SV* sv) =for hackers -Found in file handy.h +Found in file sv.h -=item newAV +=item SvSetMagicSV -Creates a new AV. The reference count is set to 1. +Like C, but does any set magic required afterwards. - AV* newAV() + void SvSetMagicSV(SV* dsb, SV* ssv) =for hackers -Found in file av.c +Found in file sv.h -=item Newc +=item SvSetSV -The XSUB-writer's interface to the C C function, with -cast. +Calls C if dsv is not the same as ssv. May evaluate arguments +more than once. - void Newc(int id, void* ptr, int nitems, type, cast) + void SvSetSV(SV* dsb, SV* ssv) =for hackers -Found in file handy.h +Found in file sv.h -=item newCONSTSUB +=item SvSetSV_nosteal -Creates a constant sub equivalent to Perl C which is -eligible for inlining at compile-time. +Calls a non-destructive version of C if dsv is not the same as +ssv. May evaluate arguments more than once. - CV* newCONSTSUB(HV* stash, char* name, SV* sv) + void SvSetSV_nosteal(SV* dsv, SV* ssv) =for hackers -Found in file op.c +Found in file sv.h -=item newHV -Creates a new HV. The reference count is set to 1. +=back - HV* newHV() +=head1 Memory Management -=for hackers -Found in file hv.c +=over 8 -=item newRV_inc +=item Copy -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. 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. - SV* newRV_inc(SV* sv) + void Copy(void* src, void* dest, int nitems, type) =for hackers -Found in file sv.h +Found in file handy.h -=item newRV_noinc +=item Move -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. The C is the +source, C is the destination, C is the number of items, and C is +the type. Can do overlapping moves. See also C. - SV* newRV_noinc(SV *sv) + void Move(void* src, void* dest, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSV +=item New -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. +The XSUB-writer's interface to the C C function. - SV* newSV(STRLEN len) + void New(int id, void* ptr, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h + +=item Newc + +The XSUB-writer's interface to the C C function, with +cast. + + void Newc(int id, void* ptr, int nitems, type, cast) + +=for hackers +Found in file handy.h =item NEWSV @@ -1363,294 +1361,523 @@ 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). + SV* NEWSV(int id, STRLEN len) =for hackers Found in file handy.h -=item newSViv +=item Newz -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. +The XSUB-writer's interface to the C C function. The allocated +memory is zeroed with C. - SV* newSViv(IV i) + void Newz(int id, void* ptr, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVnv +=item Renew -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. +The XSUB-writer's interface to the C C function. - SV* newSVnv(NV n) + void Renew(void* ptr, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVpv +=item Renewc -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, with +cast. - SV* newSVpv(const char* s, STRLEN len) + void Renewc(void* ptr, int nitems, type, cast) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVpvf +=item Safefree -Creates a new SV and initializes it with the string formatted like -C. +The XSUB-writer's interface to the C C function. - SV* newSVpvf(const char* pat, ...) + void Safefree(void* ptr) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVpvn +=item savepv -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. +Copy a string to a safe spot. This does not use an SV. - SV* newSVpvn(const char* s, STRLEN len) + char* savepv(const char* sv) =for hackers -Found in file sv.c +Found in file util.c -=item newSVpvn_share +=item savepvn -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. +Copy a string to a safe spot. The C indicates number of bytes to +copy. This does not use an SV. - SV* newSVpvn_share(const char* s, I32 len, U32 hash) + char* savepvn(const char* sv, I32 len) =for hackers -Found in file sv.c +Found in file util.c -=item newSVrv +=item StructCopy -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. +This is an architecture-independent macro to copy one structure to another. - SV* newSVrv(SV* rv, const char* classname) + void StructCopy(type src, type dest, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVsv +=item Zero -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). +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* newSVsv(SV* old) + void Zero(void* dest, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVuv -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. +=back - SV* newSVuv(UV u) +=head1 Miscellaneous Functions -=for hackers -Found in file sv.c +=over 8 -=item newXS +=item fbm_compile -Used by C to hook up XSUBs as Perl subs. +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 op.c +Found in file util.c -=item newXSproto +=item fbm_instr -Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to -the subs. +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. + + char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) =for hackers -Found in file XSUB.h +Found in file util.c -=item Newz +=item form -The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. +Takes a sprintf-style format pattern and conventional +(non-SV) arguments and returns the formatted string. - void Newz(int id, void* ptr, int nitems, type) + (char *) Perl_form(pTHX_ const char* pat, ...) -=for hackers -Found in file handy.h +can be used any place a string (char *) is required: -=item Nullav + char * s = Perl_form("%d.%d",major,minor); -Null AV pointer. +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 av.h +Found in file util.c -=item Nullch +=item getcwd_sv -Null character pointer. +Fill the sv with current working directory + + int getcwd_sv(SV* sv) =for hackers -Found in file handy.h +Found in file util.c -=item Nullcv +=item strEQ -Null CV pointer. +Test two strings to see if they are equal. Returns true or false. + + bool strEQ(char* s1, char* s2) =for hackers -Found in file cv.h +Found in file handy.h -=item Nullhv +=item strGE -Null HV pointer. +Test two strings to see if the first, C, is greater than or equal to +the second, C. Returns true or false. + + bool strGE(char* s1, char* s2) =for hackers -Found in file hv.h +Found in file handy.h -=item Nullsv +=item strGT -Null SV pointer. +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 handy.h -=item ORIGMARK +=item strLE -The original stack mark for the XSUB. See C. +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 pp.h +Found in file handy.h -=item perl_alloc +=item strLT -Allocates a new Perl interpreter. See L. +Test two strings to see if the first, C, is less than the second, +C. Returns true or false. - PerlInterpreter* perl_alloc() + bool strLT(char* s1, char* s2) =for hackers -Found in file perl.c +Found in file handy.h -=item perl_clone +=item strNE -Create and return a new interpreter by cloning the current one. +Test two strings to see if they are different. Returns true or +false. - PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) + bool strNE(char* s1, char* s2) =for hackers -Found in file sv.c +Found in file handy.h -=item perl_construct +=item strnEQ -Initializes a new Perl interpreter. See L. +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). - void perl_construct(PerlInterpreter* interp) + bool strnEQ(char* s1, char* s2, STRLEN len) =for hackers -Found in file perl.c +Found in file handy.h -=item perl_destruct +=item strnNE -Shuts down a Perl interpreter. See L. +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). - void perl_destruct(PerlInterpreter* interp) + bool strnNE(char* s1, char* s2, STRLEN len) =for hackers -Found in file perl.c - -=item perl_free +Found in file handy.h -Releases a Perl interpreter. See L. - void perl_free(PerlInterpreter* interp) +=back -=for hackers -Found in file perl.c +=head1 Numeric functions -=item perl_parse +=over 8 -Tells a Perl interpreter to parse a Perl script. See L. +=item grok_bin - int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) +converts a string representing a binary number to numeric form. -=for hackers -Found in file perl.c +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. -=item perl_run +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). -Tells a Perl interpreter to run. See L. +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. - int perl_run(PerlInterpreter* interp) + UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file perl.c - -=item PL_modglobal +Found in file numeric.c -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. +=item grok_hex - HV* PL_modglobal +converts a string representing a hex number to numeric form. -=for hackers -Found in file intrpvar.h +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. -=item PL_na +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). -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. +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. - STRLEN PL_na + UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file thrdvar.h +Found in file numeric.c -=item PL_sv_no +=item grok_number -This is the C SV. See C. Always refer to this as -C<&PL_sv_no>. +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). - SV PL_sv_no +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 intrpvar.h +Found in file numeric.c -=item PL_sv_undef +=item grok_numeric_radix -This is the C SV. Always refer to this as C<&PL_sv_undef>. +Scan and skip for a numeric decimal separator (radix). - SV PL_sv_undef + bool grok_numeric_radix(const char **sp, const char *send) =for hackers -Found in file intrpvar.h +Found in file numeric.c -=item PL_sv_yes +=item grok_oct -This is the C SV. See C. Always refer to this as -C<&PL_sv_yes>. - SV PL_sv_yes + UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file intrpvar.h +Found in file numeric.c + +=item scan_bin + +For backwards compatibility. Use C instead. + + NV scan_bin(char* start, STRLEN len, STRLEN* retlen) + +=for hackers +Found in file numeric.c + +=item scan_hex + +For backwards compatibility. Use C instead. + + NV scan_hex(char* start, STRLEN len, STRLEN* retlen) + +=for hackers +Found in file numeric.c + +=item scan_oct + +For backwards compatibility. Use C instead. + + NV scan_oct(char* start, STRLEN len, STRLEN* retlen) + +=for hackers +Found in file numeric.c + + +=back + +=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 op.c + +=item newCONSTSUB + +Creates a constant sub equivalent to Perl C which is +eligible for inlining at compile-time. + + 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 Shared SV Functions + +=over 8 + +=item sharedsv_find + +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. + + shared_sv* sharedsv_find(SV* sv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_init + +Saves a space for keeping SVs wider than an interpreter, +currently only stores a pointer to the first interpreter. + + void sharedsv_init() + +=for hackers +Found in file sharedsv.c + +=item sharedsv_lock + +Recursive locks on a sharedsv. +Locks are dynamically scoped at the level of the first lock. + void sharedsv_lock(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_new + +Allocates a new shared sv struct, you must yourself create the SV/AV/HV. + shared_sv* sharedsv_new() + +=for hackers +Found in file sharedsv.c + +=item sharedsv_thrcnt_dec + +Decrements the threadcount of a shared sv. When a threads frontend is freed +this function should be called. + + void sharedsv_thrcnt_dec(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_thrcnt_inc + +Increments the threadcount of a sharedsv. + void sharedsv_thrcnt_inc(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_unlock + +Recursively unlocks a shared sv. + + void sharedsv_unlock(shared_sv* ssv) + +=for hackers +Found in file sharedsv.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 pp.h + +=item dORIGMARK + +Saves the original stack mark for the XSUB. See C. + + dORIGMARK; + +=for hackers +Found in file pp.h + +=item dSP + +Declares a local copy of perl's stack pointer for the XSUB, available via +the C macro. See C. + + dSP; + +=for hackers +Found in file pp.h + +=item EXTEND + +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. + + void EXTEND(SP, int nitems) + +=for hackers +Found in file pp.h + +=item MARK + +Stack marker variable for the XSUB. See C. + +=for hackers +Found in file pp.h + +=item ORIGMARK + +The original stack mark for the XSUB. See C. + +=for hackers +Found in file pp.h =item POPi @@ -1754,237 +1981,476 @@ Push a string onto the stack. The stack must have room for this element. The C indicates the length of the string. Handles 'set' magic. See C. - void PUSHp(char* str, STRLEN len) + void PUSHp(char* str, STRLEN len) + +=for hackers +Found in file pp.h + +=item PUSHs + +Push an SV onto the stack. The stack must have room for this element. +Does not handle 'set' magic. See C. + + void PUSHs(SV* sv) + +=for hackers +Found in file pp.h + +=item PUSHu + +Push an unsigned integer onto the stack. The stack must have room for this +element. See C. + + void PUSHu(UV uv) + +=for hackers +Found in file pp.h + +=item PUTBACK + +Closing bracket for XSUB arguments. This is usually handled by C. +See C and L for other uses. + + PUTBACK; + +=for hackers +Found in file pp.h + +=item SP + +Stack pointer. This is usually handled by C. See C and +C. + +=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 pp.h + +=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 + +=item XPUSHn + +Push a double onto the stack, extending the stack if necessary. Handles +'set' magic. See C. + + void XPUSHn(NV nv) + +=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 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) + +=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 + +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 pp.h - -=item PUSHs +Found in file sv.h -Push an SV onto the stack. The stack must have room for this element. -Does not handle 'set' magic. See C. +=item SVt_IV - void PUSHs(SV* sv) +Integer type flag for scalars. See C. =for hackers -Found in file pp.h - -=item PUSHu +Found in file sv.h -Push an unsigned integer onto the stack. The stack must have room for this -element. See C. +=item SVt_NV - void PUSHu(UV uv) +Double type flag for scalars. See C. =for hackers -Found in file pp.h - -=item PUTBACK +Found in file sv.h -Closing bracket for XSUB arguments. This is usually handled by C. -See C and L for other uses. +=item SVt_PV - PUTBACK; +Pointer type flag for scalars. See C. =for hackers -Found in file pp.h - -=item Renew +Found in file sv.h -The XSUB-writer's interface to the C C function. +=item SVt_PVAV - void Renew(void* ptr, int nitems, type) +Type flag for arrays. See C. =for hackers -Found in file handy.h - -=item Renewc +Found in file sv.h -The XSUB-writer's interface to the C C function, with -cast. +=item SVt_PVCV - void Renewc(void* ptr, int nitems, type, cast) +Type flag for code refs. See C. =for hackers -Found in file handy.h +Found in file sv.h -=item require_pv +=item SVt_PVHV -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. +Type flag for hashes. See C. -NOTE: the perl_ form of this function is deprecated. +=for hackers +Found in file sv.h - void require_pv(const char* pv) +=item SVt_PVMG + +Type flag for blessed scalars. See C. =for hackers -Found in file perl.c +Found in file sv.h -=item RETVAL -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. +=back - (whatever) RETVAL +=head1 SV Manipulation Functions -=for hackers -Found in file XSUB.h +=over 8 -=item Safefree +=item get_sv -The XSUB-writer's interface to the C C function. +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. - void Safefree(void* ptr) +NOTE: the perl_ form of this function is deprecated. + + SV* get_sv(const char* name, I32 create) =for hackers -Found in file handy.h +Found in file perl.c -=item savepv +=item looks_like_number -Copy a string to a safe spot. This does not use an SV. +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. - char* savepv(const char* sv) + I32 looks_like_number(SV* sv) =for hackers -Found in file util.c +Found in file sv.c -=item savepvn +=item newRV_inc -Copy a string to a safe spot. The C indicates number of bytes to -copy. This does not use an SV. +Creates an RV wrapper for an SV. The reference count for the original SV is +incremented. - char* savepvn(const char* sv, I32 len) + SV* newRV_inc(SV* sv) =for hackers -Found in file util.c +Found in file sv.h -=item SAVETMPS +=item newRV_noinc -Opening bracket for temporaries on a callback. See C and -L. +Creates an RV wrapper for an SV. The reference count for the original +SV is B incremented. - SAVETMPS; + SV* newRV_noinc(SV *sv) =for hackers -Found in file scope.h +Found in file sv.c -=item SP +=item newSV -Stack pointer. This is usually handled by C. See C and -C. +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. + + SV* newSV(STRLEN len) =for hackers -Found in file pp.h +Found in file sv.c -=item SPAGAIN +=item newSViv -Refetch the stack pointer. Used after a callback. See L. +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. - SPAGAIN; + SV* newSViv(IV i) =for hackers -Found in file pp.h +Found in file sv.c -=item ST +=item newSVnv -Used to access elements on the XSUB's stack. +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. - SV* ST(int ix) + SV* newSVnv(NV n) =for hackers -Found in file XSUB.h +Found in file sv.c -=item strEQ +=item newSVpv -Test two strings to see if they are equal. 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 strEQ(char* s1, char* s2) + SV* newSVpv(const char* s, STRLEN len) =for hackers -Found in file handy.h +Found in file sv.c -=item strGE +=item newSVpvf -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 initializes it with the string formatted like +C. - bool strGE(char* s1, char* s2) + SV* newSVpvf(const char* pat, ...) =for hackers -Found in file handy.h +Found in file sv.c -=item strGT +=item newSVpvn -Test two strings to see if the first, C, is greater than 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 strGT(char* s1, char* s2) + SV* newSVpvn(const char* s, STRLEN len) =for hackers -Found in file handy.h +Found in file sv.c -=item strLE +=item newSVpvn_share -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 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 strLE(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 strLT +=item newSVrv -Test two strings to see if the first, C, is less than the second, -C. 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 strLT(char* s1, char* s2) + SV* newSVrv(SV* rv, const char* classname) =for hackers -Found in file handy.h +Found in file sv.c -=item strNE +=item newSVsv -Test two strings to see if they are different. Returns true or -false. +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). - bool strNE(char* s1, char* s2) + SV* newSVsv(SV* old) =for hackers -Found in file handy.h +Found in file sv.c -=item strnEQ +=item newSVuv -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 and copies an unsigned integer into it. +The reference count for the SV is set to 1. - bool strnEQ(char* s1, char* s2, STRLEN len) + SV* newSVuv(UV u) =for hackers -Found in file handy.h - -=item strnNE +Found in file sv.c -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). +=item new_vstring - bool strnNE(char* s1, char* s2, STRLEN len) +Returns a pointer to the next character after the parsed +vstring, as well as updating the passed in sv. -=for hackers -Found in file handy.h +Function must be called like -=item StructCopy + sv = NEWSV(92,5); + s = new_vstring(s,sv); -This is an architecture-independent macro to copy one structure to another. +The sv must already be large enough to store the vstring +passed in. - void StructCopy(type src, type dest, type) + char* new_vstring(char *vstr, SV *sv) =for hackers -Found in file handy.h +Found in file util.c =item SvCUR @@ -2014,21 +2480,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) @@ -2057,7 +2513,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) @@ -2114,7 +2570,17 @@ Found in file sv.h Coerces the given SV to an integer and returns it. See C for a version which guarantees to evaluate sv only once. - IV SvIV(SV* sv) + IV SvIV(SV* sv) + +=for hackers +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 efficient C otherwise. + + IV SvIVx(SV* sv) =for hackers Found in file sv.h @@ -2129,16 +2595,6 @@ Only use when you are sure SvIOK is true. See also C. =for hackers 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. - - IV SvIVx(SV* sv) - -=for hackers -Found in file sv.h - =item SvLEN Returns the size of the string buffer in the SV, not including any part @@ -2234,22 +2690,22 @@ which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvNVx +=item SvNVX -Coerces the given SV to a double and returns it. Guarantees to evaluate -sv only once. Use the more efficent C otherwise. +Returns the raw value in the SV's NV slot, without checks or conversions. +Only use when you are sure SvNOK is true. See also C. - NV SvNVx(SV* sv) + NV SvNVX(SV* sv) =for hackers Found in file sv.h -=item SvNVX +=item SvNVx -Returns the raw value in the SV's NV slot, without checks or conversions. -Only use when you are sure SvNOK is true. See also C. +Coerces the given SV to a double and returns it. Guarantees to evaluate +sv only once. Use the more efficient C otherwise. - NV SvNVX(SV* sv) + NV SvNVx(SV* sv) =for hackers Found in file sv.h @@ -2356,7 +2812,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. @@ -2368,7 +2824,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) @@ -2389,14 +2845,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) @@ -2405,8 +2861,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) @@ -2416,8 +2872,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) @@ -2427,7 +2883,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) @@ -2436,9 +2892,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 @@ -2555,50 +3011,12 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h -=item SvSETMAGIC - -Invokes C on an SV if it has 'set' magic. This macro evaluates its -argument more than once. - - void SvSETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV - -Like C, but does any set magic required afterwards. - - void SvSetMagicSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - =item SvSetMagicSV_nosteal Like C, but does any set magic required afterwards. - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV - -Calls C if dsv is not the same as ssv. May evaluate arguments -more than once. - - void SvSetSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV_nosteal -Calls a non-destructive version of C if dsv is not the same as -ssv. May evaluate arguments more than once. - - void SvSetSV_nosteal(SV* dsv, SV* ssv) + void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) =for hackers Found in file sv.h @@ -2664,14 +3082,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. @@ -2681,55 +3091,6 @@ 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. - -=for hackers -Found in file sv.h - -=item SVt_PVMG - -Type flag for blessed scalars. See C. - -=for hackers -Found in file sv.h - =item SvUOK Returns a boolean indicating whether the SV contains an unsigned integer. @@ -2787,22 +3148,22 @@ for a version which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvUVX +=item SvUVx -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. +Coerces the given SV to an unsigned integer and returns it. Guarantees to +evaluate sv only once. Use the more efficient C otherwise. - UV SvUVX(SV* sv) + UV SvUVx(SV* sv) =for hackers Found in file sv.h -=item SvUVx +=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. +Returns the raw value in the SV's UV slot, without checks or conversions. +Only use when you are sure SvIOK is true. See also C. - UV SvUVx(SV* sv) + UV SvUVX(SV* sv) =for hackers Found in file sv.h @@ -2810,7 +3171,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) @@ -2850,8 +3211,9 @@ Found in file sv.c =item sv_2mortal -Marks an existing SV as mortal. The SV will be destroyed when the current -context ends. See also C and C. +Marks an existing SV as mortal. The SV will be destroyed "soon", either +by an explicit call to FREETMPS, or by an implicit call at places such as +statement boundaries. See also C and C. SV* sv_2mortal(SV* sv) @@ -3322,8 +3684,9 @@ Found in file sv.c =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). -The new SV is marked as mortal. It will be destroyed when the current -context ends. See also C and C. +The new SV is marked as mortal. It will be destroyed "soon", either by an +explicit call to FREETMPS, or by an implicit call at places such as +statement boundaries. See also C and C. SV* sv_mortalcopy(SV* oldsv) @@ -3333,8 +3696,9 @@ Found in file sv.c =item sv_newmortal Creates a new null SV which is mortal. The reference count of the SV is -set to 1. It will be destroyed when the current context ends. See -also C and C. +set to 1. It will be destroyed "soon", either by an explicit call to +FREETMPS, or by an implicit call at places such as statement boundaries. +See also C and C. SV* sv_newmortal() @@ -3984,66 +4348,269 @@ Found in file sv.c 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) + 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 sv.c +Found in file utf8.c -=item sv_vcatpvfn +=item to_utf8_case -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 "p" contains the pointer to the UTF-8 string encoding +the character that is being converted. -Usually used via one of its frontends C and C. +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. - void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) +The "swash" is a pointer to the swash to use. + +The "normal" is a string like "ToLower" which means the swash +$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl, +and loaded by SWASHGET, using lib/utf8_heavy.pl. + +The "special" is a string like "utf8::ToSpecLower", which means +the hash %utf8::ToSpecLower, which is stored in the same file, +lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access +to the hash is by Perl_to_utf8_case(). + + 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 @@ -4185,223 +4752,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 @@ -4425,15 +4943,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