Re: [PATCH 5.7.1] sv.c documentation

Message-Id: <200106182029.VAA06503@gizmo.fdgroup.co.uk>

p4raw-id: //depot/perl@10691

1 files changed, 105 insertions, 23 deletions

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 87468f279a..91d6b315fe 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -1323,6 +1323,17 @@ SV is B<not> incremented.
 =for hackers
 Found in file sv.c
 
+=item newSV
+
+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<NEWSV>
+macro.
+
+	SV*	newSV(STRLEN len)
+
+=for hackers
+Found in file sv.c
+
 =item NEWSV
 
 Creates a new SV.  A non-zero C<len> parameter indicates the number of
@@ -2087,22 +2098,22 @@ version which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
-=item SvIVX
+=item SvIVx
 
-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<SvIV()>.
+Coerces the given SV to an integer and returns it. Guarantees to evaluate
+sv only once. Use the more efficent C<SvIV> otherwise.
 
-	IV	SvIVX(SV* sv)
+	IV	SvIVx(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvIVx
+=item SvIVX
 
-Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficent C<SvIV> otherwise.
+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<SvIV()>.
 
-	IV	SvIVx(SV* sv)
+	IV	SvIVX(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2632,19 +2643,19 @@ false, defined or undefined.  Does not handle 'get' magic.
 =for hackers
 Found in file sv.h
 
-=item SvTYPE
-
-Returns the type of the SV.  See C<svtype>.
+=item svtype
 
-	svtype	SvTYPE(SV* sv)
+An enum of flags for Perl types.  These are found in the file B<sv.h> 
+in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
 
 =for hackers
 Found in file sv.h
 
-=item svtype
+=item SvTYPE
 
-An enum of flags for Perl types.  These are found in the file B<sv.h> 
-in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
+Returns the type of the SV.  See C<svtype>.
+
+	svtype	SvTYPE(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2755,22 +2766,22 @@ for a version which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
-=item SvUVX
+=item SvUVx
 
-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<SvUV()>.
+Coerces the given SV to an unsigned integer and returns it. Guarantees to
+evaluate sv only once. Use the more efficent C<SvUV> otherwise.
 
-	UV	SvUVX(SV* sv)
+	UV	SvUVx(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvUVx
+=item SvUVX
 
-Coerces the given SV to an unsigned integer and returns it. Guarantees to
-evaluate sv only once. Use the more efficent C<SvUV> otherwise.
+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<SvUV()>.
 
-	UV	SvUVx(SV* sv)
+	UV	SvUVX(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2837,6 +2848,19 @@ macros.
 =for hackers
 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
+side-effect.
+
+Usually accessed via the C<SvPVbyte> macro.
+
+	char*	sv_2pvbyte(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
 =item sv_2pvbyte_nolen
 
 Return a pointer to the byte-encoded representation of the SV.
@@ -2849,6 +2873,18 @@ Usually accessed via the C<SvPVbyte_nolen> macro.
 =for hackers
 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.
+
+Usually accessed via the C<SvPVutf8> macro.
+
+	char*	sv_2pvutf8(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
 =item sv_2pvutf8_nolen
 
 Return a pointer to the UTF8-encoded representation of the SV.
@@ -3337,6 +3373,16 @@ type coercion.
 =for hackers
 Found in file sv.c
 
+=item sv_pv
+
+A private implementation of the C<SvPV_nolen> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+	char*	sv_pv(SV *sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_pvbyte
 
 A private implementation of the C<SvPVbyte_nolen> macro for compilers
@@ -3370,6 +3416,16 @@ instead.
 =for hackers
 Found in file sv.c
 
+=item sv_pvn
+
+A private implementation of the C<SvPV> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+	char*	sv_pvn(SV *sv, STRLEN *len)
+
+=for hackers
+Found in file sv.c
+
 =item sv_pvn_force
 
 Get a sensible string out of the SV somehow.
@@ -3469,6 +3525,16 @@ Dump the contents of all SVs not yet freed. (Debugging aid).
 =for hackers
 Found in file sv.c
 
+=item sv_reset
+
+Underlying implementation for the C<reset> Perl function.
+Note that the perl-level function is vaguely deprecated.
+
+	void	sv_reset(char* s, HV* stash)
+
+=for hackers
+Found in file sv.c
+
 =item sv_rvweaken
 
 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
@@ -3746,6 +3812,14 @@ Taint an SV. Use C<SvTAINTED_on> instead.
 =for hackers
 Found in file sv.c
 
+=item sv_tainted
+
+Test an SV for taintedness. Use C<SvTAINTED> instead.
+	bool	sv_tainted(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_true
 
 Returns true if the SV has a true value by Perl's rules.
@@ -3793,6 +3867,14 @@ See C<SvROK_off>.
 =for hackers
 Found in file sv.c
 
+=item sv_untaint
+
+Untaint an SV. Use C<SvTAINTED_off> instead.
+	void	sv_untaint(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_upgrade
 
 Upgrade an SV to a more complex form.  Gnenerally adds a new body type to the