X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/2d7f66116e374c78dcf18cb5b9fea7b79ac82b5b..b9904204a39a06e70bac207805ef0ba22080bd35:/sv.h diff --git a/sv.h b/sv.h index b6da18c..e1797de 100644 --- a/sv.h +++ b/sv.h @@ -16,7 +16,7 @@ =head1 SV Flags =for apidoc AmU||svtype -An enum of flags for Perl types. These are found in the file B +An enum of flags for Perl types. These are found in the file F in the C enum. Test these flags with the C macro. The types are: @@ -41,8 +41,8 @@ The types are: These are most easily explained from the bottom up. -SVt_PVIO is for I/O objects, SVt_PVFM for formats, SVt_PVCV for -subroutines, SVt_PVHV for hashes and SVt_PVAV for arrays. +C is for I/O objects, C for formats, C for +subroutines, C for hashes and C for arrays. All the others are scalar types, that is, things that can be bound to a C<$> variable. For these, the internal types are mostly orthogonal to @@ -51,25 +51,25 @@ types in the Perl language. Hence, checking C<< SvTYPE(sv) < SVt_PVAV >> is the best way to see whether something is a scalar. -SVt_PVGV represents a typeglob. If !SvFAKE(sv), then it is a real, -incoercible typeglob. If SvFAKE(sv), then it is a scalar to which a +C represents a typeglob. If C, then it is a real, +incoercible typeglob. If C, then it is a scalar to which a typeglob has been assigned. Assigning to it again will stop it from being -a typeglob. SVt_PVLV represents a scalar that delegates to another scalar +a typeglob. C represents a scalar that delegates to another scalar behind the scenes. It is used, e.g., for the return value of C and for tied hash and array elements. It can hold any scalar value, including -a typeglob. SVt_REGEXP is for regular -expressions. SVt_INVLIST is for Perl +a typeglob. C is for regular +expressions. C is for Perl core internal use only. -SVt_PVMG represents a "normal" scalar (not a typeglob, regular expression, +C represents a "normal" scalar (not a typeglob, regular expression, or delegate). Since most scalars do not need all the internal fields of a PVMG, we save memory by allocating smaller structs when possible. All the -other types are just simpler forms of SVt_PVMG, with fewer internal fields. - SVt_NULL can only hold undef. SVt_IV can hold undef, an integer, or a -reference. (SVt_RV is an alias for SVt_IV, which exists for backward -compatibility.) SVt_NV can hold any of those or a double. SVt_PV can only -hold undef or a string. SVt_PVIV is a superset of SVt_PV and SVt_IV. -SVt_PVNV is similar. SVt_PVMG can hold anything SVt_PVNV can hold, but it +other types are just simpler forms of C, with fewer internal fields. +C can only hold undef. C can hold undef, an integer, or a +reference. (C is an alias for C, which exists for backward +compatibility.) C can hold any of those or a double. C can only +hold C or a string. C is a superset of C and C. +C is similar. C can hold anything C can hold, but it can, but does not have to, be blessed or magical. =for apidoc AmU||SVt_NULL @@ -274,57 +274,57 @@ Returns the value of the object's reference count. =for apidoc Am|SV*|SvREFCNT_inc|SV* sv Increments the reference count of the given SV, returning the SV. -All of the following SvREFCNT_inc* macros are optimized versions of -SvREFCNT_inc, and can be replaced with SvREFCNT_inc. +All of the following C* macros are optimized versions of +C, and can be replaced with C. =for apidoc Am|SV*|SvREFCNT_inc_NN|SV* sv -Same as SvREFCNT_inc, but can only be used if you know C -is not NULL. Since we don't have to check the NULLness, it's faster +Same as C, but can only be used if you know C +is not C. Since we don't have to check the NULLness, it's faster and smaller. =for apidoc Am|void|SvREFCNT_inc_void|SV* sv -Same as SvREFCNT_inc, but can only be used if you don't need the +Same as C, but can only be used if you don't need the return value. The macro doesn't need to return a meaningful value. =for apidoc Am|void|SvREFCNT_inc_void_NN|SV* sv -Same as SvREFCNT_inc, but can only be used if you don't need the return -value, and you know that C is not NULL. The macro doesn't need +Same as C, but can only be used if you don't need the return +value, and you know that C is not C. The macro doesn't need to return a meaningful value, or check for NULLness, so it's smaller and faster. =for apidoc Am|SV*|SvREFCNT_inc_simple|SV* sv -Same as SvREFCNT_inc, but can only be used with expressions without side +Same as C, but can only be used with expressions without side effects. Since we don't have to store a temporary value, it's faster. =for apidoc Am|SV*|SvREFCNT_inc_simple_NN|SV* sv -Same as SvREFCNT_inc_simple, but can only be used if you know C -is not NULL. Since we don't have to check the NULLness, it's faster +Same as C, but can only be used if you know C +is not C. Since we don't have to check the NULLness, it's faster and smaller. =for apidoc Am|void|SvREFCNT_inc_simple_void|SV* sv -Same as SvREFCNT_inc_simple, but can only be used if you don't need the +Same as C, but can only be used if you don't need the return value. The macro doesn't need to return a meaningful value. =for apidoc Am|void|SvREFCNT_inc_simple_void_NN|SV* sv -Same as SvREFCNT_inc, but can only be used if you don't need the return -value, and you know that C is not NULL. The macro doesn't need +Same as C, but can only be used if you don't need the return +value, and you know that C is not C. The macro doesn't need to return a meaningful value, or check for NULLness, so it's smaller and faster. =for apidoc Am|void|SvREFCNT_dec|SV* sv -Decrements the reference count of the given SV. C may be NULL. +Decrements the reference count of the given SV. C may be C. =for apidoc Am|void|SvREFCNT_dec_NN|SV* sv -Same as SvREFCNT_dec, but can only be used if you know C -is not NULL. Since we don't have to check the NULLness, it's faster +Same as C, but can only be used if you know C +is not C. Since we don't have to check the NULLness, it's faster and smaller. =for apidoc Am|svtype|SvTYPE|SV* sv -Returns the type of the SV. See C. +Returns the type of the SV. See C>. =for apidoc Am|void|SvUPGRADE|SV* sv|svtype type Used to upgrade an SV to a more complex form. Uses C to -perform the upgrade if necessary. See C. +perform the upgrade if necessary. See C>. =cut */ @@ -399,7 +399,9 @@ perform the upgrade if necessary. See C. #define SVf_BREAK 0x04000000 /* refcnt is artificially low - used by SVs in final arena cleanup. Set in S_regtry on PL_reg_curpm, so that - perl_destruct will skip it. */ + perl_destruct will skip it. + Used for mark and sweep by OP_AASSIGN + */ #define SVf_READONLY 0x08000000 /* may not be modified */ @@ -465,7 +467,7 @@ perform the upgrade if necessary. See C. /* PVHV */ #define SVphv_HASKFLAGS 0x80000000 /* keys have flag byte after hash */ /* PVGV when SVpbm_VALID is true */ -#define SVpbm_TAIL 0x80000000 +#define SVpbm_TAIL 0x80000000 /* string has a fake "\n" appended */ /* RV upwards. However, SVf_ROK and SVp_IOK are exclusive */ #define SVprv_WEAKREF 0x80000000 /* Weak reference */ /* pad name vars only */ @@ -689,20 +691,20 @@ Tells an SV that it is an integer. Unsets the IV status of an SV. =for apidoc Am|void|SvIOK_only|SV* sv -Tells an SV that it is an integer and disables all other OK bits. +Tells an SV that it is an integer and disables all other C bits. =for apidoc Am|void|SvIOK_only_UV|SV* sv -Tells an SV that it is an unsigned integer and disables all other OK bits. +Tells an SV that it is an unsigned integer and disables all other C bits. =for apidoc Am|bool|SvIOK_UV|SV* sv Returns a boolean indicating whether the SV contains an integer that must be interpreted as unsigned. A non-negative integer whose value is within the -range of both an IV and a UV may be be flagged as either SvUOK or SVIOK. +range of both an IV and a UV may be be flagged as either C or C. =for apidoc Am|bool|SvUOK|SV* sv Returns a boolean indicating whether the SV contains an integer that must be interpreted as unsigned. A non-negative integer whose value is within the -range of both an IV and a UV may be be flagged as either SvUOK or SVIOK. +range of both an IV and a UV may be be flagged as either C or C. =for apidoc Am|bool|SvIOK_notUV|SV* sv Returns a boolean indicating whether the SV contains a signed integer. @@ -730,7 +732,7 @@ Tells an SV that it is a string. Unsets the PV status of an SV. =for apidoc Am|void|SvPOK_only|SV* sv -Tells an SV that it is a string and disables all other OK bits. +Tells an SV that it is a string and disables all other C bits. Will also turn off the UTF-8 status. =for apidoc Am|bool|SvVOK|SV* sv @@ -739,9 +741,9 @@ Returns a boolean indicating whether the SV contains a v-string. =for apidoc Am|U32|SvOOK|SV* sv Returns a U32 indicating whether the pointer to the string buffer is offset. This hack is used internally to speed up removal of characters from the -beginning of a SvPV. When SvOOK is true, then the start of the -allocated string buffer is actually C bytes before SvPVX. -This offset used to be stored in SvIVX, but is now stored within the spare +beginning of a C. When C is true, then the start of the +allocated string buffer is actually C bytes before C. +This offset used to be stored in C, but is now stored within the spare part of the buffer. =for apidoc Am|U32|SvROK|SV* sv @@ -758,37 +760,37 @@ Dereferences an RV to return the SV. =for apidoc Am|IV|SvIVX|SV* sv 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. +Only use when you are sure C is true. See also C>. =for apidoc Am|UV|SvUVX|SV* sv Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. +Only use when you are sure C is true. See also C>. =for apidoc Am|NV|SvNVX|SV* sv Returns the raw value in the SV's NV slot, without checks or conversions. -Only use when you are sure SvNOK is true. See also C. +Only use when you are sure C is true. See also C>. =for apidoc Am|char*|SvPVX|SV* sv Returns a pointer to the physical string in the SV. The SV must contain a string. Prior to 5.9.3 it is not safe to execute this macro unless the SV's -type >= SVt_PV. +type >= C. This is also used to store the name of an autoloaded subroutine in an XS AUTOLOAD routine. See L. =for apidoc Am|STRLEN|SvCUR|SV* sv -Returns the length of the string which is in the SV. See C. +Returns the length of the string which is in the SV. See C>. =for apidoc Am|STRLEN|SvLEN|SV* sv Returns the size of the string buffer in the SV, not including any part -attributable to C. See C. +attributable to C. See C>. =for apidoc Am|char*|SvEND|SV* sv Returns a pointer to the spot just after the last character in the string which is in the SV, where there is usually a trailing C character (even though Perl scalars do not strictly require it). -See C. Access the character as *(SvEND(sv)). +See C>. Access the character as C<*(SvEND(sv))>. Warning: If C is equal to C, then C points to unallocated memory. @@ -803,40 +805,40 @@ With future Perls, however, it will be more efficient to use C instead of the lvalue assignment to C. =for apidoc Am|void|SvNV_set|SV* sv|NV val -Set the value of the NV pointer in sv to val. See C. +Set the value of the NV pointer in C to val. See C>. =for apidoc Am|void|SvPV_set|SV* sv|char* val This is probably not what you want to use, you probably wanted L or L or L. Set the value of the PV pointer in C to the Perl allocated -C-terminated string C. See also C. +C-terminated string C. See also C>. Remember to free the previous PV buffer. There are many things to check. Beware that the existing pointer may be involved in copy-on-write or other mischief, so do C and use C or -C (or check the SvIsCOW flag) first to make sure this +C (or check the C flag) first to make sure this modification is safe. Then finally, if it is not a COW, call C to free the previous PV buffer. =for apidoc Am|void|SvUV_set|SV* sv|UV val -Set the value of the UV pointer in sv to val. See C. +Set the value of the UV pointer in C to val. See C>. =for apidoc Am|void|SvRV_set|SV* sv|SV* val -Set the value of the RV pointer in sv to val. See C. +Set the value of the RV pointer in C to val. See C>. =for apidoc Am|void|SvMAGIC_set|SV* sv|MAGIC* val -Set the value of the MAGIC pointer in sv to val. See C. +Set the value of the MAGIC pointer in C to val. See C>. =for apidoc Am|void|SvSTASH_set|SV* sv|HV* val -Set the value of the STASH pointer in sv to val. See C. +Set the value of the STASH pointer in C to val. See C>. =for apidoc Am|void|SvCUR_set|SV* sv|STRLEN len -Set the current length of the string which is in the SV. See C -and C. +Set the current length of the string which is in the SV. See C> +and C>. =for apidoc Am|void|SvLEN_set|SV* sv|STRLEN len -Set the actual length of the string which is in the SV. See C. +Set the actual length of the string which is in the SV. See C>. =cut */ @@ -899,7 +901,7 @@ Set the actual length of the string which is in the SV. See C. =for apidoc Am|U32|SvUTF8|SV* sv Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up properly, this indicates whether or not the SV contains UTF-8 encoded data. -You should use this I a call to SvPV() or one of its variants, in +You should use this I a call to C or one of its variants, in case any call to string overloading updates the internal flag. If you want to take into account the L pragma, use C> @@ -914,7 +916,7 @@ Unsets the UTF-8 status of an SV (the data is not changed, just the flag). Do not use frivolously. =for apidoc Am|void|SvPOK_only_UTF8|SV* sv -Tells an SV that it is a string and disables all other OK bits, +Tells an SV that it is a string and disables all other C bits, and leaves the UTF-8 status as it was. =cut @@ -947,7 +949,7 @@ in gv.h: */ #define SvOOK(sv) (SvFLAGS(sv) & SVf_OOK) #define SvOOK_on(sv) (SvFLAGS(sv) |= SVf_OOK) -#define SvOOK_off(sv) ((void)(SvOOK(sv) && sv_backoff(sv))) +#define SvOOK_off(sv) ((void)(SvOOK(sv) && (sv_backoff(sv),0))) #define SvFAKE(sv) (SvFLAGS(sv) & SVf_FAKE) #define SvFAKE_on(sv) (SvFLAGS(sv) |= SVf_FAKE) @@ -1042,14 +1044,14 @@ the scalar's value cannot change unless written to. /* =for apidoc m|U32|SvTHINKFIRST|SV *sv -A quick flag check to see whether an sv should be passed to sv_force_normal -to be "downgraded" before SvIVX or SvPVX can be modified directly. +A quick flag check to see whether an C should be passed to C +to be "downgraded" before C or C can be modified directly. -For example, if your scalar is a reference and you want to modify the SvIVX -slot, you can't just do SvROK_off, as that will leak the referent. +For example, if your scalar is a reference and you want to modify the C +slot, you can't just do C, as that will leak the referent. This is used internally by various sv-modifying functions, such as -sv_setsv, sv_setiv and sv_pvn_force. +C, C and C. One case that this does not handle is a gv without SvFAKE set. After @@ -1057,8 +1059,8 @@ One case that this does not handle is a gv without SvFAKE set. After it will still be a gv. -SvTHINKFIRST sometimes produces false positives. In those cases -sv_force_normal does nothing. +C sometimes produces false positives. In those cases +C does nothing. =cut */ @@ -1497,17 +1499,17 @@ Returns a pointer to the string in the SV, or a stringified form of the SV if the SV does not contain a string. The SV may cache the stringified version becoming C. Handles 'get' magic. The C variable will be set to the length of the string (this is a macro, so -don't use C<&len>). See also C for a version which guarantees to -evaluate sv only once. +don't use C<&len>). See also C> for a version which guarantees to +evaluate C only once. Note that there is no guarantee that the return value of C is equal to C, or that C contains valid data, or that successive calls to C will return the same pointer value each time. This is due to the way that things like overloading and Copy-On-Write are handled. In these cases, the return value may point to -a temporary buffer or similar. If you absolutely need the SvPVX field to +a temporary buffer or similar. If you absolutely need the C field to be valid (for example, if you intend to write to it), then see -L. +C>. =for apidoc Am|char*|SvPVx|SV* sv|STRLEN len A version of C which guarantees to evaluate C only once. @@ -1524,8 +1526,8 @@ Like C but doesn't set a length variable. Like C but doesn't process magic. =for apidoc Am|IV|SvIV|SV* sv -Coerces the given SV to an integer and returns it. See C for a -version which guarantees to evaluate sv only once. +Coerces the given SV to an integer and returns it. See C> for a +version which guarantees to evaluate C only once. =for apidoc Am|IV|SvIV_nomg|SV* sv Like C but doesn't process magic. @@ -1537,8 +1539,8 @@ this if C is an expression with side effects, otherwise use the more efficient C. =for apidoc Am|NV|SvNV|SV* sv -Coerce the given SV to a double and return it. See C for a version -which guarantees to evaluate sv only once. +Coerce the given SV to a double and return it. See C> for a version +which guarantees to evaluate C only once. =for apidoc Am|NV|SvNV_nomg|SV* sv Like C but doesn't process magic. @@ -1550,8 +1552,8 @@ this if C is an expression with side effects, otherwise use the more efficient C. =for apidoc Am|UV|SvUV|SV* sv -Coerces the given SV to an unsigned integer and returns it. See C -for a version which guarantees to evaluate sv only once. +Coerces the given SV to an unsigned integer and returns it. See C> +for a version which guarantees to evaluate C only once. =for apidoc Am|UV|SvUV_nomg|SV* sv Like C but doesn't process magic. @@ -1564,50 +1566,50 @@ otherwise use the more efficient C. =for apidoc Am|bool|SvTRUE|SV* sv Returns a boolean indicating whether Perl would evaluate the SV as true or -false. See SvOK() for a defined/undefined test. Handles 'get' magic -unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the +false. See C> for a defined/undefined test. Handles 'get' magic +unless the scalar is already C, C or C (the public, not the private flags). =for apidoc Am|bool|SvTRUE_nomg|SV* sv Returns a boolean indicating whether Perl would evaluate the SV as true or -false. See SvOK() for a defined/undefined test. Does not handle 'get' magic. +false. See C> for a defined/undefined test. Does not handle 'get' magic. =for apidoc Am|char*|SvPVutf8_force|SV* sv|STRLEN len -Like C, but converts sv to utf8 first if necessary. +Like C, but converts C to UTF-8 first if necessary. =for apidoc Am|char*|SvPVutf8|SV* sv|STRLEN len -Like C, but converts sv to utf8 first if necessary. +Like C, but converts C to UTF-8 first if necessary. =for apidoc Am|char*|SvPVutf8_nolen|SV* sv -Like C, but converts sv to utf8 first if necessary. +Like C, but converts C to UTF-8 first if necessary. =for apidoc Am|char*|SvPVbyte_force|SV* sv|STRLEN len -Like C, but converts sv to byte representation first if necessary. +Like C, but converts C to byte representation first if necessary. =for apidoc Am|char*|SvPVbyte|SV* sv|STRLEN len -Like C, but converts sv to byte representation first if necessary. +Like C, but converts C to byte representation first if necessary. =for apidoc Am|char*|SvPVbyte_nolen|SV* sv -Like C, but converts sv to byte representation first if necessary. +Like C, but converts C to byte representation first if necessary. =for apidoc Am|char*|SvPVutf8x_force|SV* sv|STRLEN len -Like C, but converts sv to utf8 first if necessary. -Guarantees to evaluate sv only once; use the more efficient C +Like C, but converts C to UTF-8 first if necessary. +Guarantees to evaluate C only once; use the more efficient C otherwise. =for apidoc Am|char*|SvPVutf8x|SV* sv|STRLEN len -Like C, but converts sv to utf8 first if necessary. -Guarantees to evaluate sv only once; use the more efficient C +Like C, but converts C to UTF-8 first if necessary. +Guarantees to evaluate C only once; use the more efficient C otherwise. =for apidoc Am|char*|SvPVbytex_force|SV* sv|STRLEN len -Like C, but converts sv to byte representation first if necessary. -Guarantees to evaluate sv only once; use the more efficient C +Like C, but converts C to byte representation first if necessary. +Guarantees to evaluate C only once; use the more efficient C otherwise. =for apidoc Am|char*|SvPVbytex|SV* sv|STRLEN len -Like C, but converts sv to byte representation first if necessary. -Guarantees to evaluate sv only once; use the more efficient C +Like C, but converts C to byte representation first if necessary. +Guarantees to evaluate C only once; use the more efficient C otherwise. =for apidoc Am|U32|SvIsCOW|SV* sv @@ -1633,7 +1635,7 @@ Like C but doesn't process magic. =for apidoc Amdb|STRLEN|sv_utf8_upgrade_nomg|NN SV *sv -Like sv_utf8_upgrade, but doesn't do magic on C. +Like C, but doesn't do magic on C. =cut */ @@ -1968,7 +1970,7 @@ incremented. #define newRV_inc(sv) newRV(sv) -/* the following macros update any magic values this sv is associated with */ +/* the following macros update any magic values this C is associated with */ /* =head1 Magical Functions @@ -1985,12 +1987,12 @@ or a tied variable (it calls C). This macro evaluates its argument more than once. =for apidoc Am|void|SvSetSV|SV* dsv|SV* ssv -Calls C if dsv is not the same as ssv. May evaluate arguments +Calls C if C is not the same as C. May evaluate arguments more than once. Does not handle 'set' magic on the destination SV. =for apidoc Am|void|SvSetSV_nosteal|SV* dsv|SV* ssv -Calls a non-destructive version of C if dsv is not the same as -ssv. May evaluate arguments more than once. +Calls a non-destructive version of C if C is not the same as +C. May evaluate arguments more than once. =for apidoc Am|void|SvSetMagicSV|SV* dsv|SV* ssv Like C, but does any set magic required afterwards. @@ -1999,15 +2001,15 @@ Like C, but does any set magic required afterwards. Like C, but does any set magic required afterwards. =for apidoc Am|void|SvSHARE|SV* sv -Arranges for sv to be shared between threads if a suitable module +Arranges for C to be shared between threads if a suitable module has been loaded. =for apidoc Am|void|SvLOCK|SV* sv -Arranges for a mutual exclusion lock to be obtained on sv if a suitable module +Arranges for a mutual exclusion lock to be obtained on C if a suitable module has been loaded. =for apidoc Am|void|SvUNLOCK|SV* sv -Releases a mutual exclusion lock on sv if a suitable module +Releases a mutual exclusion lock on C if a suitable module has been loaded. =head1 SV Manipulation Functions @@ -2017,7 +2019,7 @@ 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 C character). Calls C to perform the expansion if necessary. Returns a pointer to the character -buffer. SV must be of type >= SVt_PV. One +buffer. SV must be of type >= C. One alternative is to call C if you are not sure of the type of SV. =cut @@ -2077,7 +2079,7 @@ alternative is to call C if you are not sure of the type of SV. Returns a true SV if C is a true value, or a false SV if C is 0. -See also C and C. +See also C> and C>. =cut */ @@ -2135,7 +2137,7 @@ struct clone_params { =for apidoc Am|SV*|newSVpvn_utf8|NULLOK const char* s|STRLEN len|U32 utf8 Creates a new SV and copies a string (which may contain C (C<\0>) -characters) into it. If utf8 is true, calls +characters) into it. If C is true, calls C on the new SV. Implemented as a wrapper around C. =cut @@ -2156,7 +2158,7 @@ Creates a new SV containing the pad name. /* =for apidoc Am|void|SvOOK_offset|NN SV*sv|STRLEN len -Reads into C the offset from SvPVX back to the true start of the +Reads into C the offset from C back to the true start of the allocated buffer, which will be non-zero if C has been used to efficiently remove characters from start of the buffer. Implemented as a macro, which takes the address of C, which must be of type C.