X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=d608eef3c3c4003d765c503c95a60edf5a1de671;hb=77004dee2553ce034a8a58b2b2849e3656df46c3;hp=38c5daf9160cc3408a99ea232413592f8d19d8f8;hpb=9244d4ad8d4fc2dc937da371d09c6041e465517d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 38c5daf..d608eef 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -317,13 +317,24 @@ Sort an array. Here is an example: sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); -See lib/sort.pm for details about controlling the sorting algorithm. +Currently this always uses mergesort. See sortsv_flags for a more +flexible routine. void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp) =for hackers Found in file pp_sort.c +=item sortsv_flags +X + +Sort an array, with various options. + + void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags) + +=for hackers +Found in file pp_sort.c + =back @@ -757,6 +768,17 @@ See L. =for hackers Found in file mathoms.c +=item pack_cat +X + +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, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) + +=for hackers +Found in file mathoms.c + =item sv_2pvbyte_nolen X @@ -845,7 +867,7 @@ potentially warn under some level of strict-ness. "Superseded" by sv_nosharing(). - void sv_nolocking(SV *) + void sv_nolocking(SV *sv) =for hackers Found in file mathoms.c @@ -859,7 +881,7 @@ potentially warn under some level of strict-ness. "Superseded" by sv_nosharing(). - void sv_nounlocking(SV *) + void sv_nounlocking(SV *sv) =for hackers Found in file mathoms.c @@ -962,49 +984,46 @@ being zero. See C. =for hackers Found in file mathoms.c -=item sv_uv -X +=item sv_usepvn +X -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. +Tells an SV to use C to find its string value. Implemented by +calling C with C of 0, hence does not handle 'set' +magic. See C. - UV sv_uv(SV* sv) + void sv_usepvn(SV* sv, char* ptr, STRLEN len) =for hackers Found in file mathoms.c -=item utf8n_to_uvchr -X - -flags - -Returns the native character value of the first character in the string -C -which is assumed to be in UTF-8 encoding; C will be set to the -length, in bytes, of that character. +=item sv_usepvn_mg +X -Allows length and flags to be passed to low level routine. +Like C, but also handles 'set' magic. - UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) + void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) =for hackers Found in file mathoms.c -=item uvchr_to_utf8 -X +=item sv_uv +X -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, +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. - d = uvchr_to_utf8(d, uv); + UV sv_uv(SV* sv) -is the recommended wide native character-aware way of saying +=for hackers +Found in file mathoms.c - *(d++) = uv; +=item unpack_str +X - U8* uvchr_to_utf8(U8 *d, UV uv) +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(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 mathoms.c @@ -1027,17 +1046,6 @@ The engine implementing pack() Perl function. =for hackers Found in file pp_pack.c -=item pack_cat -X - -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, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) - -=for hackers -Found in file pp_pack.c - =item unpackstring X @@ -1050,17 +1058,6 @@ Issue C before and C after the call to this function. =for hackers Found in file pp_pack.c -=item unpack_str -X - -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(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 - =back @@ -1144,6 +1141,19 @@ Return the SV from the GV. =for hackers Found in file gv.h +=item gv_const_sv +X + +If C is a typeglob whose subroutine entry is a constant sub eligible for +inlining, or C is a placeholder reference that would be promoted to such +a typeglob, then returns the value returned by the sub. Otherwise, returns +NULL. + + SV* gv_const_sv(GV* gv) + +=for hackers +Found in file gv.c + =item gv_fetchmeth X @@ -1385,7 +1395,7 @@ Found in file hv.h =item HeSVKEY X -Returns the key as an C, or C if the hash entry does not +Returns the key as an C, or C if the hash entry does not contain an C key. SV* HeSVKEY(HE* he) @@ -2000,7 +2010,7 @@ The XSUB-writer's interface to the C C function. In 5.9.3, Newx() and friends replace the older New() API, and drops the first parameter, I, a debug aid which allowed callers to identify -themselves. This aid has been superceded by a new build option, +themselves. This aid has been superseded by a new build option, PERL_MEM_LOG (see L). The older API is still there for use in XS modules supporting older perls. @@ -2034,14 +2044,34 @@ Found in file handy.h =item Poison X -Fill up memory with a pattern (byte 0xAB over and over again) that -hopefully catches attempts to access uninitialized memory. +PoisonWith(0xEF) for catching access to freed memory. void Poison(void* dest, int nitems, type) =for hackers Found in file handy.h +=item PoisonNew +X + +PoisonWith(0xAB) for catching access to allocated but uninitialized memory. + + void PoisonNew(void* dest, int nitems, type) + +=for hackers +Found in file handy.h + +=item PoisonWith +X + +Fill up memory with a byte pattern (a byte repeated over and over +again) that hopefully catches attempts to access uninitialized memory. + + void PoisonWith(void* dest, int nitems, type, U8 byte) + +=for hackers +Found in file handy.h + =item Renew X @@ -2091,8 +2121,8 @@ X Perl's version of what C would be if it existed. Returns a pointer to a newly allocated string which is a duplicate of the first -C bytes from C. The memory allocated for the new string can be -freed with the C function. +C bytes from C, plus a trailing NUL byte. The memory allocated for +the new string can be freed with the C function. char* savepvn(const char* pv, I32 len) @@ -2175,7 +2205,7 @@ Found in file util.c X 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 +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. @@ -2363,7 +2393,7 @@ Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument. Exists to avoid test for a NULL function pointer and because it could potentially warn under some level of strict-ness. - void sv_nosharing(SV *) + void sv_nosharing(SV *sv) =for hackers Found in file util.c @@ -2456,6 +2486,55 @@ Found in file util.c =back +=head1 Multicall Functions + +=over 8 + +=item dMULTICALL +X + +Declare local variables for a multicall. See L. + + dMULTICALL; + +=for hackers +Found in file cop.h + +=item MULTICALL +X + +Make a lightweight callback. See L. + + MULTICALL; + +=for hackers +Found in file cop.h + +=item POP_MULTICALL +X + +Closing bracket for a lightweight callback. +See L. + + POP_MULTICALL; + +=for hackers +Found in file cop.h + +=item PUSH_MULTICALL +X + +Opening bracket for a lightweight callback. +See L. + + PUSH_MULTICALL; + +=for hackers +Found in file cop.h + + +=back + =head1 Numeric functions =over 8 @@ -2646,7 +2725,8 @@ Found in file op.c =item newXS X -Used by C to hook up XSUBs as Perl subs. +Used by C to hook up XSUBs as Perl subs. I needs to be +static storage, as it is used directly as CvFILE(), without a copy being made. =for hackers Found in file op.c @@ -3403,18 +3483,6 @@ NOTE: the perl_ form of this function is deprecated. =for hackers Found in file perl.c -=item looks_like_number -X - -Test if the content of an SV looks like a number (or is a number). -C and C are treated as numbers (so will not issue a -non-numeric warning), even if your atof() doesn't grok them. - - I32 looks_like_number(SV* sv) - -=for hackers -Found in file sv.c - =item newRV_inc X @@ -3426,252 +3494,108 @@ incremented. =for hackers Found in file sv.h -=item newRV_noinc -X +=item SvCUR +X -Creates an RV wrapper for an SV. The reference count for the original -SV is B incremented. +Returns the length of the string which is in the SV. See C. - SV* newRV_noinc(SV *sv) + STRLEN SvCUR(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item NEWSV -X +=item SvCUR_set +X -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). +Set the current length of the string which is in the SV. See C +and C. - SV* NEWSV(int id, STRLEN len) + void SvCUR_set(SV* sv, STRLEN len) =for hackers -Found in file handy.h +Found in file sv.h -=item newSV -X +=item SvEND +X -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. +Returns a pointer to the last character in the string which is in the SV. +See C. Access the character as *(SvEND(sv)). - SV* newSV(STRLEN len) + char* SvEND(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item newSVhek -X +=item SvGAMAGIC +X -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. +Returns true if the SV has get magic or overloading. If either is true then +the scalar is active data, and has the potential to return a new value every +time it is accessed. Hence you must be careful to only read it once per user +logical operation and work with that returned value. If neither is true then +the scalar's value cannot change unless written to. - SV* newSVhek(const HEK *hek) + char* SvGAMAGIC(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item newSViv -X +=item SvGROW +X -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. +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. - SV* newSViv(IV i) + char * SvGROW(SV* sv, STRLEN len) =for hackers -Found in file sv.c +Found in file sv.h -=item newSVnv -X +=item SvIOK +X -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. +Returns a boolean indicating whether the SV contains an integer. - SV* newSVnv(NV n) + bool SvIOK(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item newSVpv -X +=item SvIOKp +X -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. If C is zero, Perl will compute the length using -strlen(). For efficiency, consider using C instead. +Returns a boolean indicating whether the SV contains an integer. Checks +the B setting. Use C. - SV* newSVpv(const char* s, STRLEN len) + bool SvIOKp(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item newSVpvf -X +=item SvIOK_notUV +X -Creates a new SV and initializes it with the string formatted like -C. +Returns a boolean indicating whether the SV contains a signed integer. - SV* newSVpvf(const char* pat, ...) + bool SvIOK_notUV(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item newSVpvn -X +=item SvIOK_off +X -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C bytes long. If the C argument is NULL the new SV will be undefined. +Unsets the IV status of an SV. - SV* newSVpvn(const char* s, STRLEN len) + void SvIOK_off(SV* sv) =for hackers -Found in file sv.c +Found in file sv.h -=item newSVpvn_share -X - -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_const == HeKEY and -hash lookup will avoid string compare. - - SV* newSVpvn_share(const char* s, I32 len, U32 hash) - -=for hackers -Found in file sv.c - -=item newSVrv -X - -Creates a new SV for the RV, C, to point to. If C is not an RV then -it will be upgraded to one. If C is non-null then the new SV will -be blessed in the specified package. The new SV is returned and its -reference count is 1. - - SV* newSVrv(SV* rv, const char* classname) - -=for hackers -Found in file sv.c - -=item newSVsv -X - -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). - - SV* newSVsv(SV* old) - -=for hackers -Found in file sv.c - -=item newSVuv -X - -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. - - SV* newSVuv(UV u) - -=for hackers -Found in file sv.c - -=item SvCUR -X - -Returns the length of the string which is in the SV. See C. - - STRLEN SvCUR(SV* sv) - -=for hackers -Found in file sv.h - -=item SvCUR_set -X - -Set the current length of the string which is in the SV. See C -and C. - - void SvCUR_set(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvEND -X - -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* sv) - -=for hackers -Found in file sv.h - -=item SvGROW -X - -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, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvIOK -X - -Returns a boolean indicating whether the SV contains an integer. - - bool SvIOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOKp -X - -Returns a boolean indicating whether the SV contains an integer. Checks -the B setting. Use C. - - bool SvIOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_notUV -X - -Returns a boolean indicating whether the SV contains a signed integer. - - bool SvIOK_notUV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_off -X - -Unsets the IV status of an SV. - - void SvIOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_on -X +=item SvIOK_on +X Tells an SV that it is an integer. @@ -4262,6 +4186,77 @@ Increments the reference count of the given SV. =for hackers Found in file sv.h +=item SvREFCNT_inc_NN +X + +Same as SvREFCNT_inc, but can only be used if you know I +is not NULL. Since we don't have to check the NULLness, it's faster +and smaller. + + SV* SvREFCNT_inc_NN(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple +X + +Same as SvREFCNT_inc, but can only be used with simple variables, not +expressions or pointer dereferences. Since we don't have to store a +temporary value, it's faster. + + SV* SvREFCNT_inc_simple(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_NN +X + +Same as SvREFCNT_inc_simple, but can only be used if you know I +is not NULL. Since we don't have to check the NULLness, it's faster +and smaller. + + SV* SvREFCNT_inc_simple_NN(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_void +X + +Same as SvREFCNT_inc_simple, but can only be used if you don't need the +return value. The macro doesn't need to return a meaningful value. + + SV* SvREFCNT_inc_simple_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_void +X + +Same as SvREFCNT_inc, but can only be used if you don't need the +return value. The macro doesn't need to return a meaningful value. + + SV* SvREFCNT_inc_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_void_NN +X + +Same as SvREFCNT_inc, but can only be used if you don't need the return +value, and you know that I is not NULL. The macro doesn't need +to return a meaningful value, or check for NULLness, so it's smaller +and faster. + + SV* SvREFCNT_inc_void_NN(SV* sv) + +=for hackers +Found in file sv.h + =item SvROK X @@ -4514,6 +4509,228 @@ Returns a boolean indicating whether the SV contains a v-string. =for hackers Found in file sv.h +=item sv_catpvn_nomg +X + +Like C but doesn't process magic. + + void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) + +=for hackers +Found in file sv.h + +=item sv_catsv_nomg +X + +Like C but doesn't process magic. + + void sv_catsv_nomg(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + +=item sv_derived_from +X + +Returns a boolean indicating whether the SV is derived from the specified +class. This is the function that implements C. It works +for class names as well as for objects. + + bool sv_derived_from(SV* sv, const char* name) + +=for hackers +Found in file universal.c + +=item sv_report_used +X + +Dump the contents of all SVs not yet freed. (Debugging aid). + + void sv_report_used() + +=for hackers +Found in file sv.c + +=item sv_setsv_nomg +X + +Like C but doesn't process magic. + + void sv_setsv_nomg(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + + +=back + +=head1 SV-Body Allocation + +=over 8 + +=item looks_like_number +X + +Test if the content of an SV looks like a number (or is a number). +C and C are treated as numbers (so will not issue a +non-numeric warning), even if your atof() doesn't grok them. + + I32 looks_like_number(SV* sv) + +=for hackers +Found in file sv.c + +=item newRV_noinc +X + +Creates an RV wrapper for an SV. The reference count for the original +SV is B incremented. + + SV* newRV_noinc(SV* sv) + +=for hackers +Found in file sv.c + +=item newSV +X + +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 +trailing 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. + +In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first +parameter, I, a debug aid which allowed callers to identify themselves. +This aid has been superseded by a new build option, PERL_MEM_LOG (see +L). The older API is still there for use in XS +modules supporting older perls. + + SV* newSV(STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVhek +X + +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 +X + +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. + + SV* newSViv(IV i) + +=for hackers +Found in file sv.c + +=item newSVnv +X + +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. + + SV* newSVnv(NV n) + +=for hackers +Found in file sv.c + +=item newSVpv +X + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. If C is zero, Perl will compute the length using +strlen(). For efficiency, consider using C instead. + + SV* newSVpv(const char* s, STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVpvf +X + +Creates a new SV and initializes it with the string formatted like +C. + + SV* newSVpvf(const char* pat, ...) + +=for hackers +Found in file sv.c + +=item newSVpvn +X + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. Note that if C is zero, Perl will create a zero length +string. You are responsible for ensuring that the source string is at least +C bytes long. If the C argument is NULL the new SV will be undefined. + + SV* newSVpvn(const char* s, STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVpvn_share +X + +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_const == HeKEY and +hash lookup will avoid string compare. + + SV* newSVpvn_share(const char* s, I32 len, U32 hash) + +=for hackers +Found in file sv.c + +=item newSVrv +X + +Creates a new SV for the RV, C, to point to. If C is not an RV then +it will be upgraded to one. If C is non-null then the new SV will +be blessed in the specified package. The new SV is returned and its +reference count is 1. + + SV* newSVrv(SV* rv, const char* classname) + +=for hackers +Found in file sv.c + +=item newSVsv +X + +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). + + SV* newSVsv(SV* old) + +=for hackers +Found in file sv.c + +=item newSVuv +X + +Creates a new SV and copies an unsigned integer into it. +The reference count for the SV is set to 1. + + SV* newSVuv(UV u) + +=for hackers +Found in file sv.c + =item sv_2bool X @@ -4530,6 +4747,7 @@ X Using various gambits, try to get a CV from an SV; in addition, try if possible to set C<*st> and C<*gvp> to the stash and GV associated with it. +The flags in C are passed to sv_fetchsv. CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) @@ -4600,6 +4818,19 @@ Usually accessed via the C macro. =for hackers Found in file sv.c +=item sv_2pvutf8 +X + +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. + + char* sv_2pvutf8(SV* sv, STRLEN* lp) + +=for hackers +Found in file sv.c + =item sv_2pv_flags X @@ -4715,16 +4946,6 @@ in terms of this function. =for hackers Found in file sv.c -=item sv_catpvn_nomg -X - -Like C but doesn't process magic. - - void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) - -=for hackers -Found in file sv.h - =item sv_catpv_mg X @@ -4760,16 +4981,6 @@ and C are implemented in terms of this function. =for hackers Found in file sv.c -=item sv_catsv_nomg -X - -Like C but doesn't process magic. - - void sv_catsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item sv_chop X @@ -4868,18 +5079,6 @@ if necessary. Handles 'get' magic. =for hackers Found in file sv.c -=item sv_derived_from -X - -Returns a boolean indicating whether the SV is derived from the specified -class. This is the function that implements C. It works -for class names as well as for objects. - - bool sv_derived_from(SV* sv, const char* name) - -=for hackers -Found in file universal.c - =item sv_eq X @@ -5048,7 +5247,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, const MGVTBL *vtbl, const char* name, I32 namlen) + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen) =for hackers Found in file sv.c @@ -5188,16 +5387,6 @@ time you'll want to use C or one of its many macro front-ends. =for hackers Found in file sv.c -=item sv_report_used -X - -Dump the contents of all SVs not yet freed. (Debugging aid). - - void sv_report_used() - -=for hackers -Found in file sv.c - =item sv_reset X @@ -5355,7 +5544,7 @@ X Copies an integer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_iv(SV* rv, const char* classname, IV iv) @@ -5369,7 +5558,7 @@ X Copies a double into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_nv(SV* rv, const char* classname, NV nv) @@ -5384,7 +5573,7 @@ Copies a pointer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. If the C argument is NULL then C will be placed into the SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. Do not use with other Perl types such as HV, AV, SV, CV, because those @@ -5404,7 +5593,7 @@ Copies a string into a new SV, optionally blessing the SV. The length of the string must be specified with C. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the blessing. Set C to -C to avoid the blessing. The new SV will have a reference count +C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. Note that C copies the pointer while this copies the string. @@ -5420,7 +5609,7 @@ X Copies an unsigned integer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_uv(SV* rv, const char* classname, UV uv) @@ -5481,16 +5670,6 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_setsv_nomg -X - -Like C but doesn't process magic. - - void sv_setsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item sv_setuv X @@ -5580,28 +5759,24 @@ You generally want to use the C macro wrapper. See also C. =for hackers Found in file sv.c -=item sv_usepvn -X +=item sv_usepvn_flags +X -Tells an SV to use C to find its string value. Normally the string is -stored inside the SV but sv_usepvn allows the SV to use an outside string. -The C should point to memory that was allocated by C. The -string length, C, must be supplied. This function will realloc the -memory pointed to by C, so that pointer should not be freed or used by -the programmer after giving it to sv_usepvn. Does not handle 'set' magic. -See C. +Tells an SV to use C to find its string value. Normally the +string is stored inside the SV but sv_usepvn allows the SV to use an +outside string. The C should point to memory that was allocated +by C. The string length, C, must be supplied. By default +this function will realloc (i.e. move) the memory pointed to by C, +so that pointer should not be freed or used by the programmer after +giving it to sv_usepvn, and neither should any pointers from "behind" +that pointer (e.g. ptr + 1) be used. - void sv_usepvn(SV* sv, char* ptr, STRLEN len) +If C & SV_SMAGIC is true, will call SvSETMAGIC. If C & +SV_HAS_TRAILING_NUL is true, then C must be NUL, and the realloc +will be skipped. (i.e. the buffer is actually at least 1 byte longer than +C, and already meets the requirements for storing in C) -=for hackers -Found in file sv.c - -=item sv_usepvn_mg -X - -Like C, but also handles 'set' magic. - - void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) + void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags) =for hackers Found in file sv.c @@ -5982,7 +6157,7 @@ of the result. The "swashp" is a pointer to the swash to use. Both the special and normal mappings are stored lib/unicore/To/Foo.pl, -and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually, +and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually, but not always, a multicharacter mapping), is tried first. The "special" is a string like "utf8::ToSpecLower", which means the @@ -6062,6 +6237,23 @@ The first character of the uppercased version is returned =for hackers Found in file utf8.c +=item utf8n_to_uvchr +X + +flags + +Returns the native character value of the first character in the string +C +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. + + UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) + +=for hackers +Found in file utf8.c + =item utf8n_to_uvuni X @@ -6137,6 +6329,8 @@ Unlike C, this over-writes the original string, and updates len to contain the new length. Returns zero on failure, setting C to -1. +If you need a copy of the string, see C. + NOTE: this function is experimental and may change or be removed without notice. @@ -6178,6 +6372,25 @@ returned and retlen is set, if possible, to -1. =for hackers Found in file utf8.c +=item uvchr_to_utf8 +X + +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, + + d = uvchr_to_utf8(d, uv); + +is the recommended wide native character-aware way of saying + + *(d++) = uv; + + U8* uvchr_to_utf8(U8 *d, UV uv) + +=for hackers +Found in file utf8.c + =item uvuni_to_utf8_flags X @@ -6422,11 +6635,11 @@ function. Calling C returns control directly to Perl, sidestepping the normal C order of execution. See C. If you want to throw an exception object, assign the object to -C<$@> and then pass C to croak(): +C<$@> and then pass C to croak(): errsv = get_sv("@", TRUE); sv_setsv(errsv, exception_object); - croak(Nullch); + croak(NULL); void croak(const char* pat, ...)