X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=2e7e59db467f877fc317927a9d3a07c1d11679bd;hb=62703e7218aceb3f5d30f70a2307dd02e5eb8c63;hp=a1ddb13f06b8f189ddaeae3aef246c08eaac3c68;hpb=cdd94ca776dceea28cef3714a8bc6d873614b2bf;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index a1ddb13..2e7e59d 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 @@ -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 @@ -1701,7 +1701,7 @@ Found in file util.c =item savesvpv -A version of C/C/C which gets the string to duplicate from the passed in SV using C char* savesvpv(SV* sv) @@ -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) + 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, 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, 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, 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 @@ -3139,22 +3186,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 efficient 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 @@ -3473,21 +3520,21 @@ Like C, but converts sv to utf8 first if necessary. =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 @@ -4249,7 +4296,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 +4385,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 +4568,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 +4601,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 @@ -5113,7 +5160,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 +5169,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 +5186,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 +5226,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,7 +5238,7 @@ 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) + bool is_utf8_string(const U8 *s, STRLEN len) =for hackers Found in file utf8.c @@ -5201,7 +5248,7 @@ Found in file utf8.c Like is_ut8_string but store the location of the failure in the last argument. - bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p) + bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p) =for hackers Found in file utf8.c @@ -5221,7 +5268,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 +5345,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 +5354,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 +5370,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 +5385,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 +5400,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 +5419,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 +5444,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 +5457,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 @@ -5438,7 +5482,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 +5511,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 +5528,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 +5536,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 +5554,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,