From: Gisle Aas Date: Mon, 16 Feb 1998 11:23:53 +0000 (+0100) Subject: perlguts update X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e89caa191d6b6ba014c124286650efba73f498a6;p=p5sagit%2Fp5-mst-13.2.git perlguts update p4raw-id: //depot/perl@547 --- diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 111baf0..4ef8c22 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -1417,13 +1417,11 @@ are subject to the same restrictions as in the pass 2. This is a listing of functions, macros, flags, and variables that may be useful to extension writers or that may be found while reading other extensions. +The sort order of the listing is case insensitive, with any +occurrences of '_' ignored for the the purpose of sorting. =over 8 -=item AvFILL - -Same as C. - =item av_clear Clears an array, making it empty. Does not free the memory used by the @@ -1449,6 +1447,10 @@ information on how to use this function on tied arrays. SV** av_fetch (AV* ar, I32 key, I32 lval) +=item AvFILL + +Same as C. + =item av_len Returns the highest index in the array. Returns -1 if the array is empty. @@ -1523,7 +1525,7 @@ 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. - (void) Copy( s, d, n, t ) + void Copy( s, d, n, t ) =item croak @@ -1534,7 +1536,7 @@ function the same way you use the C C function. See C. Returns the stash of the CV. - HV * CvSTASH( SV* sv ) + HV* CvSTASH( SV* sv ) =item DBsingle @@ -1598,6 +1600,22 @@ Used to extend the argument stack for an XSUB's return values. EXTEND( sp, int x ) +=item fbm_compile + +Analyses the string in order to make fast searches on it using fbm_instr() -- +the Boyer-Moore algorithm. + + void fbm_compile(SV* sv) + +=item fbm_instr + +Returns the location of the SV in the string delimited by C and +C. It returns C if the string can't be found. The +C does not have to be fbm_compiled, but the search will not be as +fast then. + + char* fbm_instr(char *str, char *strend, SV *sv) + =item FREETMPS Closing bracket for temporaries on a callback. See C and @@ -1637,10 +1655,6 @@ Indicates that no arguments are being sent to a callback. See L. Used to indicate scalar context. See C, C, and L. -=item G_VOID - -Used to indicate void context. See C and L. - =item gv_fetchmeth Returns the glob with the given C and a defined subroutine or @@ -1692,6 +1706,10 @@ C apply equally to these functions. GV* gv_fetchmethod (HV* stash, char* name) GV* gv_fetchmethod_autoload (HV* stash, char* name, I32 autoload) +=item G_VOID + +Used to indicate void context. See C and L. + =item gv_stashpv Returns a pointer to the stash for a specified package. If C is set @@ -1718,9 +1736,9 @@ C pointer is to be expected. (For information only--not to be used). =item HeHASH -Returns the computed hash (type C) stored in the hash entry. +Returns the computed hash stored in the hash entry. - HeHASH(HE* he) + U32 HeHASH(HE* he) =item HeKEY @@ -1729,7 +1747,7 @@ The pointer may be either C or C, depending on the value of C. Can be assigned to. The C or C macros are usually preferable for finding the value of a key. - HeKEY(HE* he) + char* HeKEY(HE* he) =item HeKLEN @@ -1738,7 +1756,7 @@ holds an C key. Otherwise, holds the actual length of the key. Can be assigned to. The C macro is usually preferable for finding key lengths. - HeKLEN(HE* he) + int HeKLEN(HE* he) =item HePV @@ -1752,7 +1770,7 @@ or similar is not a good way to find the length of hash keys. This is very similar to the C macro described elsewhere in this document. - HePV(HE* he, STRLEN len) + char* HePV(HE* he, STRLEN len) =item HeSVKEY @@ -1899,7 +1917,7 @@ Returns entries from a hash iterator. See C. Performs an C, C, and C in one operation. - SV * hv_iternextsv (HV* hv, char** key, I32* retlen) + SV* hv_iternextsv (HV* hv, char** key, I32* retlen) =item hv_iterval @@ -1918,7 +1936,7 @@ Adds magic to a hash. See C. Returns the package name of a stash. See C, C. - char *HvNAME (HV* stash) + char* HvNAME (HV* stash) =item hv_store @@ -1964,38 +1982,38 @@ Undefines the hash. Returns a boolean indicating whether the C C is an ascii alphanumeric character or digit. - int isALNUM (char c) + int isALNUM (char c) =item isALPHA Returns a boolean indicating whether the C C is an ascii alphabetic character. - int isALPHA (char c) + int isALPHA (char c) =item isDIGIT Returns a boolean indicating whether the C C is an ascii digit. - int isDIGIT (char c) + int isDIGIT (char c) =item isLOWER Returns a boolean indicating whether the C C is a lowercase character. - int isLOWER (char c) + int isLOWER (char c) =item isSPACE Returns a boolean indicating whether the C C is whitespace. - int isSPACE (char c) + int isSPACE (char c) =item isUPPER Returns a boolean indicating whether the C C is an uppercase character. - int isUPPER (char c) + int isUPPER (char c) =item items @@ -2013,6 +2031,13 @@ Closing bracket on a callback. See C and L. LEAVE; +=item looks_like_number + +Test if an the content of an SV looks like a number (or is a number). + + int looks_like_number(SV*) + + =item MARK Stack marker variable for the XSUB. See C. @@ -2071,7 +2096,7 @@ The XSUB-writer's interface to the C C function. The C is the source, C is the destination, C is the number of items, and C is the type. Can do overlapping moves. See also C. - (void) Move( s, d, n, t ) + void Move( s, d, n, t ) =item na @@ -2082,20 +2107,7 @@ string length. The XSUB-writer's interface to the C C function. - void * New( x, void *ptr, int size, type ) - -=item Newc - -The XSUB-writer's interface to the C C function, with cast. - - void * Newc( x, void *ptr, int size, type, cast ) - -=item Newz - -The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. - - void * Newz( x, void *ptr, int size, type ) + void* New( x, void *ptr, int size, type ) =item newAV @@ -2103,6 +2115,12 @@ Creates a new AV. The reference count is set to 1. AV* newAV (void) +=item Newc + +The XSUB-writer's interface to the C C function, with cast. + + void* Newc( x, void *ptr, int size, type, cast ) + =item newHV Creates a new HV. The reference count is set to 1. @@ -2127,10 +2145,12 @@ SV is B incremented. =item NEWSV -Creates a new SV. The C parameter indicates the number of bytes of -preallocated string space the SV should have. The reference count for the -new SV is set to 1. C is an integer id between 0 and 1299 (used to -identify leaks). +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). SV* NEWSV (int id, STRLEN len) @@ -2155,6 +2175,13 @@ SV is set to 1. If C is zero then Perl will compute the length. SV* newSVpv (char* s, STRLEN len) +=item newSVpvf + +Creates a new SV an initialize it with the string formatted like +C. + + SV* newSVpvf(const char* pat, ...); + =item newSVpvn Creates a new SV and copies a string into it. The reference count for the @@ -2187,6 +2214,13 @@ Used by C to hook up XSUBs as Perl subs. Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to the subs. +=item Newz + +The XSUB-writer's interface to the C C function. The allocated +memory is zeroed with C. + + void* Newz( x, void *ptr, int size, type ) + =item Nullav Null AV pointer. @@ -2315,31 +2349,31 @@ Tells a Perl interpreter to run. See L. Pops an integer off the stack. - int POPi() + int POPi() =item POPl Pops a long off the stack. - long POPl() + long POPl() =item POPp Pops a string off the stack. - char * POPp() + char* POPp() =item POPn Pops a double off the stack. - double POPn() + double POPn() =item POPs Pops an SV off the stack. - SV* POPs() + SV* POPs() =item PUSHMARK @@ -2352,14 +2386,14 @@ Opening bracket for arguments on a callback. See C and L. Push an integer onto the stack. The stack must have room for this element. Handles 'set' magic. See C. - PUSHi(int d) + void PUSHi(int d) =item PUSHn Push a double onto the stack. The stack must have room for this element. Handles 'set' magic. See C. - PUSHn(double d) + void PUSHn(double d) =item PUSHp @@ -2367,14 +2401,22 @@ Push a string onto the stack. The stack must have room for this element. The C indicates the length of the string. Handles 'set' magic. See C. - PUSHp(char *c, int len ) + void PUSHp(char *c, int len ) =item PUSHs Push an SV onto the stack. The stack must have room for this element. Does not handle 'set' magic. See C. - PUSHs(sv) + void PUSHs(sv) + +=item PUSHu + +Push an unsigned integer onto the stack. The stack must have room for +this element. See C. + + void PUSHu(unsigned int d) + =item PUTBACK @@ -2387,13 +2429,13 @@ See C and L for other uses. The XSUB-writer's interface to the C C function. - void * Renew( void *ptr, int size, type ) + void* Renew( void *ptr, int size, type ) =item Renewc The XSUB-writer's interface to the C C function, with cast. - void * Renewc( void *ptr, int size, type, cast ) + void* Renewc( void *ptr, int size, type, cast ) =item RETVAL @@ -2448,61 +2490,61 @@ Refetch the stack pointer. Used after a callback. See L. Used to access elements on the XSUB's stack. - SV* ST(int x) + SV* ST(int x) =item strEQ Test two strings to see if they are equal. Returns true or false. - int strEQ( char *s1, char *s2 ) + int strEQ( char *s1, char *s2 ) =item strGE Test two strings to see if the first, C, is greater than or equal to the second, C. Returns true or false. - int strGE( char *s1, char *s2 ) + int strGE( char *s1, char *s2 ) =item strGT Test two strings to see if the first, C, is greater than the second, C. Returns true or false. - int strGT( char *s1, char *s2 ) + int strGT( char *s1, char *s2 ) =item strLE Test two strings to see if the first, C, is less than or equal to the second, C. Returns true or false. - int strLE( char *s1, char *s2 ) + int strLE( char *s1, char *s2 ) =item strLT Test two strings to see if the first, C, is less than the second, C. Returns true or false. - int strLT( char *s1, char *s2 ) + int strLT( char *s1, char *s2 ) =item strNE Test two strings to see if they are different. Returns true or false. - int strNE( char *s1, char *s2 ) + int strNE( char *s1, char *s2 ) =item strnEQ Test two strings to see if they are equal. The C parameter indicates the number of bytes to compare. Returns true or false. - int strnEQ( char *s1, char *s2 ) + int strnEQ( char *s1, char *s2 ) =item strnNE Test two strings to see if they are different. The C parameter indicates the number of bytes to compare. Returns true or false. - int strnNE( char *s1, char *s2, int len ) + int strnNE( char *s1, char *s2, int len ) =item sv_2mortal @@ -2573,6 +2615,16 @@ Like C, but also handles 'set' magic. void sv_catsv_mg (SV* dsv, SV* ssv) +=item sv_chop + +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. + + void sv_chop(SV* sv, char *ptr) + + =item sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the @@ -2585,13 +2637,13 @@ C. Returns the length of the string which is in the SV. See C. - int SvCUR (SV* sv) + int SvCUR (SV* sv) =item SvCUR_set Set the length of the string which is in the SV. See C. - SvCUR_set (SV* sv, int val ) + void SvCUR_set (SV* sv, int val ) =item sv_dec @@ -2599,12 +2651,19 @@ Auto-decrement of the value in the SV. void sv_dec (SV* sv) +=item sv_derived_from + +Returns a boolean indicating whether the SV is a subclass of the +specified class. + + int sv_derived_from(SV* sv, char* class) + =item SvEND Returns a pointer to the last character in the string which is in the SV. See C. Access the character as - *SvEND(sv) + char* SvEND(sv) =item sv_eq @@ -2622,10 +2681,12 @@ its argument more than once. =item SvGROW -Expands the character buffer in the SV. Calls C to perform the -expansion if necessary. Returns a pointer to the character buffer. +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. Returns a pointer to the character buffer. - char * SvGROW( SV* sv, int len ) + char* SvGROW( SV* sv, int len ) =item sv_grow @@ -2639,36 +2700,44 @@ Auto-increment of the value in the SV. void sv_inc (SV* sv) +=item sv_insert + +Inserts a string at the specified offset/length within the SV. +Similar to the Perl substr() function. + + void sv_insert(SV *sv, STRLEN offset, STRLEN len, + char *str, STRLEN strlen) + =item SvIOK Returns a boolean indicating whether the SV contains an integer. - int SvIOK (SV* SV) + int SvIOK (SV* SV) =item SvIOK_off Unsets the IV status of an SV. - SvIOK_off (SV* sv) + void SvIOK_off (SV* sv) =item SvIOK_on Tells an SV that it is an integer. - SvIOK_on (SV* sv) + void SvIOK_on (SV* sv) =item SvIOK_only Tells an SV that it is an integer and disables all other OK bits. - SvIOK_on (SV* sv) + void SvIOK_only (SV* sv) =item SvIOKp Returns a boolean indicating whether the SV contains an integer. Checks the B setting. Use C. - int SvIOKp (SV* SV) + int SvIOKp (SV* SV) =item sv_isa @@ -2678,12 +2747,6 @@ an inheritance relationship. int sv_isa (SV* sv, char* name) -=item SvIV - -Returns the integer which is in the SV. - - int SvIV (SV* sv) - =item sv_isobject Returns a boolean indicating whether the SV is an RV pointing to a blessed @@ -2692,17 +2755,23 @@ will return false. int sv_isobject (SV* sv) +=item SvIV + +Returns the integer which is in the SV. + + int SvIV (SV* sv) + =item SvIVX Returns the integer which is stored in the SV. - int SvIVX (SV* sv) + int SvIVX (SV* sv) =item SvLEN Returns the size of the string buffer in the SV. See C. - int SvLEN (SV* sv) + int SvLEN (SV* sv) =item sv_len @@ -2723,115 +2792,124 @@ as mortal. SV* sv_mortalcopy (SV* oldsv) -=item SvOK - -Returns a boolean indicating whether the value is an SV. - - int SvOK (SV* sv) - =item sv_newmortal Creates a new SV which is mortal. The reference count of the SV is set to 1. SV* sv_newmortal (void) -=item sv_no - -This is the C SV. See C. Always refer to this as C<&sv_no>. - =item SvNIOK Returns a boolean indicating whether the SV contains a number, integer or double. - int SvNIOK (SV* SV) + int SvNIOK (SV* SV) =item SvNIOK_off Unsets the NV/IV status of an SV. - SvNIOK_off (SV* sv) + void SvNIOK_off (SV* sv) =item SvNIOKp Returns a boolean indicating whether the SV contains a number, integer or double. Checks the B setting. Use C. - int SvNIOKp (SV* SV) + int SvNIOKp (SV* SV) + +=item sv_no + +This is the C SV. See C. Always refer to this as C<&sv_no>. =item SvNOK Returns a boolean indicating whether the SV contains a double. - int SvNOK (SV* SV) + int SvNOK (SV* SV) =item SvNOK_off Unsets the NV status of an SV. - SvNOK_off (SV* sv) + void SvNOK_off (SV* sv) =item SvNOK_on Tells an SV that it is a double. - SvNOK_on (SV* sv) + void SvNOK_on (SV* sv) =item SvNOK_only Tells an SV that it is a double and disables all other OK bits. - SvNOK_on (SV* sv) + void SvNOK_only (SV* sv) =item SvNOKp Returns a boolean indicating whether the SV contains a double. Checks the B setting. Use C. - int SvNOKp (SV* SV) + int SvNOKp (SV* SV) =item SvNV Returns the double which is stored in the SV. - double SvNV (SV* sv) + double SvNV (SV* sv) =item SvNVX Returns the double which is stored in the SV. - double SvNVX (SV* sv) + double SvNVX (SV* sv) + +=item SvOK + +Returns a boolean indicating whether the value is an SV. + + int SvOK (SV* sv) + +=item SvOOK + +Returns a boolean indicating whether the SvIVX is a valid offset value +for the SvPVX. This hack is used internally to speed up removal of +characters from the beginning of a SvPV. When SvOOK is true, then the +start of the allocated string buffer is really (SvPVX - SvIVX). + + int SvOOK(Sv* sv) =item SvPOK Returns a boolean indicating whether the SV contains a character string. - int SvPOK (SV* SV) + int SvPOK (SV* SV) =item SvPOK_off Unsets the PV status of an SV. - SvPOK_off (SV* sv) + void SvPOK_off (SV* sv) =item SvPOK_on Tells an SV that it is a string. - SvPOK_on (SV* sv) + void SvPOK_on (SV* sv) =item SvPOK_only Tells an SV that it is a string and disables all other OK bits. - SvPOK_on (SV* sv) + void SvPOK_only (SV* sv) =item SvPOKp Returns a boolean indicating whether the SV contains a character string. Checks the B setting. Use C. - int SvPOKp (SV* SV) + int SvPOKp (SV* SV) =item SvPV @@ -2839,49 +2917,57 @@ Returns a pointer to the string in the SV, or a stringified form of the SV if the SV does not contain a string. If C is C then Perl will handle the length on its own. Handles 'get' magic. - char * SvPV (SV* sv, int len ) + char* SvPV (SV* sv, int len ) + +=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. + + char* SvPV_force(SV* sv, int len) + =item SvPVX Returns a pointer to the string in the SV. The SV must contain a string. - char * SvPVX (SV* sv) + char* SvPVX (SV* sv) =item SvREFCNT Returns the value of the object's reference count. - int SvREFCNT (SV* sv) + int SvREFCNT (SV* sv) =item SvREFCNT_dec Decrements the reference count of the given SV. - void SvREFCNT_dec (SV* sv) + void SvREFCNT_dec (SV* sv) =item SvREFCNT_inc Increments the reference count of the given SV. - void SvREFCNT_inc (SV* sv) + void SvREFCNT_inc (SV* sv) =item SvROK Tests if the SV is an RV. - int SvROK (SV* sv) + int SvROK (SV* sv) =item SvROK_off Unsets the RV status of an SV. - SvROK_off (SV* sv) + void SvROK_off (SV* sv) =item SvROK_on Tells an SV that it is an RV. - SvROK_on (SV* sv) + void SvROK_on (SV* sv) =item SvRV @@ -2896,35 +2982,6 @@ its argument more than once. void SvSETMAGIC( SV *sv ) -=item SvTAINT - -Taints an SV if tainting is enabled - - SvTAINT (SV* sv) - -=item SvTAINTED - -Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not. - - SvTAINTED (SV* sv) - -=item SvTAINTED_off - -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. - - SvTAINTED_off (SV* sv) - -=item SvTAINTED_on - -Marks an SV as tainted. - - SvTAINTED_on (SV* sv) - =item sv_setiv Copies an integer into the given SV. Does not handle 'set' magic. @@ -3097,7 +3154,36 @@ Like C, but also handles 'set' magic. Returns the stash of the SV. - HV * SvSTASH (SV* sv) + HV* SvSTASH (SV* sv) + +=item SvTAINT + +Taints an SV if tainting is enabled + + void SvTAINT (SV* sv) + +=item SvTAINTED + +Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not. + + int SvTAINTED (SV* sv) + +=item SvTAINTED_off + +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. + + void SvTAINTED_off (SV* sv) + +=item SvTAINTED_on + +Marks an SV as tainted. + + void SvTAINTED_on (SV* sv) =item SVt_IV @@ -3132,7 +3218,7 @@ Double type flag for scalars. See C. Returns a boolean indicating whether Perl would evaluate the SV as true or false, defined or undefined. Does not handle 'get' magic. - int SvTRUE (SV* sv) + int SvTRUE (SV* sv) =item SvTYPE @@ -3145,17 +3231,6 @@ Returns the type of the SV. See C. 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. -=item SvUPGRADE - -Used to upgrade an SV to a more complex form. Uses C to perform -the upgrade if necessary. See C. - - bool SvUPGRADE (SV* sv, svtype mt) - -=item sv_upgrade - -Upgrade an SV to a more complex form. Use C. See C. - =item sv_undef This is the C SV. Always refer to this as C<&sv_undef>. @@ -3168,6 +3243,17 @@ as a reversal of C. See C. void sv_unref (SV* sv) +=item SvUPGRADE + +Used to upgrade an SV to a more complex form. Uses C to perform +the upgrade if necessary. See C. + + bool SvUPGRADE (SV* sv, svtype mt) + +=item sv_upgrade + +Upgrade an SV to a more complex form. Use C. See C. + =item sv_usepvn Tells an SV to use C to find its string value. Normally the string is @@ -3186,6 +3272,18 @@ Like C, but also handles 'set' magic. void sv_usepvn_mg (SV* sv, char* ptr, STRLEN len) +=item SvUV + +Returns the unsigned integer which is in the SV. + + UV SvUV(SV* sv) + +=item SvUVX + +Returns the unsigned integer which is stored in the SV. + + UV SvUVX(SV* sv) + =item sv_yes This is the C SV. See C. Always refer to this as C<&sv_yes>. @@ -3200,13 +3298,13 @@ L. Converts the specified character to lowercase. - int toLOWER (char c) + int toLOWER (char c) =item toUPPER Converts the specified character to uppercase. - int toUPPER (char c) + int toUPPER (char c) =item warn @@ -3241,6 +3339,11 @@ handle 'set' magic. See C. XPUSHs(sv) +=item XPUSHu + +Push an unsigned integer onto the stack, extending the stack if +necessary. See C. + =item XS Macro to declare an XSUB and its C parameter list. This is handled by @@ -3350,7 +3453,7 @@ C. See L. 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. - (void) Zero( d, n, t ) + void Zero( d, n, t ) =back