X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=91880e498f2528266b709d660b2c50bb753744f9;hb=038fcae385eee134ba22a23fbbf09eafafbe7927;hp=d52baf27c5a23ed1a647ed01f170afe09f3b0a5d;hpb=c55831ac3c360ec7500d3c9e928cfb5e54b0d876;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index d52baf2..91880e4 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -725,7 +725,9 @@ Found in file pp_pack.c =item unpackstring -The engine implementing unpack() Perl function. +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) @@ -1065,6 +1067,15 @@ Returns the package name of a stash. See C, C. =for hackers Found in file hv.h +=item hv_assert + +Check that a hash is in an internally consistent state. + + void hv_assert(HV* tb) + +=for hackers +Found in file hv.c + =item hv_clear Clears a hash, making it empty. @@ -1074,6 +1085,21 @@ Clears a hash, making it empty. =for hackers Found in file hv.c +=item hv_clear_placeholders + +Clears any placeholders from a hash. If a restricted hash has any of its keys +marked as readonly and the key is subsequently deleted, the key is not actually +deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags +it so it will be ignored by future operations such as iterating over the hash, +but will still allow the hash to have a value reaasigned to the key at some +future point. This function clears any such placeholder keys from the hash. +See Hash::Util::lock_keys() for an example of its use. + + void hv_clear_placeholders(HV* hb) + +=for hackers +Found in file hv.c + =item hv_delete Deletes a key/value pair in the hash. The value SV is removed from the @@ -1254,6 +1280,15 @@ Adds magic to a hash. See C. =for hackers Found in file hv.c +=item hv_scalar + +Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied. + + SV* hv_scalar(HV* hv) + +=for hackers +Found in file hv.c + =item hv_store Stores an SV in a hash. The hash key is specified as C and C is @@ -1737,15 +1772,17 @@ an RV. Function must be called with an already existing SV like - sv = NEWSV(92,0); - s = scan_version(s,sv); + sv = newSV(0); + s = scan_version(s,SV *sv, bool qv); Performs some preprocessing to the string to ensure that it has the correct characteristics of a version. Flags the object if it contains an underscore (which denotes this -is a beta version). +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) + char* scan_version(char *vstr, SV *sv, bool qv) =for hackers Found in file util.c @@ -2420,6 +2457,15 @@ Return C<&PL_sv_undef> from an XSUB immediately. Uses C. =for hackers Found in file XSUB.h +=item XSRETURN_UV + +Return an integer from an XSUB immediately. Uses C. + + void XSRETURN_UV(IV uv) + +=for hackers +Found in file XSUB.h + =item XSRETURN_YES Return C<&PL_sv_yes> from an XSUB immediately. Uses C. @@ -2778,7 +2824,7 @@ Found in file sv.h Returns a boolean indicating whether the SV contains a signed integer. - void SvIOK_notUV(SV* sv) + bool SvIOK_notUV(SV* sv) =for hackers Found in file sv.h @@ -2823,7 +2869,7 @@ Found in file sv.h Returns a boolean indicating whether the SV contains an unsigned integer. - void SvIOK_UV(SV* sv) + bool SvIOK_UV(SV* sv) =for hackers Found in file sv.h @@ -2879,6 +2925,15 @@ Only use when you are sure SvIOK is true. See also C. =for hackers Found in file sv.h +=item SvIV_nomg + +Like C but doesn't process magic. + + IV SvIV_nomg(SV* sv) + +=for hackers +Found in file sv.h + =item SvLEN Returns the size of the string buffer in the SV, not including any part @@ -3056,7 +3111,7 @@ Found in file sv.h =item SvPOK_only Tells an SV that it is a string and disables all other OK bits. -Will also turn off the UTF8 status. +Will also turn off the UTF-8 status. void SvPOK_only(SV* sv) @@ -3066,7 +3121,7 @@ Found in file sv.h =item SvPOK_only_UTF8 Tells an SV that it is a string and disables all other OK bits, -and leaves the UTF8 status as it was. +and leaves the UTF-8 status as it was. void SvPOK_only_UTF8(SV* sv) @@ -3235,6 +3290,15 @@ stringified form becoming C. Handles 'get' magic. =for hackers Found in file sv.h +=item SvPV_nomg + +Like C but doesn't process magic. + + char* SvPV_nomg(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + =item SvREFCNT Returns the value of the object's reference count. @@ -3402,14 +3466,14 @@ Found in file sv.h Returns a boolean indicating whether the SV contains UTF-8 encoded data. - void SvUTF8(SV* sv) + bool SvUTF8(SV* sv) =for hackers Found in file sv.h =item SvUTF8_off -Unsets the UTF8 status of an SV. +Unsets the UTF-8 status of an SV. void SvUTF8_off(SV *sv) @@ -3418,7 +3482,7 @@ Found in file sv.h =item SvUTF8_on -Turn on the UTF8 status of an SV (the data is not changed, just the flag). +Turn on the UTF-8 status of an SV (the data is not changed, just the flag). Do not use frivolously. void SvUTF8_on(SV *sv) @@ -3456,6 +3520,15 @@ evaluate sv only once. Use the more efficient C otherwise. =for hackers Found in file sv.h +=item SvUV_nomg + +Like C but doesn't process magic. + + UV SvUV_nomg(SV* sv) + +=for hackers +Found in file sv.h + =item SvVOK Returns a boolean indicating whether the SV contains a v-string. @@ -3496,12 +3569,13 @@ named after the PV if we're a string. =for hackers Found in file sv.c -=item sv_2iv +=item sv_2iv_flags -Return the integer value of an SV, doing any necessary string conversion, -magic etc. Normally used via the C and C macros. +Return the integer value of an SV, doing any necessary string +conversion. If flags includes SV_GMAGIC, does an mg_get() first. +Normally used via the C and C macros. - IV sv_2iv(SV* sv) + IV sv_2iv_flags(SV* sv, I32 flags) =for hackers Found in file sv.c @@ -3531,7 +3605,7 @@ Found in file sv.c =item sv_2pvbyte 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 +to its length. May cause the SV to be downgraded from UTF-8 as a side-effect. Usually accessed via the C macro. @@ -3544,7 +3618,7 @@ Found in file sv.c =item sv_2pvbyte_nolen Return a pointer to the byte-encoded representation of the SV. -May cause the SV to be downgraded from UTF8 as a side-effect. +May cause the SV to be downgraded from UTF-8 as a side-effect. Usually accessed via the C macro. @@ -3555,8 +3629,8 @@ Found in file sv.c =item sv_2pvutf8 -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. +Return a pointer to the UTF-8-encoded representation of the SV, and set *lp +to its length. May cause the SV to be upgraded to UTF-8 as a side-effect. Usually accessed via the C macro. @@ -3567,8 +3641,8 @@ Found in file sv.c =item sv_2pvutf8_nolen -Return a pointer to the UTF8-encoded representation of the SV. -May cause the SV to be upgraded to UTF8 as a side-effect. +Return a pointer to the UTF-8-encoded representation of the SV. +May cause the SV to be upgraded to UTF-8 as a side-effect. Usually accessed via the C macro. @@ -3599,13 +3673,13 @@ use the macro wrapper C instead. =for hackers Found in file sv.c -=item sv_2uv +=item sv_2uv_flags Return the unsigned integer value of an SV, doing any necessary string -conversion, magic etc. Normally used via the C and C -macros. +conversion. If flags includes SV_GMAGIC, does an mg_get() first. +Normally used via the C and C macros. - UV sv_2uv(SV* sv) + UV sv_2uv_flags(SV* sv, I32 flags) =for hackers Found in file sv.c @@ -3634,8 +3708,8 @@ Found in file sv.c =item sv_catpv Concatenates the string onto the end of the string which is in the SV. -If the SV has the UTF8 status set, then the bytes appended should be -valid UTF8. Handles 'get' magic, but not 'set' magic. See C. +If the SV has the UTF-8 status set, then the bytes appended should be +valid UTF-8. Handles 'get' magic, but not 'set' magic. See C. void sv_catpv(SV* sv, const char* ptr) @@ -3669,8 +3743,8 @@ Found in file sv.c =item sv_catpvn Concatenates the string onto the end of the string which is in the SV. The -C indicates number of bytes to copy. If the SV has the UTF8 -status set, then the bytes appended should be valid UTF8. +C indicates number of bytes to copy. If the SV has the UTF-8 +status set, then the bytes appended should be valid UTF-8. Handles 'get' magic, but not 'set' magic. See C. void sv_catpvn(SV* sv, const char* ptr, STRLEN len) @@ -3681,8 +3755,8 @@ Found in file sv.c =item sv_catpvn_flags Concatenates the string onto the end of the string which is in the SV. The -C indicates number of bytes to copy. If the SV has the UTF8 -status set, then the bytes appended should be valid UTF8. +C indicates number of bytes to copy. If the SV has the UTF-8 +status set, then the bytes appended should be valid UTF-8. If C has C bit set, will C on C if appropriate, else not. C and C are implemented in terms of this function. @@ -3981,7 +4055,7 @@ Found in file sv.c =item sv_len_utf8 Returns the number of characters in the string in an SV, counting wide -UTF8 bytes as a single character. Handles magic and type coercion. +UTF-8 bytes as a single character. Handles magic and type coercion. STRLEN sv_len_utf8(SV* sv) @@ -4066,7 +4140,7 @@ Found in file sv.c =item sv_pos_b2u 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. +start of the string, to a count of the equivalent number of UTF-8 chars. Handles magic and type coercion. void sv_pos_b2u(SV* sv, I32* offsetp) @@ -4076,7 +4150,7 @@ Found in file sv.c =item sv_pos_u2b -Converts the value pointed to by offsetp from a count of UTF8 chars from +Converts the value pointed to by offsetp from a count of UTF-8 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 @@ -4625,7 +4699,7 @@ Found in file sv.c =item sv_utf8_downgrade -Attempt to convert the PV of an SV from UTF8-encoded to byte encoding. +Attempt to convert the PV of an SV from UTF-8-encoded to byte encoding. 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. @@ -4643,7 +4717,7 @@ Found in file sv.c =item sv_utf8_encode -Convert the PV of an SV to UTF8-encoded, but then turn off the C +Convert the PV of an SV to UTF-8-encoded, but then turn off the C flag so that it looks like octets again. Used as a building block for encode_utf8 in Encode.xs @@ -4654,7 +4728,7 @@ Found in file sv.c =item sv_utf8_upgrade -Convert the PV of an SV to its UTF8-encoded form. +Convert the PV of an SV to its UTF-8-encoded form. 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. @@ -4669,7 +4743,7 @@ Found in file sv.c =item sv_utf8_upgrade_flags -Convert the PV of an SV to its UTF8-encoded form. +Convert the PV of an SV to its UTF-8-encoded form. 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, @@ -4730,7 +4804,7 @@ Found in file sv.c =item bytes_from_utf8 -Converts a string C of length C from UTF8 into byte encoding. +Converts a string C of length C from UTF-8 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 @@ -4747,11 +4821,11 @@ Found in file utf8.c =item bytes_to_utf8 -Converts a string C of length C from ASCII into UTF8 encoding. +Converts a string C of length C from ASCII into UTF-8 encoding. Returns a pointer to the newly-created string, and sets C to reflect the new length. -If you want to convert to UTF8 from other encodings than ASCII, +If you want to convert to UTF-8 from other encodings than ASCII, see sv_recode_to_utf8(). NOTE: this function is experimental and may change or be @@ -4805,15 +4879,25 @@ 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 code points above 0x7F encoded in -UTF8' because a valid ASCII string is a valid UTF8 string. +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) =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. + + bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p) + +=for hackers +Found in file utf8.c + =item pv_uni_display Build to the scalar dsv a displayable version of the string spv, @@ -4978,7 +5062,7 @@ Found in file utf8.c =item utf8n_to_uvchr Returns the native character value of the first character in the string C -which is assumed to be in UTF8 encoding; C will be set to the +which is assumed to be in UTF-8 encoding; C will be set to the length, in bytes, of that character. Allows length and flags to be passed to low level routine. @@ -4992,10 +5076,10 @@ Found in file utf8.c Bottom level UTF-8 decode routine. Returns the unicode code point value of the first character in the string C -which is assumed to be in UTF8 encoding and no longer than C; +which is assumed to be in UTF-8 encoding and no longer than C; C will be set to the length, in bytes, of that character. -If C does not point to a well-formed UTF8 character, the behaviour +If C does not point to a well-formed UTF-8 character, the behaviour is dependent on the value of C: if it contains UTF8_CHECK_ONLY, it is assumed that the caller will raise a warning, and this function will silently just set C to C<-1> and return zero. If the @@ -5015,7 +5099,7 @@ Found in file utf8.c =item utf8_distance -Returns the number of UTF8 characters between the UTF-8 pointers C +Returns the number of UTF-8 characters between the UTF-8 pointers C and C. WARNING: use only if you *know* that the pointers point inside the @@ -5053,7 +5137,7 @@ Found in file utf8.c =item utf8_to_bytes -Converts a string C of length C from UTF8 into byte encoding. +Converts a string C of length C from UTF-8 into byte encoding. Unlike C, this over-writes the original string, and updates len to contain the new length. Returns zero on failure, setting C to -1. @@ -5069,10 +5153,10 @@ Found in file utf8.c =item utf8_to_uvchr Returns the native character value of the first character in the string C -which is assumed to be in UTF8 encoding; C will be set to the +which is assumed to be in UTF-8 encoding; C will be set to the length, in bytes, of that character. -If C does not point to a well-formed UTF8 character, zero is +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) @@ -5083,13 +5167,13 @@ Found in file utf8.c =item utf8_to_uvuni Returns the Unicode code point of the first character in the string C -which is assumed to be in UTF8 encoding; C will be set to the +which is assumed to be in UTF-8 encoding; C will be set to the length, in bytes, of that character. This function should only be used when returned UV is considered an index into the Unicode semantic tables (e.g. swashes). -If C does not point to a well-formed UTF8 character, zero is +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) @@ -5099,7 +5183,7 @@ Found in file utf8.c =item uvchr_to_utf8 -Adds the UTF8 representation of the Native codepoint C to the end +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 bytes available. The return value is the pointer to the byte after the end of the new character. In other words, @@ -5117,7 +5201,7 @@ Found in file utf8.c =item uvuni_to_utf8_flags -Adds the UTF8 representation of the Unicode codepoint C to the end +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 bytes available. The return value is the pointer to the byte after the end of the new character. In other words,