X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=6b603bf77475618777bae468d55b42f87411af10;hb=1b6737cc10a847650f574c35f419cbd680a5a5ef;hp=7f258d892c3edf518d38a1bb1fe645e7079d8b85;hpb=9c2fe30c684e721963ef24f7385a620d0e125995;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 7f258d8..6b603bf 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -179,7 +179,7 @@ Found in file av.c Returns the highest index in the array. Returns -1 if the array is empty. - I32 av_len(AV* ar) + I32 av_len(const AV* ar) =for hackers Found in file av.c @@ -693,7 +693,7 @@ Found in file perl.c The engine implementing pack() Perl function. - void packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist) + void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist) =for hackers Found in file pp_pack.c @@ -703,7 +703,7 @@ Found in file pp_pack.c The engine implementing pack() Perl function. Note: parameters next_in_list and flags are not used. This call should not be used; use packlist instead. - void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) + void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) =for hackers Found in file pp_pack.c @@ -714,7 +714,7 @@ The engine implementing unpack() Perl function. C puts the extracted list items on the stack and returns the number of elements. Issue C before and C after the call to this function. - I32 unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags) + I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags) =for hackers Found in file pp_pack.c @@ -724,7 +724,7 @@ Found in file pp_pack.c The engine implementing unpack() Perl function. Note: parameters strbeg, new_s and ocnt are not used. This call should not be used, use unpackstring instead. - I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) + I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags) =for hackers Found in file pp_pack.c @@ -1411,7 +1411,7 @@ Found in file mg.c Finds the magic pointer for type matching the SV. See C. - MAGIC* mg_find(SV* sv, int type) + MAGIC* mg_find(const SV* sv, int type) =for hackers Found in file mg.c @@ -1828,7 +1828,7 @@ is a alpha version). The boolean qv denotes that the version should be interpreted as if it had multiple decimals, even if it doesn't. - char* scan_version(char *vstr, SV *sv, bool qv) + const char* scan_version(const char *vstr, SV *sv, bool qv) =for hackers Found in file util.c @@ -2031,7 +2031,7 @@ invalid character will also trigger a warning. On return I<*len> is set to the length of the 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, +If the value is <= C 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 @@ -2042,7 +2042,7 @@ 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) + UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result) =for hackers Found in file numeric.c @@ -2070,7 +2070,7 @@ 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) + UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result) =for hackers Found in file numeric.c @@ -2130,7 +2130,7 @@ is NULL). If C is set in I<*flags> then the octal number may use '_' characters to separate digits. - UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) + UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result) =for hackers Found in file numeric.c @@ -2139,7 +2139,7 @@ Found in file numeric.c For backwards compatibility. Use C instead. - NV scan_bin(char* start, STRLEN len, STRLEN* retlen) + NV scan_bin(const char* start, STRLEN len, STRLEN* retlen) =for hackers Found in file numeric.c @@ -2148,7 +2148,7 @@ Found in file numeric.c For backwards compatibility. Use C instead. - NV scan_hex(char* start, STRLEN len, STRLEN* retlen) + NV scan_hex(const char* start, STRLEN len, STRLEN* retlen) =for hackers Found in file numeric.c @@ -2157,7 +2157,7 @@ Found in file numeric.c For backwards compatibility. Use C instead. - NV scan_oct(char* start, STRLEN len, STRLEN* retlen) + NV scan_oct(const char* start, STRLEN len, STRLEN* retlen) =for hackers Found in file numeric.c @@ -2187,7 +2187,7 @@ Found in file op.c Creates a constant sub equivalent to Perl C which is eligible for inlining at compile-time. - CV* newCONSTSUB(HV* stash, char* name, SV* sv) + CV* newCONSTSUB(HV* stash, const char* name, SV* sv) =for hackers Found in file op.c @@ -2219,6 +2219,53 @@ Found in file pad.c =back +=head1 Simple Exception Handling Macros + +=over 8 + +=item dXCPT + +Set up neccessary local variables for exception handling. +See L. + + dXCPT; + +=for hackers +Found in file XSUB.h + +=item XCPT_CATCH + +Introduces a catch block. See L. + +=for hackers +Found in file XSUB.h + +=item XCPT_RETHROW + +Rethrows a previously caught exception. See L. + + XCPT_RETHROW; + +=for hackers +Found in file XSUB.h + +=item XCPT_TRY_END + +Ends a try block. See L. + +=for hackers +Found in file XSUB.h + +=item XCPT_TRY_START + +Starts a try block. See L. + +=for hackers +Found in file XSUB.h + + +=back + =head1 Stack Manipulation Macros =over 8 @@ -2394,8 +2441,7 @@ Found in file pp.h =item POPp -Pops a string off the stack. Deprecated. New code should provide -a STRLEN n_a and use POPpx. +Pops a string off the stack. Deprecated. New code should use POPpx. char* POPp @@ -2405,7 +2451,6 @@ Found in file pp.h =item POPpbytex Pops a string off the stack which must consist of bytes i.e. characters < 256. -Requires a variable STRLEN n_a in scope. char* POPpbytex @@ -2415,7 +2460,6 @@ Found in file pp.h =item POPpx Pops a string off the stack. -Requires a variable STRLEN n_a in scope. char* POPpx @@ -2895,6 +2939,17 @@ macro. =for hackers Found in file sv.c +=item newSVhek + +Creates a new SV from the hash key structure. It will generate scalars that +point to the shared string table where possible. Returns a new (undefined) +SV if the hek is NULL. + + SV* newSVhek(const HEK *hek) + +=for hackers +Found in file sv.c + =item newSViv Creates a new SV and copies an integer into it. The reference count for the @@ -2950,12 +3005,12 @@ Found in file sv.c =item newSVpvn_share -Creates a new SV with its SvPVX pointing to a shared string in the string +Creates a new SV with its SvPVX_const 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 +is used for shared hash keys these strings will have SvPVX_const == HeKEY and hash lookup will avoid string compare. SV* newSVpvn_share(const char* s, I32 len, U32 hash) @@ -3006,7 +3061,8 @@ Found in file sv.h =item SvCUR_set -Set the length of the string which is in the SV. See C. +Set the current length of the string which is in the SV. See C +and C. void SvCUR_set(SV* sv, STRLEN len) @@ -3168,6 +3224,18 @@ Like C but doesn't process magic. =for hackers Found in file sv.h +=item SvIV_set + +Set the value of the IV pointer in sv to val. It is possible to perform +the same function of this macro with an lvalue assignment to C. +With future Perls, however, it will be more efficient to use +C instead of the lvalue assignment to C. + + void SvIV_set(SV* sv, IV val) + +=for hackers +Found in file sv.h + =item SvLEN Returns the size of the string buffer in the SV, not including any part @@ -3178,6 +3246,24 @@ attributable to C. See C. =for hackers Found in file sv.h +=item SvLEN_set + +Set the actual length of the string which is in the SV. See C. + + void SvLEN_set(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvMAGIC_set + +Set the value of the MAGIC pointer in sv to val. See C. + + void SvMAGIC_set(SV* sv, MAGIC* val) + +=for hackers +Found in file sv.h + =item SvNIOK Returns a boolean indicating whether the SV contains a number, integer or @@ -3283,6 +3369,15 @@ sv only once. Use the more efficient C otherwise. =for hackers Found in file sv.h +=item SvNV_set + +Set the value of the NV pointer in sv to val. See C. + + void SvNV_set(SV* sv, NV val) + +=for hackers +Found in file sv.h + =item SvOK Returns a boolean indicating whether the value is an SV. It also tells @@ -3534,6 +3629,15 @@ Like C but doesn't process magic. =for hackers Found in file sv.h +=item SvPV_set + +Set the value of the PV pointer in sv to val. See C. + + void SvPV_set(SV* sv, char* val) + +=for hackers +Found in file sv.h + =item SvREFCNT Returns the value of the object's reference count. @@ -3597,6 +3701,15 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h +=item SvRV_set + +Set the value of the RV pointer in sv to val. See C. + + void SvRV_set(SV* sv, SV* val) + +=for hackers +Found in file sv.h + =item SvSTASH Returns the stash of the SV. @@ -3606,6 +3719,15 @@ Returns the stash of the SV. =for hackers Found in file sv.h +=item SvSTASH_set + +Set the value of the STASH pointer in sv to val. See C. + + void SvSTASH_set(SV* sv, STASH* val) + +=for hackers +Found in file sv.h + =item SvTAINT Taints an SV if tainting is enabled. @@ -3753,6 +3875,15 @@ Like C but doesn't process magic. =for hackers Found in file sv.h +=item SvUV_set + +Set the value of the UV pointer in sv to val. See C. + + void SvUV_set(SV* sv, UV val) + +=for hackers +Found in file sv.h + =item SvVOK Returns a boolean indicating whether the SV contains a v-string. @@ -4066,10 +4197,10 @@ 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. Uses the "OOK hack". -Beware: after this function returns, C and SvPVX(sv) may no longer +Beware: after this function returns, C and SvPVX_const(sv) may no longer refer to the same chunk of data. - void sv_chop(SV* sv, char* ptr) + void sv_chop(SV* sv, const char* ptr) =for hackers Found in file sv.c @@ -4249,7 +4380,7 @@ Found in file sv.c 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) + void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen) =for hackers Found in file sv.c @@ -4338,7 +4469,7 @@ to contain an C and is stored as-is with its REFCNT incremented. (This is now used as a subroutine by C.) - MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen) + MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen) =for hackers Found in file sv.c @@ -4521,7 +4652,7 @@ Found in file sv.c Returns a string describing what the SV is a reference to. - char* sv_reftype(SV* sv, int ob) + char* sv_reftype(const SV* sv, int ob) =for hackers Found in file sv.c @@ -4554,7 +4685,7 @@ Found in file sv.c Underlying implementation for the C Perl function. Note that the perl-level function is vaguely deprecated. - void sv_reset(char* s, HV* stash) + void sv_reset(const char* s, HV* stash) =for hackers Found in file sv.c @@ -4742,7 +4873,7 @@ of 1, and the RV will be returned. Note that C copies the pointer while this copies the string. - SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) + SV* sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n) =for hackers Found in file sv.c @@ -4915,7 +5046,7 @@ 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) + void sv_upgrade(SV* sv, U32 mt) =for hackers Found in file sv.c @@ -5113,7 +5244,7 @@ Found in file sv.c =item bytes_from_utf8 Converts a string C of length C from UTF-8 into byte encoding. -Unlike but like C, returns a pointer to +Unlike C 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 @@ -5122,7 +5253,7 @@ is unchanged. Do nothing if C points to 0. Sets C to NOTE: this function is experimental and may change or be removed without notice. - U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) + U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8) =for hackers Found in file utf8.c @@ -5139,7 +5270,7 @@ see sv_recode_to_utf8(). NOTE: this function is experimental and may change or be removed without notice. - U8* bytes_to_utf8(U8 *s, STRLEN *len) + U8* bytes_to_utf8(const U8 *s, STRLEN *len) =for hackers Found in file utf8.c @@ -5179,7 +5310,7 @@ 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) + STRLEN is_utf8_char(const U8 *p) =for hackers Found in file utf8.c @@ -5191,17 +5322,36 @@ UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does not mean 'a string that contains code points above 0x7F encoded in UTF-8' because a valid ASCII string is a valid UTF-8 string. - bool is_utf8_string(U8 *s, STRLEN len) +See also is_utf8_string_loclen() and is_utf8_string_loc(). + + bool is_utf8_string(const U8 *s, STRLEN len) =for hackers Found in file utf8.c =item is_utf8_string_loc -Like is_ut8_string but store the location of the failure in -the last argument. +Like is_ut8_string() but stores the location of the failure (in the +case of "utf8ness failure") or the location s+len (in the case of +"utf8ness success") in the C. + +See also is_utf8_string_loclen() and is_utf8_string(). + + bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p) - bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p) +=for hackers +Found in file utf8.c + +=item is_utf8_string_loclen + +Like is_ut8_string() but stores the location of the failure (in the +case of "utf8ness failure") or the location s+len (in the case of +"utf8ness success") in the C, and the number of UTF-8 +encoded characters in the C. + +See also is_utf8_string_loc() and is_utf8_string(). + + bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el) =for hackers Found in file utf8.c @@ -5221,7 +5371,7 @@ 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) + char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags) =for hackers Found in file utf8.c @@ -5298,7 +5448,7 @@ 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) + UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, const char *normal, const char *special) =for hackers Found in file utf8.c @@ -5307,14 +5457,14 @@ Found in file utf8.c 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 +that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the foldcase version may be longer than the original character (up to three characters). 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) + UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp) =for hackers Found in file utf8.c @@ -5323,14 +5473,13 @@ Found in file utf8.c 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). +that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the +lowercase version may be longer than the original character. 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) + UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp) =for hackers Found in file utf8.c @@ -5339,14 +5488,13 @@ Found in file utf8.c 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). +that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the +titlecase version may be longer than the original character. 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) + UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp) =for hackers Found in file utf8.c @@ -5355,14 +5503,13 @@ Found in file utf8.c 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). +that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since +the uppercase version may be longer than the original character. 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) + UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp) =for hackers Found in file utf8.c @@ -5375,7 +5522,7 @@ length, in bytes, of that character. Allows length and flags to be passed to low level routine. - UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) + UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) =for hackers Found in file utf8.c @@ -5400,7 +5547,7 @@ the strict UTF-8 encoding (see F). Most code should use utf8_to_uvchr() rather than call this directly. - UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) + UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) =for hackers Found in file utf8.c @@ -5413,7 +5560,7 @@ and C. WARNING: use only if you *know* that the pointers point inside the same UTF-8 buffer. - IV utf8_distance(U8 *a, U8 *b) + IV utf8_distance(const U8 *a, const U8 *b) =for hackers Found in file utf8.c @@ -5427,7 +5574,7 @@ WARNING: do not use the following unless you *know* C is within the UTF-8 data pointed to by C *and* that on entry C is aligned on the first byte of character or just after the last byte of a character. - U8* utf8_hop(U8 *s, I32 off) + U8* utf8_hop(const U8 *s, I32 off) =for hackers Found in file utf8.c @@ -5438,7 +5585,7 @@ Return the length of the UTF-8 char encoded string C in characters. Stops at C (inclusive). If C s> or if the scan would end up past C, croaks. - STRLEN utf8_length(U8* s, U8 *e) + STRLEN utf8_length(const U8* s, const U8 *e) =for hackers Found in file utf8.c @@ -5467,7 +5614,7 @@ length, in bytes, of that character. If C does not point to a well-formed UTF-8 character, zero is returned and retlen is set, if possible, to -1. - UV utf8_to_uvchr(U8 *s, STRLEN* retlen) + UV utf8_to_uvchr(const U8 *s, STRLEN* retlen) =for hackers Found in file utf8.c @@ -5484,7 +5631,7 @@ an index into the Unicode semantic tables (e.g. swashes). If C does not point to a well-formed UTF-8 character, zero is returned and retlen is set, if possible, to -1. - UV utf8_to_uvuni(U8 *s, STRLEN* retlen) + UV utf8_to_uvuni(const U8 *s, STRLEN* retlen) =for hackers Found in file utf8.c @@ -5492,7 +5639,7 @@ Found in file utf8.c =item uvchr_to_utf8 Adds the UTF-8 representation of the Native codepoint C to the end -of the string C; C should be have at least C free +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, @@ -5510,7 +5657,7 @@ Found in file utf8.c =item uvuni_to_utf8_flags Adds the UTF-8 representation of the Unicode codepoint C to the end -of the string C; C should be have at least C free +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, @@ -5571,6 +5718,16 @@ This is usually handled automatically by C by calling C. =for hackers Found in file XSUB.h +=item dAXMARK + +Sets up the C variable and stack marker variable C. +This is usually handled automatically by C by calling C. + + dAXMARK; + +=for hackers +Found in file XSUB.h + =item dITEMS Sets up the C variable.