This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fixup Perl_magic_freemglob()
[perl5.git] / sv.h
diff --git a/sv.h b/sv.h
index 58e86ae..ba701ed 100644 (file)
--- a/sv.h
+++ b/sv.h
@@ -747,7 +747,7 @@ 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 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.
@@ -922,7 +922,7 @@ Set the size of the string buffer for the SV. See C<L</SvLEN>>.
 =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>>
@@ -1383,6 +1383,17 @@ object type. Exposed to perl code via Internals::SvREADONLY().
        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)                 \
@@ -1555,10 +1566,10 @@ attention to precisely which outputs are influenced by which inputs.
 =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
@@ -1573,10 +1584,13 @@ to specify to perform 'get' magic (by setting the C<SV_GMAGIC> flag) or to skip
 '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
@@ -2156,10 +2170,11 @@ Returns the hash for C<sv> created by C<L</newSVpvn_share>>.
 #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
 */