X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=af2794bbb7cb73af5ac400f306f7de93bd87d404;hb=7207e29d564e32c8ec2cb43eabae72ff68c02442;hp=bee65f60fa9990cfc0e3c18231f4649478ce2b36;hpb=afd1eb533c8ea286efcac6fd054ae7cebaf0dfe3;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index bee65f6..af2794b 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -465,6 +465,26 @@ then. =for hackers Found in file util.c +=item form + +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 util.c + =item FREETMPS Closing bracket for temporaries on a callback. See C and @@ -559,12 +579,64 @@ respectively. =for hackers Found in file op.h +=item grok_bin + +converts a string representing a binary number to numeric form. + +On entry I and I<*len> give the string to scan, I<*flags> gives +conversion flags, and I should be NULL or a pointer to an NV. +The scan stops at the end of the string, or the first invalid character. +On return I<*len> is set to the length scanned string, and I<*flags> gives +output flags. + +If the value is <= UV_MAX it is returned as a UV, the output flags are clear, +and nothing is written to I<*result>. If the value is > UV_MAX C +returns UV_MAX, sets C in the output flags, +and writes the value to I<*result> (or the value is discarded if I +is NULL). + +The hex number may optionally be prefixed with "0b" or "b" unless +C is set in I<*flags> on entry. If +C is set in I<*flags> then the binary +number may use '_' characters to separate digits. + + UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) + +=for hackers +Found in file numeric.c + +=item grok_hex + +converts a string representing a hex number to numeric form. + +On entry I and I<*len> give the string to scan, I<*flags> gives +conversion flags, and I should be NULL or a pointer to an NV. +The scan stops at the end of the string, or the first non-hex-digit character. +On return I<*len> is set to the length scanned string, and I<*flags> gives +output flags. + +If the value is <= UV_MAX it is returned as a UV, the output flags are clear, +and nothing is written to I<*result>. If the value is > UV_MAX C +returns UV_MAX, sets C in the output flags, +and writes the value to I<*result> (or the value is discarded if I +is NULL). + +The hex number may optionally be prefixed with "0x" or "x" unless +C is set in I<*flags> on entry. If +C is set in I<*flags> then the hex +number may use '_' characters to separate digits. + + UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) + +=for hackers +Found in file numeric.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). +IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). If the value of the number can fit an in UV, it is returned in the *valuep IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV @@ -593,6 +665,14 @@ Scan and skip for a numeric decimal separator (radix). =for hackers Found in file numeric.c +=item grok_oct + + + UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) + +=for hackers +Found in file numeric.c + =item GvSV Return the SV from the GV. @@ -734,7 +814,7 @@ Found in file cop.h =item HEf_SVKEY This flag, used in the length slot of hash entries and magic structures, -specifies the structure contains a C pointer where a C pointer +specifies the structure contains an C pointer where a C pointer is to be expected. (For information only--not to be used). =for hackers @@ -898,7 +978,7 @@ Found in file hv.c Returns the SV which corresponds to the specified key in the hash. The C is the length of the key. If C is set then the fetch will be part of a store. Check that the return value is non-null before -dereferencing it to a C. +dereferencing it to an C. See L for more information on how to use this function on tied hashes. @@ -1048,6 +1128,22 @@ Undefines the hash. =for hackers Found in file hv.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. + +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, bool ua, I32 len1, const char* b, bool ub, I32 len2) + +=for hackers +Found in file utf8.c + =item isALNUM Returns a boolean indicating whether the C C is an ASCII alphanumeric @@ -1344,6 +1440,17 @@ SV is B incremented. =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 NEWSV Creates a new SV. A non-zero C parameter indicates the number of @@ -1357,17 +1464,6 @@ C is an integer id between 0 and 1299 (used to identify leaks). =for hackers Found in file handy.h -=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 @@ -1493,6 +1589,24 @@ memory is zeroed with C. =for hackers Found in file handy.h +=item new_vstring + +Returns a pointer to the next character after the parsed +vstring, as well as updating the passed in sv. + +Function must be called like + + sv = NEWSV(92,5); + s = new_vstring(s,sv); + +The sv must already be large enough to store the vstring +passed in. + + char* new_vstring(char *vstr, SV *sv) + +=for hackers +Found in file util.c + =item Nullav Null AV pointer. @@ -1566,7 +1680,7 @@ Found in file perl.c Shuts down a Perl interpreter. See L. - void perl_destruct(PerlInterpreter* interp) + int perl_destruct(PerlInterpreter* interp) =for hackers Found in file perl.c @@ -1789,6 +1903,19 @@ See C and L for other uses. =for hackers Found in file pp.h +=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 is currently unused but available for future extensions. +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 Renew The XSUB-writer's interface to the C C function. @@ -1870,6 +1997,108 @@ L. =for hackers Found in file scope.h +=item scan_bin + +For backwards compatibility. Use C instead. + + NV scan_bin(char* start, STRLEN len, STRLEN* retlen) + +=for hackers +Found in file numeric.c + +=item scan_hex + +For backwards compatibility. Use C instead. + + NV scan_hex(char* start, STRLEN len, STRLEN* retlen) + +=for hackers +Found in file numeric.c + +=item scan_oct + +For backwards compatibility. Use C instead. + + NV scan_oct(char* start, STRLEN len, STRLEN* retlen) + +=for hackers +Found in file numeric.c + +=item sharedsv_find + +Tries to find if a given SV has a shared backend, either by +looking at magic, or by checking if it is tied again threads::shared. + + shared_sv* sharedsv_find(SV* sv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_init + +Saves a space for keeping SVs wider than an interpreter, +currently only stores a pointer to the first interpreter. + + void sharedsv_init() + +=for hackers +Found in file sharedsv.c + +=item sharedsv_lock + +Recursive locks on a sharedsv. +Locks are dynamically scoped at the level of the first lock. + void sharedsv_lock(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_new + +Allocates a new shared sv struct, you must yourself create the SV/AV/HV. + shared_sv* sharedsv_new() + +=for hackers +Found in file sharedsv.c + +=item sharedsv_thrcnt_dec + +Decrements the threadcount of a shared sv. When a threads frontend is freed +this function should be called. + + void sharedsv_thrcnt_dec(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_thrcnt_inc + +Increments the threadcount of a sharedsv. + void sharedsv_thrcnt_inc(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sharedsv_unlock + +Recursively unlocks a shared sv. + + void sharedsv_unlock(shared_sv* ssv) + +=for hackers +Found in file sharedsv.c + +=item sortsv + +Sort an array. Here is an example: + + sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); + + void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) + +=for hackers +Found in file pp_sort.c + =item SP Stack pointer. This is usually handled by C. See C and @@ -2028,7 +2257,7 @@ Found in file sv.h Expands the character buffer in the SV so that it has room for the indicated number of bytes (remember to reserve space for an extra trailing -NUL character). Calls C to perform the expansion if necessary. +NUL character). Calls C to perform the expansion if necessary. Returns a pointer to the character buffer. char * SvGROW(SV* sv, STRLEN len) @@ -2057,7 +2286,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) @@ -2119,22 +2348,22 @@ version which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvIVx +=item SvIVX -Coerces the given SV to an integer and returns it. Guarantees to evaluate -sv only once. Use the more efficent C otherwise. +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) + IV SvIVX(SV* sv) =for hackers Found in file sv.h -=item SvIVX +=item SvIVx -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. +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) + IV SvIVx(SV* sv) =for hackers Found in file sv.h @@ -2237,7 +2466,7 @@ Found in file sv.h =item SvNVx Coerces the given SV to a double and returns it. Guarantees to evaluate -sv only once. Use the more efficent C otherwise. +sv only once. Use the more efficient C otherwise. NV SvNVx(SV* sv) @@ -2356,7 +2585,7 @@ Found in file sv.h =item SvPVbytex Like C, but converts sv to byte representation first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Guarantees to evaluate sv only once; use the more efficient C otherwise. @@ -2368,7 +2597,7 @@ Found in file sv.h =item SvPVbytex_force Like C, but converts sv to byte representation first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Guarantees to evaluate sv only once; use the more efficient C otherwise. char* SvPVbytex_force(SV* sv, STRLEN len) @@ -2389,14 +2618,14 @@ Found in file sv.h Like C, but converts sv to byte representation first if necessary. - char* SvPVbyte_nolen(SV* sv, STRLEN len) + char* SvPVbyte_nolen(SV* sv) =for hackers Found in file sv.h =item SvPVutf8 -Like C, but converts sv to uft8 first if necessary. +Like C, but converts sv to utf8 first if necessary. char* SvPVutf8(SV* sv, STRLEN len) @@ -2405,8 +2634,8 @@ Found in file sv.h =item SvPVutf8x -Like C, but converts sv to uft8 first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Like C, but converts sv to utf8 first if necessary. +Guarantees to evaluate sv only once; use the more efficient C otherwise. char* SvPVutf8x(SV* sv, STRLEN len) @@ -2416,8 +2645,8 @@ Found in file sv.h =item SvPVutf8x_force -Like C, but converts sv to uft8 first if necessary. -Guarantees to evalute sv only once; use the more efficient C +Like C, but converts sv to utf8 first if necessary. +Guarantees to evaluate sv only once; use the more efficient C otherwise. char* SvPVutf8x_force(SV* sv, STRLEN len) @@ -2427,7 +2656,7 @@ Found in file sv.h =item SvPVutf8_force -Like C, but converts sv to uft8 first if necessary. +Like C, but converts sv to utf8 first if necessary. char* SvPVutf8_force(SV* sv, STRLEN len) @@ -2436,28 +2665,28 @@ Found in file sv.h =item SvPVutf8_nolen -Like C, but converts sv to uft8 first if necessary. +Like C, but converts sv to utf8 first if necessary. - char* SvPVutf8_nolen(SV* sv, STRLEN len) + char* SvPVutf8_nolen(SV* sv) =for hackers Found in file sv.h -=item SvPVx +=item SvPVX -A version of C which guarantees to evaluate sv only once. +Returns a pointer to the physical string in the SV. The SV must contain a +string. - char* SvPVx(SV* sv, STRLEN len) + char* SvPVX(SV* sv) =for hackers Found in file sv.h -=item SvPVX +=item SvPVx -Returns a pointer to the physical string in the SV. The SV must contain a -string. +A version of C which guarantees to evaluate sv only once. - char* SvPVX(SV* sv) + char* SvPVx(SV* sv, STRLEN len) =for hackers Found in file sv.h @@ -2664,19 +2893,19 @@ false, defined or undefined. Does not handle 'get' magic. =for hackers Found in file sv.h -=item SvTYPE - -Returns the type of the SV. See C. +=item svtype - svtype SvTYPE(SV* sv) +An enum of flags for Perl types. These are found in the file B +in the C enum. Test these flags with the C macro. =for hackers Found in file sv.h -=item svtype +=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. +Returns the type of the SV. See C. + + svtype SvTYPE(SV* sv) =for hackers Found in file sv.h @@ -2800,7 +3029,7 @@ Found in file sv.h =item SvUVx Coerces the given SV to an unsigned integer and returns it. Guarantees to -evaluate sv only once. Use the more efficent C otherwise. +evaluate sv only once. Use the more efficient C otherwise. UV SvUVx(SV* sv) @@ -2810,7 +3039,7 @@ Found in file sv.h =item sv_2bool This function is only called on magical items, and is only used by -sv_true() or its macro equivalent. +sv_true() or its macro equivalent. bool sv_2bool(SV* sv) @@ -2850,8 +3079,9 @@ Found in file sv.c =item sv_2mortal -Marks an existing SV as mortal. The SV will be destroyed when the current -context ends. See also C and C. +Marks an existing SV as mortal. The SV will be destroyed "soon", either +by an explicit call to FREETMPS, or by an implicit call at places such as +statement boundaries. See also C and C. SV* sv_2mortal(SV* sv) @@ -3322,8 +3552,9 @@ Found in file sv.c =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). -The new SV is marked as mortal. It will be destroyed when the current -context ends. See also C and C. +The new SV is marked as mortal. It will be destroyed "soon", either by an +explicit call to FREETMPS, or by an implicit call at places such as +statement boundaries. See also C and C. SV* sv_mortalcopy(SV* oldsv) @@ -3333,8 +3564,9 @@ Found in file sv.c =item sv_newmortal Creates a new null SV which is mortal. The reference count of the SV is -set to 1. It will be destroyed when the current context ends. See -also C and C. +set to 1. It will be destroyed "soon", either by an explicit call to +FREETMPS, or by an implicit call at places such as statement boundaries. +See also C and C. SV* sv_newmortal() @@ -3496,6 +3728,24 @@ instead. =for hackers Found in file sv.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_reftype Returns a string describing what the SV is a reference to. @@ -3834,6 +4084,19 @@ instead use an in-line version. =for hackers Found in file sv.c +=item sv_uni_display + +Build to the scalar dsv a displayable version of the scalar sv, +he displayable version being at most pvlim bytes long +(if longer, the rest is truncated and "..." will be appended). +The flags argument is currently unused but available for future extensions. +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_unmagic Removes all magic of type C from an SV. @@ -4045,6 +4308,31 @@ Converts the specified character to uppercase. =for hackers Found in file handy.h +=item to_utf8_case + +The "p" contains the pointer to the UTF-8 string encoding +the character that is being converted. + +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 "swash" is a pointer to the swash to use. + +The "normal" is a string like "ToLower" which means the swash +$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl, +and loaded by SWASHGET, using lib/utf8_heavy.pl. + +The "special" is a string like "utf8::ToSpecLower", which means +the hash %utf8::ToSpecLower, which is stored in the same file, +lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access +to the hash is by Perl_to_utf8_case(). + + UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special) + +=for hackers +Found in file utf8.c + =item utf8n_to_uvchr Returns the native character value of the first character in the string C @@ -4185,20 +4473,28 @@ 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_flags(d, uv, flags); + +or, in most cases, + d = uvuni_to_utf8(d, uv); +(which is equivalent to) + + d = uvuni_to_utf8_flags(d, uv, 0); + is the recommended Unicode-aware way of saying *(d++) = uv; - U8* uvuni_to_utf8(U8 *d, UV uv) + U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) =for hackers Found in file utf8.c @@ -4312,7 +4608,7 @@ Found in file XSUB.h =item XSRETURN_NV -Return an double from an XSUB immediately. Uses C. +Return a double from an XSUB immediately. Uses C. void XSRETURN_NV(NV nv)