=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 C<SvPV>. When C<SvOOK> is true, then the start of the
+beginning of a C<L</SvPV>>. When C<SvOOK> is true, then the start of the
allocated string buffer is actually C<SvOOK_offset()> bytes before C<SvPVX>.
This offset used to be stored in C<SvIVX>, but is now stored within the spare
part of the buffer.
=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<after> a call to C<SvPV()> or one of its variants, in
+You should use this I<after> a call to C<L</SvPV>> 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<bytes> pragma, use C<L</DO_UTF8>>
STMT_START { assert(SvTYPE(sv) >= SVt_PV); \
SvCUR_set(sv, (val) - SvPVX(sv)); } STMT_END
+/*
+=for apidoc Am|void|SvPV_renew|SV* sv|STRLEN len
+Low level micro optimization of C<L</SvGROW>>. It is generally better to use
+C<SvGROW> instead. This is because C<SvPV_renew> ignores potential issues that
+C<SvGROW> handles. C<sv> needs to have a real C<PV> that is unencombered by
+things like COW. Using C<SV_CHECK_THINKFIRST> or
+C<SV_CHECK_THINKFIRST_COW_DROP> before calling this should clean it up, but
+why not just use C<SvGROW> if you're not sure about the provenance?
+
+=cut
+*/
#define SvPV_renew(sv,n) \
STMT_START { SvLEN_set(sv, n); \
SvPV_set((sv), (MEM_WRAP_CHECK_(n,char) \
=for apidoc_item ||SvPVutf8_force
=for apidoc_item ||SvPVutf8x_force
-These are like C<L</SvPV>> but will force the SV into containing a string
-(C<L</SvPOK>>), and only a string (C<L</SvPOK_only>>), by hook or by crook.
-You need to use one of these C<force> routines if you are going to update the
-C<L</SvPVX>> directly.
+These are like C<L</SvPV>>, returning the string in the SV, but will force the
+SV into containing a string (C<L</SvPOK>>), and only a string
+(C<L</SvPOK_only>>), by hook or by crook. You need to use one of these
+C<force> routines if you are going to update the C<L</SvPVX>> directly.
Note that coercing an arbitrary scalar into a plain PV will potentially
strip useful data from it. For example if the SV was C<SvROK>, then the
'get' magic (by clearing it). The other forms do perform 'get' magic, except
for the ones with C<nomg> in their names, which skip 'get' magic.
-The forms with C<nolen> in their names do not return the length of the string.
-They should be used only when it is known that the PV is a C string, terminated by
-a NUL byte, and without intermediate NUL characters; or when you don't care
-about its length.
+The forms that take a C<len> parameter will set that variable to the byte
+length of the resultant string (these are macros, so don't use C<&len>).
+
+The forms with C<nolen> in their names indicate they don't have a C<len>
+parameter. They should be used only when it is known that the PV is a C
+string, terminated by a NUL byte, and without intermediate NUL characters; or
+when you don't care about its length.
The forms with C<mutable> in their names are effectively the same as those without,
but the name emphasizes that the string is modifiable by the caller, which it is
#endif
/*
-=for apidoc Am|SV*|newRV_inc|SV* sv
+=for apidoc newRV
+=for apidoc_item ||newRV_inc|
-Creates an RV wrapper for an SV. The reference count for the original SV is
-incremented.
+These are identical. They create an RV wrapper for an SV. The reference count
+for the original SV is incremented.
=cut
*/
https://perl5.git.perl.org / perl5.git / blobdiff