X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=08420967a83f26791ab7cf8d87e2f51380a8c08d;hb=b03ad8f690c4dcc613a1ec77d747e2d429945b16;hp=d67da131f9d8b53e0525ba70ff128c5749914ee1;hpb=9f2ea79885dcd731e16cfe839c551021222566a9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index d67da13..0842096 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,55 @@ 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) +See lib/sort.pm for details about controlling the sorting algorithm. + + 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,307 +357,397 @@ 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 nothreadhook -Closing bracket for temporaries on a callback. See C and -L. +Stub that provides thread hook for perl_destruct when there are +no threads. - FREETMPS; + int nothreadhook() =for hackers -Found in file scope.h +Found in file perl.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 Functions in file pp_pack.c + + +=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 op.h +Found in file pp_pack.c -=item GIMME_V +=item unpack_str -The XSUB-writer's equivalent to Perl's C. Returns C, -C or C for void, scalar or list context, -respectively. +The engine implementing unpack() Perl function. - U32 GIMME_V + 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 grok_number -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). If the value -of the number can fit an in UV, it is returned in the *valuep. +=back - int grok_number(const char *pv, STRLEN len, UV *valuep) +=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 util.c +Found in file intrpvar.h -=item grok_numeric_radix +=item PL_na -Scan and skip for a numeric decimal separator (radix). +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. - bool grok_numeric_radix(const char **sp, const char *send) + STRLEN PL_na =for hackers -Found in file util.c +Found in file thrdvar.h + +=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 intrpvar.h + +=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 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 @@ -641,6 +818,20 @@ C apply equally to these functions. =for hackers Found in file gv.c +=item gv_fetchmeth_autoload + +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 @@ -663,61 +854,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 @@ -877,7 +1062,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. @@ -915,6 +1100,7 @@ NOTE: Before version 5.004_65, C used to return the number of hash buckets that happen to be in use. If you still need that esoteric value, you can get it through the macro C. + I32 hv_iterinit(HV* tb) =for hackers @@ -945,6 +1131,14 @@ Found in file hv.c Returns entries from a hash iterator. See C. +You may call C or C on the hash entry that the +iterator currently points to, without losing your place or invalidating your +iterator. Note that in this case the current entry is deleted from the hash +with your iterator holding the last reference to it. Your iterator is flagged +to free the entry on the next call to C, so you must not discard +your iterator immediately else the entry will leak - call C to +trigger the resource deallocation. + HE* hv_iternext(HV* tb) =for hackers @@ -960,6 +1154,26 @@ operation. =for hackers Found in file hv.c +=item hv_iternext_flags + +Returns entries from a hash iterator. See C and C. +The C value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is +set the placeholders keys (for restricted hashes) will be returned in addition +to normal keys. By default placeholders are automatically skipped over. +Currently a placeholder is implemented with a value that is literally +<&Perl_sv_undef> (a regular C value is a normal read-write SV for which +C is false). Note that the implementation of placeholders and +restricted hashes may change, and the implementation currently is +insufficiently abstracted for any change to be tidy. + +NOTE: this function is experimental and may change or be +removed without notice. + + HE* hv_iternext_flags(HV* tb, I32 flags) + +=for hackers +Found in file hv.c + =item hv_iterval Returns the value from the current position of the hash iterator. See @@ -1027,223 +1241,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 an 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 @@ -1265,15 +1453,6 @@ The XSUB-writer's interface to the C C function. =for hackers Found in file handy.h -=item newAV - -Creates a new AV. The reference count is set to 1. - - AV* newAV() - -=for hackers -Found in file av.c - =item Newc The XSUB-writer's interface to the C C function, with @@ -1284,329 +1463,485 @@ cast. =for hackers Found in file handy.h -=item newCONSTSUB +=item NEWSV -Creates a constant sub equivalent to Perl C which is -eligible for inlining at compile-time. +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). - CV* newCONSTSUB(HV* stash, char* name, SV* sv) + + SV* NEWSV(int id, STRLEN len) =for hackers -Found in file op.c +Found in file handy.h -=item newHV +=item Newz -Creates a new HV. The reference count is set to 1. +The XSUB-writer's interface to the C C function. The allocated +memory is zeroed with C. - HV* newHV() + void Newz(int id, void* ptr, int nitems, type) =for hackers -Found in file hv.c +Found in file handy.h -=item newRV_inc +=item Poison -Creates an RV wrapper for an SV. The reference count for the original SV is -incremented. +Fill up memory with a pattern (byte 0xAB over and over again) that +hopefully catches attempts to access uninitialized memory. - SV* newRV_inc(SV* sv) + void Poison(void* dest, int nitems, type) =for hackers -Found in file sv.h +Found in file handy.h -=item newRV_noinc +=item Renew -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 Renew(void* ptr, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item NEWSV +=item Renewc -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). +The XSUB-writer's interface to the C C function, with +cast. - SV* NEWSV(int id, STRLEN len) + void Renewc(void* ptr, int nitems, type, cast) =for hackers Found in file handy.h -=item newSViv +=item Safefree -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. - SV* newSViv(IV i) + void Safefree(void* ptr) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVnv +=item savepv -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. +Perl's version of C. Returns a pointer to a newly allocated +string which is a duplicate of C. The size of the string is +determined by C. The memory allocated for the new string can +be freed with the C function. - SV* newSVnv(NV n) + char* savepv(const char* pv) =for hackers -Found in file sv.c +Found in file util.c -=item newSVpv +=item savepvn -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. +Perl's version of what C would be if it existed. Returns a +pointer to a newly allocated string which is a duplicate of the first +C bytes from C. The memory allocated for the new string can be +freed with the C function. - SV* newSVpv(const char* s, STRLEN len) + char* savepvn(const char* pv, I32 len) =for hackers -Found in file sv.c +Found in file util.c -=item newSVpvf +=item savesharedpv -Creates a new SV an initialize it with the string formatted like -C. +A version of C which allocates the duplicate string in memory +which is shared between threads. - SV* newSVpvf(const char* pat, ...) + char* savesharedpv(const char* pv) =for hackers -Found in file sv.c +Found in file util.c -=item newSVpvn +=item StructCopy -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. +This is an architecture-independent macro to copy one structure to another. - SV* newSVpvn(const char* s, STRLEN len) + void StructCopy(type src, type dest, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVpvn_share +=item Zero -Creates a new SV and populates it with a string from -the string table. Turns on READONLY and FAKE. -The idea here is that as string table is used for shared hash -keys these strings will have SvPVX == HeKEY and hash lookup -will avoid string compare. +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* newSVpvn_share(const char* s, I32 len, U32 hash) + void Zero(void* dest, int nitems, type) =for hackers -Found in file sv.c +Found in file handy.h -=item newSVrv -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. +=back - SV* newSVrv(SV* rv, const char* classname) +=head1 Miscellaneous Functions -=for hackers -Found in file sv.c +=over 8 -=item newSVsv +=item fbm_compile -Creates a new SV which is an exact duplicate of the original SV. +Analyses the string in order to make fast searches on it using fbm_instr() +-- the Boyer-Moore algorithm. - SV* newSVsv(SV* old) + void fbm_compile(SV* sv, U32 flags) =for hackers -Found in file sv.c +Found in file util.c -=item newSVuv +=item fbm_instr -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. +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* newSVuv(UV u) + 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 newXS +=item form -Used by C to hook up XSUBs as Perl subs. +Takes a sprintf-style format pattern and conventional +(non-SV) arguments and returns the formatted string. + + (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 op.c +Found in file util.c -=item newXSproto +=item getcwd_sv -Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to -the subs. +Fill the sv with current working directory + + int getcwd_sv(SV* sv) =for hackers -Found in file XSUB.h +Found in file util.c -=item Newz +=item strEQ -The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. +Test two strings to see if they are equal. Returns true or false. - void Newz(int id, void* ptr, int nitems, type) + bool strEQ(char* s1, char* s2) =for hackers Found in file handy.h -=item Nullav +=item strGE -Null AV 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 av.h +Found in file handy.h -=item Nullch +=item strGT -Null character 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 Nullcv +=item strLE -Null CV pointer. +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 cv.h +Found in file handy.h -=item Nullhv +=item strLT -Null HV pointer. +Test two strings to see if the first, C, is less than the second, +C. Returns true or false. + + bool strLT(char* s1, char* s2) =for hackers -Found in file hv.h +Found in file handy.h -=item Nullsv +=item strNE -Null SV 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 handy.h -=item ORIGMARK +=item strnEQ -The original stack mark for the XSUB. See C. +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 pp.h +Found in file handy.h -=item perl_alloc +=item strnNE -Allocates a new 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). - PerlInterpreter* perl_alloc() + bool strnNE(char* s1, char* s2, STRLEN len) =for hackers -Found in file perl.c +Found in file handy.h -=item perl_construct -Initializes a new Perl interpreter. See L. +=back - void perl_construct(PerlInterpreter* interp) +=head1 Numeric functions -=for hackers -Found in file perl.c +=over 8 -=item perl_destruct +=item grok_bin -Shuts down a Perl interpreter. See L. +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. - void perl_destruct(PerlInterpreter* interp) + UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file perl.c +Found in file numeric.c -=item perl_free +=item grok_hex -Releases a Perl interpreter. See L. +converts a string representing a hex number to numeric form. - void perl_free(PerlInterpreter* interp) +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 perl.c +Found in file numeric.c -=item perl_parse +=item grok_number -Tells a Perl interpreter to parse a Perl script. See L. +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). - int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) +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 perl.c +Found in file numeric.c -=item perl_run +=item grok_numeric_radix -Tells a Perl interpreter to run. See L. +Scan and skip for a numeric decimal separator (radix). - int perl_run(PerlInterpreter* interp) + bool grok_numeric_radix(const char **sp, const char *send) =for hackers -Found in file perl.c +Found in file numeric.c -=item PL_modglobal +=item grok_oct -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 + UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file intrpvar.h +Found in file numeric.c -=item PL_na +=item scan_bin -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. +For backwards compatibility. Use C instead. - STRLEN PL_na + NV scan_bin(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file thrdvar.h +Found in file numeric.c -=item PL_sv_no +=item scan_hex -This is the C SV. See C. Always refer to this as -C<&PL_sv_no>. +For backwards compatibility. Use C instead. - SV PL_sv_no + NV scan_hex(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file intrpvar.h +Found in file numeric.c -=item PL_sv_undef +=item scan_oct -This is the C SV. Always refer to this as C<&PL_sv_undef>. +For backwards compatibility. Use C instead. - SV PL_sv_undef + NV scan_oct(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file intrpvar.h +Found in file numeric.c -=item PL_sv_yes -This is the C SV. See C. Always refer to this as -C<&PL_sv_yes>. +=back - SV PL_sv_yes +=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 intrpvar.h +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 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 @@ -1745,202 +2080,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. - (whatever) RETVAL + 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 Safefree +=item XSRETURN_IV -The XSUB-writer's interface to the C C function. +Return an integer from an XSUB immediately. Uses C. - void Safefree(void* ptr) + void XSRETURN_IV(IV iv) =for hackers -Found in file handy.h +Found in file XSUB.h -=item savepv +=item XSRETURN_NO -Copy a string to a safe spot. This does not use an SV. +Return C<&PL_sv_no> from an XSUB immediately. Uses C. - char* savepv(const char* sv) + XSRETURN_NO; =for hackers -Found in file util.c +Found in file XSUB.h -=item savepvn +=item XSRETURN_NV -Copy a string to a safe spot. The C indicates number of bytes to -copy. This does not use an SV. +Return a double from an XSUB immediately. Uses C. - char* savepvn(const char* sv, I32 len) + void XSRETURN_NV(NV nv) =for hackers -Found in file util.c +Found in file XSUB.h -=item SAVETMPS +=item XSRETURN_PV -Opening bracket for temporaries on a callback. See C and -L. +Return a copy of a string from an XSUB immediately. Uses C. - SAVETMPS; + void XSRETURN_PV(char* str) =for hackers -Found in file scope.h +Found in file XSUB.h -=item SP +=item XSRETURN_UNDEF -Stack pointer. This is usually handled by C. See C and -C. +Return C<&PL_sv_undef> from an XSUB immediately. Uses C. + + XSRETURN_UNDEF; =for hackers -Found in file pp.h +Found in file XSUB.h -=item SPAGAIN +=item XSRETURN_YES -Refetch the stack pointer. Used after a callback. See L. +Return C<&PL_sv_yes> from an XSUB immediately. Uses C. - SPAGAIN; + XSRETURN_YES; =for hackers -Found in file pp.h +Found in file XSUB.h -=item ST +=item XST_mIV -Used to access elements on the XSUB's stack. +Place an integer into the specified position C on the stack. The +value is stored in a new mortal SV. - SV* ST(int ix) + void XST_mIV(int pos, IV iv) =for hackers Found in file XSUB.h -=item strEQ +=item XST_mNO -Test two strings to see if they are equal. Returns true or false. +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 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 + + +=back + +=head1 SV Manipulation Functions + +=over 8 + +=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. + +NOTE: the perl_ form of this function is deprecated. + + SV* get_sv(const char* name, I32 create) + +=for hackers +Found in file perl.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) + +=for hackers +Found in file sv.c + +=item newRV_inc + +Creates an RV wrapper for an SV. The reference count for the original SV is +incremented. + + SV* newRV_inc(SV* sv) + +=for hackers +Found in file sv.h + +=item newRV_noinc + +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 sv.c + +=item newSV + +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 sv.c + +=item newSViv + +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. + + SV* newSViv(IV i) + +=for hackers +Found in file sv.c + +=item newSVnv + +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. + + SV* newSVnv(NV n) + +=for hackers +Found in file sv.c + +=item newSVpv + +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 @@ -1970,21 +2544,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) @@ -2013,7 +2577,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) @@ -2067,17 +2631,28 @@ Found in file sv.h =item SvIV -Coerces the given SV to an integer and returns it. +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) =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 + =item SvIVX -Returns the integer which is stored in the SV, assuming SvIOK is -true. +Returns the raw value in the SV's IV slot, without checks or conversions. +Only use when you are sure SvIOK is true. See also C. IV SvIVX(SV* sv) @@ -2171,7 +2746,8 @@ Found in file sv.h =item SvNV -Coerce the given SV to a double and return it. +Coerce the given SV to a double and return it. See C for a version +which guarantees to evaluate sv only once. NV SvNV(SV* sv) @@ -2180,14 +2756,24 @@ Found in file sv.h =item SvNVX -Returns the double which is stored in the SV, assuming SvNOK is -true. +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) =for hackers 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 efficient C otherwise. + + NV SvNVx(SV* sv) + +=for hackers +Found in file sv.h + =item SvOK Returns a boolean indicating whether the value is an SV. @@ -2269,17 +2855,127 @@ 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. +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) =for hackers Found in file sv.h +=item SvPVbyte + +Like C, but converts sv to byte representation first if necessary. + + char* SvPVbyte(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvPVbytex + +Like C, but converts sv to byte representation first if necessary. +Guarantees to evaluate sv only once; use the more efficient C +otherwise. + + + char* SvPVbytex(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvPVbytex_force + +Like C, but converts sv to byte representation first if necessary. +Guarantees to evaluate sv only once; use the more efficient C +otherwise. + + char* SvPVbytex_force(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvPVbyte_force + +Like C, but converts sv to byte representation first if necessary. + + char* SvPVbyte_force(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvPVbyte_nolen + +Like C, but converts sv to byte representation first if necessary. + + char* SvPVbyte_nolen(SV* sv) + +=for hackers +Found in file sv.h + +=item SvPVutf8 + +Like C, but converts sv to utf8 first if necessary. + + char* SvPVutf8(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvPVutf8x + +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) + +=for hackers +Found in file sv.h + +=item SvPVutf8x_force + +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) + +=for hackers +Found in file sv.h + +=item SvPVutf8_force + +Like C, but converts sv to utf8 first if necessary. + + char* SvPVutf8_force(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvPVutf8_nolen + +Like C, but converts sv to utf8 first if necessary. + + char* SvPVutf8_nolen(SV* sv) + +=for hackers +Found in file sv.h + +=item SvPVx + +A version of C which guarantees to evaluate sv only once. + + char* SvPVx(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + =item SvPVX -Returns a pointer to the string in the SV. The SV must contain a +Returns a pointer to the physical string in the SV. The SV must contain a string. char* SvPVX(SV* sv) @@ -2289,18 +2985,31 @@ 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) =for hackers Found in file sv.h +=item SvPV_force_nomg + +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) + +=for hackers +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) @@ -2370,235 +3079,315 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h -=item SvSETMAGIC +=item SvSTASH -Invokes C on an SV if it has 'set' magic. This macro evaluates its -argument more than once. +Returns the stash of the SV. - void SvSETMAGIC(SV* sv) + HV* SvSTASH(SV* sv) =for hackers Found in file sv.h -=item SvSetSV +=item SvTAINT -Calls C if dsv is not the same as ssv. May evaluate arguments -more than once. +Taints an SV if tainting is enabled - void SvSetSV(SV* dsb, SV* ssv) + void SvTAINT(SV* sv) =for hackers Found in file sv.h -=item SvSetSV_nosteal +=item SvTAINTED -Calls a non-destructive version of C if dsv is not the same as -ssv. May evaluate arguments more than once. +Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if +not. - void SvSetSV_nosteal(SV* dsv, SV* ssv) + bool SvTAINTED(SV* sv) =for hackers Found in file sv.h -=item SvSTASH +=item SvTAINTED_off -Returns the stash of the SV. +Untaints an SV. Be I careful with this routine, as it short-circuits +some of Perl's fundamental security features. XS module authors should not +use this function unless they fully understand all the implications of +unconditionally untainting the value. Untainting should be done in the +standard perl fashion, via a carefully crafted regexp, rather than directly +untainting variables. - HV* SvSTASH(SV* sv) + void SvTAINTED_off(SV* sv) =for hackers Found in file sv.h -=item SvTAINT +=item SvTAINTED_on -Taints an SV if tainting is enabled +Marks an SV as tainted. - void SvTAINT(SV* sv) + void SvTAINTED_on(SV* sv) =for hackers Found in file sv.h -=item SvTAINTED +=item SvTRUE -Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if -not. +Returns a boolean indicating whether Perl would evaluate the SV as true or +false, defined or undefined. Does not handle 'get' magic. - bool SvTAINTED(SV* sv) + bool SvTRUE(SV* sv) + +=for hackers +Found in file sv.h + +=item SvTYPE + +Returns the type of the SV. See C. + + svtype SvTYPE(SV* sv) + +=for hackers +Found in file sv.h + +=item SvUNLOCK + +Releases a mutual exclusion lock on sv if a suitable module +has been loaded. + + + void SvUNLOCK(SV* sv) + +=for hackers +Found in file sv.h + +=item SvUOK + +Returns a boolean indicating whether the SV contains an unsigned integer. + + void SvUOK(SV* sv) + +=for hackers +Found in file sv.h + +=item SvUPGRADE + +Used to upgrade an SV to a more complex form. Uses C to +perform the upgrade if necessary. See C. + + void SvUPGRADE(SV* sv, svtype type) =for hackers Found in file sv.h -=item SvTAINTED_off +=item SvUTF8 -Untaints an SV. Be I careful with this routine, as it short-circuits -some of Perl's fundamental security features. XS module authors should not -use this function unless they fully understand all the implications of -unconditionally untainting the value. Untainting should be done in the -standard perl fashion, via a carefully crafted regexp, rather than directly -untainting variables. +Returns a boolean indicating whether the SV contains UTF-8 encoded data. - void SvTAINTED_off(SV* sv) + void SvUTF8(SV* sv) =for hackers Found in file sv.h -=item SvTAINTED_on +=item SvUTF8_off -Marks an SV as tainted. +Unsets the UTF8 status of an SV. - void SvTAINTED_on(SV* sv) + void SvUTF8_off(SV *sv) =for hackers Found in file sv.h -=item SvTRUE +=item SvUTF8_on -Returns a boolean indicating whether Perl would evaluate the SV as true or -false, defined or undefined. Does not handle 'get' magic. +Turn on the UTF8 status of an SV (the data is not changed, just the flag). +Do not use frivolously. - bool SvTRUE(SV* sv) + void SvUTF8_on(SV *sv) =for hackers Found in file sv.h -=item svtype +=item SvUV -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. +Coerces the given SV to an unsigned integer and returns it. See C +for a version which guarantees to evaluate sv only once. + + UV SvUV(SV* sv) =for hackers Found in file sv.h -=item SvTYPE +=item SvUVX -Returns the type of the SV. See C. +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. - svtype SvTYPE(SV* sv) + UV SvUVX(SV* sv) =for hackers Found in file sv.h -=item SVt_IV +=item SvUVx -Integer type flag for scalars. See 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) =for hackers Found in file sv.h -=item SVt_NV +=item sv_2bool -Double type flag for scalars. See C. +This function is only called on magical items, and is only used by +sv_true() or its macro equivalent. + + bool sv_2bool(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SVt_PV +=item sv_2cv -Pointer type flag for scalars. See C. +Using various gambits, try to get a CV from an SV; in addition, try if +possible to set C<*st> and C<*gvp> to the stash and GV associated with it. + + CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) =for hackers -Found in file sv.h +Found in file sv.c -=item SVt_PVAV +=item sv_2io -Type flag for arrays. See C. +Using various gambits, try to get an IO from an SV: the IO slot if its a +GV; or the recursive result if we're an RV; or the IO slot of the symbol +named after the PV if we're a string. + + IO* sv_2io(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SVt_PVCV +=item sv_2iv -Type flag for code refs. See C. +Return the integer value of an SV, doing any necessary string conversion, +magic etc. Normally used via the C and C macros. + + IV sv_2iv(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SVt_PVHV +=item sv_2mortal -Type flag for hashes. See 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) =for hackers -Found in file sv.h +Found in file sv.c -=item SVt_PVMG +=item sv_2nv -Type flag for blessed scalars. See C. +Return the num value of an SV, doing any necessary string or integer +conversion, magic etc. Normally used via the C and C +macros. + + NV sv_2nv(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SvUOK +=item sv_2pvbyte -Returns a boolean indicating whether the SV contains an unsigned integer. +Return a pointer to the byte-encoded representation of the SV, and set *lp +to its length. May cause the SV to be downgraded from UTF8 as a +side-effect. - void SvUOK(SV* sv) +Usually accessed via the C macro. + + char* sv_2pvbyte(SV* sv, STRLEN* lp) =for hackers -Found in file sv.h +Found in file sv.c -=item SvUPGRADE +=item sv_2pvbyte_nolen -Used to upgrade an SV to a more complex form. Uses C to -perform the upgrade if necessary. See C. +Return a pointer to the byte-encoded representation of the SV. +May cause the SV to be downgraded from UTF8 as a side-effect. - void SvUPGRADE(SV* sv, svtype type) +Usually accessed via the C macro. + + char* sv_2pvbyte_nolen(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SvUTF8 +=item sv_2pvutf8 -Returns a boolean indicating whether the SV contains UTF-8 encoded data. +Return a pointer to the UTF8-encoded representation of the SV, and set *lp +to its length. May cause the SV to be upgraded to UTF8 as a side-effect. - void SvUTF8(SV* sv) +Usually accessed via the C macro. + + char* sv_2pvutf8(SV* sv, STRLEN* lp) =for hackers -Found in file sv.h +Found in file sv.c -=item SvUTF8_off +=item sv_2pvutf8_nolen -Unsets the UTF8 status of an SV. +Return a pointer to the UTF8-encoded representation of the SV. +May cause the SV to be upgraded to UTF8 as a side-effect. - void SvUTF8_off(SV *sv) +Usually accessed via the C macro. + + char* sv_2pvutf8_nolen(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SvUTF8_on +=item sv_2pv_flags -Turn on the UTF8 status of an SV (the data is not changed, just the flag). -Do not use frivolously. +Returns a pointer to the string value of an SV, and sets *lp to its length. +If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string +if necessary. +Normally invoked via the C macro. C and C +usually end up here too. - void SvUTF8_on(SV *sv) + char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags) =for hackers -Found in file sv.h - -=item SvUV +Found in file sv.c -Coerces the given SV to an unsigned integer and returns it. +=item sv_2pv_nolen - UV SvUV(SV* sv) +Like C, but doesn't return the length too. You should usually +use the macro wrapper C instead. + char* sv_2pv_nolen(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item SvUVX +=item sv_2uv -Returns the unsigned integer which is stored in the SV, assuming SvIOK is -true. +Return the unsigned integer value of an SV, doing any necessary string +conversion, magic etc. Normally used via the C and C +macros. - UV SvUVX(SV* sv) + UV sv_2uv(SV* sv) =for hackers -Found in file sv.h +Found in file sv.c -=item sv_2mortal +=item sv_backoff -Marks an SV as mortal. The SV will be destroyed when the current context -ends. +Remove any string offset. You should normally use the C macro +wrapper instead. - SV* sv_2mortal(SV* sv) + int sv_backoff(SV* sv) =for hackers Found in file sv.c @@ -2730,7 +3519,7 @@ Found in file sv.c Efficient removal of characters from the beginning of the string buffer. SvPOK(sv) must be true and the C must be a pointer to somewhere inside the string buffer. The C becomes the first character of the adjusted -string. +string. Uses the "OOK hack". void sv_chop(SV* sv, char* ptr) @@ -2739,188 +3528,409 @@ Found in file sv.c =item sv_clear -Clear an SV, making it empty. Does not free the memory used by the SV -itself. +Clear an SV: call any destructors, free up any memory used by the body, +and free the body itself. The SV's head is I freed, although +its type is set to all 1's so that it won't inadvertently be assumed +to be live during global destruction etc. +This function should only be called when REFCNT is zero. Most of the time +you'll want to call C (or its macro wrapper C) +instead. void sv_clear(SV* sv) =for hackers Found in file sv.c -=item sv_cmp +=item sv_cmp + +Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the +string in C is less than, equal to, or greater than the string in +C. Is UTF-8 and 'use bytes' aware, handles get magic, and will +coerce its args to strings if necessary. See also C. + + I32 sv_cmp(SV* sv1, SV* sv2) + +=for hackers +Found in file sv.c + +=item sv_cmp_locale + +Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and +'use bytes' aware, handles get magic, and will coerce its args to strings +if necessary. See also C. See also C. + + I32 sv_cmp_locale(SV* sv1, SV* sv2) + +=for hackers +Found in file sv.c + +=item sv_collxfrm + +Add Collate Transform magic to an SV if it doesn't already have it. + +Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the +scalar data of the variable, but transformed to such a format that a normal +memory comparison can be used to compare the data according to the locale +settings. + + char* sv_collxfrm(SV* sv, STRLEN* nxp) + +=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 +if necessary. Handles 'get' magic. + + void sv_dec(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_derived_from + +Returns a boolean indicating whether the SV is derived from the specified +class. This is the function that implements C. It works +for class names as well as for objects. + + bool sv_derived_from(SV* sv, const char* name) + +=for hackers +Found in file universal.c + +=item sv_eq + +Returns a boolean indicating whether the strings in the two SVs are +identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will +coerce its args to strings if necessary. + + I32 sv_eq(SV* sv1, SV* sv2) + +=for hackers +Found in file sv.c + +=item sv_force_normal + +Undo various types of fakery on an SV: if the PV is a shared string, make +a private copy; if we're a ref, stop refing; if we're a glob, downgrade to +an xpvmg. See also C. + + void sv_force_normal(SV *sv) + +=for hackers +Found in file sv.c + +=item sv_force_normal_flags + +Undo various types of fakery on an SV: if the PV is a shared string, make +a private copy; if we're a ref, stop refing; if we're a glob, downgrade to +an xpvmg. The C parameter gets passed to C +when unrefing. C calls this function with flags set to 0. + + void sv_force_normal_flags(SV *sv, U32 flags) + +=for hackers +Found in file sv.c + +=item sv_free + +Decrement an SV's reference count, and if it drops to zero, call +C to invoke destructors and free up any memory used by +the body; finally, deallocate the SV's head itself. +Normally called via a wrapper macro C. + + void sv_free(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_gets + +Get a line from the filehandle and store it into the SV, optionally +appending to the currently-stored string. + + char* sv_gets(SV* sv, PerlIO* fp, I32 append) + +=for hackers +Found in file sv.c + +=item sv_grow + +Expands the character buffer in the SV. If necessary, uses C and +upgrades the SV to C. Returns a pointer to the character buffer. +Use the C wrapper instead. + + char* sv_grow(SV* sv, STRLEN newlen) + +=for hackers +Found in file sv.c + +=item sv_inc + +Auto-increment of the value in the SV, doing string to numeric conversion +if necessary. Handles 'get' magic. + + void sv_inc(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_insert + +Inserts a string at the specified offset/length within the SV. Similar to +the Perl substr() function. + + void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) + +=for hackers +Found in file sv.c + +=item sv_isa + +Returns a boolean indicating whether the SV is blessed into the specified +class. This does not check for subtypes; use C to verify +an inheritance relationship. + + int sv_isa(SV* sv, const char* name) + +=for hackers +Found in file sv.c + +=item sv_isobject + +Returns a boolean indicating whether the SV is an RV pointing to a blessed +object. If the SV is not an RV, or if the object is not blessed, then this +will return false. + + int sv_isobject(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_iv + +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. + + IV sv_iv(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_len -Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the -string in C is less than, equal to, or greater than the string in -C. +Returns the length of the string in the SV. Handles magic and type +coercion. See also C, which gives raw access to the xpv_cur slot. - I32 sv_cmp(SV* sv1, SV* sv2) + STRLEN sv_len(SV* sv) =for hackers Found in file sv.c -=item sv_cmp_locale +=item sv_len_utf8 -Compares the strings in two SVs in a locale-aware manner. See -L +Returns the number of characters in the string in an SV, counting wide +UTF8 bytes as a single character. Handles magic and type coercion. - I32 sv_cmp_locale(SV* sv1, SV* sv2) + STRLEN sv_len_utf8(SV* sv) =for hackers Found in file sv.c -=item sv_dec +=item sv_magic -Auto-decrement of the value in the SV. +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. - void sv_dec(SV* sv) + void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers Found in file sv.c -=item sv_derived_from +=item sv_magicext -Returns a boolean indicating whether the SV is derived from the specified -class. This is the function that implements C. It works -for class names as well as for objects. +Adds magic to an SV, upgrading it if necessary. Applies the +supplied vtable and returns pointer to the magic added. - bool sv_derived_from(SV* sv, const char* name) +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 universal.c +Found in file sv.c -=item sv_eq +=item sv_mortalcopy -Returns a boolean indicating whether the strings in the two SVs are -identical. +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 "soon", either by an +explicit call to FREETMPS, or by an implicit call at places such as +statement boundaries. See also C and C. - I32 sv_eq(SV* sv1, SV* sv2) + SV* sv_mortalcopy(SV* oldsv) =for hackers Found in file sv.c -=item sv_free +=item sv_newmortal -Free the memory used by an SV. +Creates a new null SV which is mortal. The reference count of the SV is +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. - void sv_free(SV* sv) + SV* sv_newmortal() =for hackers Found in file sv.c -=item sv_getcwd +=item sv_newref -Fill the sv with current working directory +Increment an SV's reference count. Use the C wrapper +instead. - int sv_getcwd(SV* sv) + SV* sv_newref(SV* sv) =for hackers -Found in file util.c +Found in file sv.c -=item sv_gets +=item sv_nolocking -Get a line from the filehandle and store it into the SV, optionally -appending to the currently-stored string. +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. - char* sv_gets(SV* sv, PerlIO* fp, I32 append) + void sv_nolocking(SV *) =for hackers -Found in file sv.c +Found in file util.c -=item sv_grow +=item sv_nosharing -Expands the character buffer in the SV. This will use C and will -upgrade the SV to C. Returns a pointer to the character buffer. -Use C. +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. - char* sv_grow(SV* sv, STRLEN newlen) + void sv_nosharing(SV *) =for hackers -Found in file sv.c +Found in file util.c -=item sv_inc +=item sv_nounlocking -Auto-increment of the value in the SV. +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_inc(SV* sv) + void sv_nounlocking(SV *) =for hackers -Found in file sv.c +Found in file util.c -=item sv_insert +=item sv_nv -Inserts a string at the specified offset/length within the SV. Similar to -the Perl substr() function. +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. - void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) + NV sv_nv(SV* sv) =for hackers Found in file sv.c -=item sv_isa +=item sv_pos_b2u -Returns a boolean indicating whether the SV is blessed into the specified -class. This does not check for subtypes; use C to verify -an inheritance relationship. +Converts the value pointed to by offsetp from a count of bytes from the +start of the string, to a count of the equivalent number of UTF8 chars. +Handles magic and type coercion. - int sv_isa(SV* sv, const char* name) + void sv_pos_b2u(SV* sv, I32* offsetp) =for hackers Found in file sv.c -=item sv_isobject +=item sv_pos_u2b -Returns a boolean indicating whether the SV is an RV pointing to a blessed -object. If the SV is not an RV, or if the object is not blessed, then this -will return false. +Converts the value pointed to by offsetp from a count of UTF8 chars from +the start of the string, to a count of the equivalent number of bytes; if +lenp is non-zero, it does the same to lenp, but this time starting from +the offset, rather than from the start of the string. Handles magic and +type coercion. - int sv_isobject(SV* sv) + void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp) =for hackers Found in file sv.c -=item sv_len +=item sv_pv -Returns the length of the string in the SV. See also C. +Use the C macro instead - STRLEN sv_len(SV* sv) + char* sv_pv(SV *sv) =for hackers Found in file sv.c -=item sv_len_utf8 +=item sv_pvbyte -Returns the number of characters in the string in an SV, counting wide -UTF8 bytes as a single character. +Use C instead. - STRLEN sv_len_utf8(SV* sv) + char* sv_pvbyte(SV *sv) =for hackers Found in file sv.c -=item sv_magic +=item sv_pvbyten -Adds magic to an SV. +A private implementation of the C macro for compilers +which can't cope with complex macro expressions. Always use the macro +instead. - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) + char* sv_pvbyten(SV *sv, STRLEN *len) =for hackers Found in file sv.c -=item sv_mortalcopy +=item sv_pvbyten_force -Creates a new SV which is a copy of the original SV. The new SV is marked -as mortal. +A private implementation of the C macro for compilers +which can't cope with complex macro expressions. Always use the macro +instead. - SV* sv_mortalcopy(SV* oldsv) + char* sv_pvbyten_force(SV* sv, STRLEN* lp) =for hackers Found in file sv.c -=item sv_newmortal +=item sv_pvn -Creates a new SV which is mortal. The reference count of the SV is set to 1. +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. - SV* sv_newmortal() + char* sv_pvn(SV *sv, STRLEN *len) =for hackers Found in file sv.c @@ -2928,6 +3938,8 @@ Found in file sv.c =item sv_pvn_force Get a sensible string out of the SV somehow. +A private implementation of the C macro for compilers which +can't cope with complex macro expressions. Always use the macro instead. char* sv_pvn_force(SV* sv, STRLEN* lp) @@ -2940,30 +3952,44 @@ Get a sensible string out of the SV somehow. If C has C bit set, will C on C if appropriate, else not. C and C are implemented in terms of this function. +You normally want to use the various wrapper macros instead: see +C and C char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags) =for hackers Found in file sv.c -=item sv_pvutf8n_force +=item sv_pvutf8 -Get a sensible UTF8-encoded string out of the SV somehow. See -L. +Use the C macro instead - char* sv_pvutf8n_force(SV* sv, STRLEN* lp) + char* sv_pvutf8(SV *sv) =for hackers Found in file sv.c -=item sv_realpath +=item sv_pvutf8n -Wrap or emulate realpath(3). +A private implementation of the C macro for compilers +which can't cope with complex macro expressions. Always use the macro +instead. - int sv_realpath(SV* sv, char *path, STRLEN len) + char* sv_pvutf8n(SV *sv, STRLEN *len) =for hackers -Found in file util.c +Found in file sv.c + +=item sv_pvutf8n_force + +A private implementation of the C macro for compilers +which can't cope with complex macro expressions. Always use the macro +instead. + + char* sv_pvutf8n_force(SV* sv, STRLEN* lp) + +=for hackers +Found in file sv.c =item sv_reftype @@ -2977,15 +4003,42 @@ Found in file sv.c =item sv_replace Make the first argument a copy of the second, then delete the original. +The target SV physically takes over ownership of the body of the source SV +and inherits its flags; however, the target keeps any magic it owns, +and any magic in the source is discarded. +Note that this is a rather specialist SV copying operation; most of the +time you'll want to use C or one of its many macro front-ends. void sv_replace(SV* sv, SV* nsv) =for hackers Found in file sv.c +=item sv_report_used + +Dump the contents of all SVs not yet freed. (Debugging aid). + + void sv_report_used() + +=for hackers +Found in file sv.c + +=item sv_reset + +Underlying implementation for the C Perl function. +Note that the perl-level function is vaguely deprecated. + + void sv_reset(char* s, HV* stash) + +=for hackers +Found in file sv.c + =item sv_rvweaken -Weaken a reference. +Weaken a reference: set the C flag on this RV; give the +referred-to SV C magic if it hasn't already; and +push a back-reference to this RV onto the array of backreferences +associated with that magic. SV* sv_rvweaken(SV *sv) @@ -2994,8 +4047,8 @@ Found in file sv.c =item sv_setiv -Copies an integer into the given SV. Does not handle 'set' magic. See -C. +Copies an integer into the given SV, upgrading first if necessary. +Does not handle 'set' magic. See also C. void sv_setiv(SV* sv, IV num) @@ -3013,8 +4066,8 @@ Found in file sv.c =item sv_setnv -Copies a double into the given SV. Does not handle 'set' magic. See -C. +Copies a double into the given SV, upgrading first if necessary. +Does not handle 'set' magic. See also C. void sv_setnv(SV* sv, NV num) @@ -3059,25 +4112,6 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_setpviv - -Copies an integer into the given SV, also updating its string value. -Does not handle 'set' magic. See C. - - void sv_setpviv(SV* sv, IV num) - -=for hackers -Found in file sv.c - -=item sv_setpviv_mg - -Like C, but also handles 'set' magic. - - void sv_setpviv_mg(SV *sv, IV iv) - -=for hackers -Found in file sv.c - =item sv_setpvn Copies a string into an SV. The C parameter indicates the number of @@ -3182,10 +4216,15 @@ Found in file sv.c =item sv_setsv -Copies the contents of the source SV C into the destination SV C. -The source SV may be destroyed if it is mortal. Does not handle 'set' -magic. See the macro forms C, C and -C. +Copies the contents of the source SV C into the destination SV +C. The source SV may be destroyed if it is mortal, so don't use this +function if the source SV needs to be reused. Does not handle 'set' magic. +Loosely speaking, it performs a copy-by-value, obliterating any previous +content of the destination. + +You probably want to use one of the assortment of wrappers, such as +C, C, C and +C. void sv_setsv(SV* dsv, SV* ssv) @@ -3194,11 +4233,21 @@ Found in file sv.c =item sv_setsv_flags -Copies the contents of the source SV C into the destination SV C. -The source SV may be destroyed if it is mortal. Does not handle 'set' -magic. If C has C bit set, will C on C if -appropriate, else not. C and C are implemented -in terms of this function. +Copies the contents of the source SV C into the destination SV +C. The source SV may be destroyed if it is mortal, so don't use this +function if the source SV needs to be reused. Does not handle 'set' magic. +Loosely speaking, it performs a copy-by-value, obliterating any previous +content of the destination. +If the C parameter has the C bit set, will C on +C if appropriate, else not. C and C are +implemented in terms of this function. + +You probably want to use one of the assortment of wrappers, such as +C, C, C and +C. + +This is the primary function for copying scalars, and most other +copy-ish functions and macros use this underneath. void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags) @@ -3216,8 +4265,8 @@ Found in file sv.c =item sv_setuv -Copies an unsigned integer into the given SV. Does not handle 'set' magic. -See C. +Copies an unsigned integer into the given SV, upgrading first if necessary. +Does not handle 'set' magic. See also C. void sv_setuv(SV* sv, UV num) @@ -3233,9 +4282,27 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c +=item sv_taint + +Taint an SV. Use C instead. + void sv_taint(SV* sv) + +=for hackers +Found in file sv.c + +=item sv_tainted + +Test an SV for taintedness. Use C instead. + bool sv_tainted(SV* sv) + +=for hackers +Found in file sv.c + =item sv_true Returns true if the SV has a true value by Perl's rules. +Use the C macro instead, which may call C or may +instead use an in-line version. I32 sv_true(SV *sv) @@ -3244,7 +4311,7 @@ Found in file sv.c =item sv_unmagic -Removes magic from an SV. +Removes all magic of type C from an SV. int sv_unmagic(SV* sv, int type) @@ -3278,10 +4345,19 @@ See C. =for hackers Found in file sv.c +=item sv_untaint + +Untaint an SV. Use C instead. + void sv_untaint(SV* sv) + +=for hackers +Found in file sv.c + =item sv_upgrade -Upgrade an SV to a more complex form. Use C. See -C. +Upgrade an SV to a more complex form. Generally adds a new body type to the +SV, then copies across as much information as possible from the old body. +You generally want to use the C macro wrapper. See also C. bool sv_upgrade(SV* sv, U32 mt) @@ -3315,7 +4391,7 @@ Found in file sv.c =item sv_utf8_decode Convert the octets in the PV from UTF-8 to chars. Scan for validity and then -turn of SvUTF8 if needed so that we see characters. Used as a building block +turn off SvUTF8 if needed so that we see characters. Used as a building block for decode_utf8 in Encode.xs NOTE: this function is experimental and may change or be @@ -3333,6 +4409,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. @@ -3355,10 +4434,13 @@ Found in file sv.c =item sv_utf8_upgrade Convert the PV of an SV to its UTF8-encoded form. -Forces the SV to string form it it is not already. +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 @@ -3367,68 +4449,290 @@ Found in file sv.c =item sv_utf8_upgrade_flags Convert the PV of an SV to its UTF8-encoded form. -Forces the SV to string form it it is not already. +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. 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 +Found in file sv.c + +=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 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. - void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) +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. + +The "swashp" is a pointer to the swash to use. + +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. + +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(). + +The "normal" is a string like "ToLower" which means the swash +%utf8::ToLower. + + 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). - void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) +The first character of the foldcased version is returned +(but note, as explained above, that there may be more.) + + 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 @@ -3570,223 +4874,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 @@ -3810,15 +5065,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