Re: [PATCH 5.7.1] sv.c documentation
Dave Mitchell [Mon, 18 Jun 2001 21:29:45 +0000 (22:29 +0100)]
Message-Id: <200106182029.VAA06503@gizmo.fdgroup.co.uk>

p4raw-id: //depot/perl@10691

embed.pl
pod/perlapi.pod

index c685d3b..5f44ceb 100755 (executable)
--- a/embed.pl
+++ b/embed.pl
@@ -1826,7 +1826,7 @@ Ap        |OP*    |newPMOP        |I32 type|I32 flags
 Ap     |OP*    |newPVOP        |I32 type|I32 flags|char* pv
 Ap     |SV*    |newRV          |SV* pref
 Apd    |SV*    |newRV_noinc    |SV *sv
-Ap     |SV*    |newSV          |STRLEN len
+Apd    |SV*    |newSV          |STRLEN len
 Ap     |OP*    |newSVREF       |OP* o
 Ap     |OP*    |newSVOP        |I32 type|I32 flags|SV* sv
 Apd    |SV*    |newSViv        |IV i
@@ -2003,13 +2003,13 @@ Apd     |IV     |sv_2iv         |SV* sv
 Apd    |SV*    |sv_2mortal     |SV* sv
 Apd    |NV     |sv_2nv         |SV* sv
 Aop    |char*  |sv_2pv         |SV* sv|STRLEN* lp
-Ap     |char*  |sv_2pvutf8     |SV* sv|STRLEN* lp
-Ap     |char*  |sv_2pvbyte     |SV* sv|STRLEN* lp
+Apd    |char*  |sv_2pvutf8     |SV* sv|STRLEN* lp
+Apd    |char*  |sv_2pvbyte     |SV* sv|STRLEN* lp
 Apd    |UV     |sv_2uv         |SV* sv
 Apd    |IV     |sv_iv          |SV* sv
 Apd    |UV     |sv_uv          |SV* sv
 Apd    |NV     |sv_nv          |SV* sv
-Ap     |char*  |sv_pvn         |SV *sv|STRLEN *len
+Apd    |char*  |sv_pvn         |SV *sv|STRLEN *len
 Apd    |char*  |sv_pvutf8n     |SV *sv|STRLEN *len
 Apd    |char*  |sv_pvbyten     |SV *sv|STRLEN *len
 Apd    |I32    |sv_true        |SV *sv
@@ -2062,7 +2062,7 @@ Apd       |int    |sv_realpath    |SV* sv|char *path|STRLEN len
 Apd    |char*  |sv_reftype     |SV* sv|int ob
 Apd    |void   |sv_replace     |SV* sv|SV* nsv
 Apd    |void   |sv_report_used
-Ap     |void   |sv_reset       |char* s|HV* stash
+Apd    |void   |sv_reset       |char* s|HV* stash
 Afpd   |void   |sv_setpvf      |SV* sv|const char* pat|...
 Ap     |void   |sv_vsetpvf     |SV* sv|const char* pat|va_list* args
 Apd    |void   |sv_setiv       |SV* sv|IV num
@@ -2079,11 +2079,11 @@ Apd     |void   |sv_setpv       |SV* sv|const char* ptr
 Apd    |void   |sv_setpvn      |SV* sv|const char* ptr|STRLEN len
 Aopd   |void   |sv_setsv       |SV* dsv|SV* ssv
 Apd    |void   |sv_taint       |SV* sv
-Ap     |bool   |sv_tainted     |SV* sv
+Apd    |bool   |sv_tainted     |SV* sv
 Apd    |int    |sv_unmagic     |SV* sv|int type
 Apd    |void   |sv_unref       |SV* sv
 Apd    |void   |sv_unref_flags |SV* sv|U32 flags
-Ap     |void   |sv_untaint     |SV* sv
+Apd    |void   |sv_untaint     |SV* sv
 Apd    |bool   |sv_upgrade     |SV* sv|U32 mt
 Apd    |void   |sv_usepvn      |SV* sv|char* ptr|STRLEN len
 Apd    |void   |sv_vcatpvfn    |SV* sv|const char* pat|STRLEN patlen \
@@ -2205,7 +2205,7 @@ Ap        |void   |reginitcolors
 Apd    |char*  |sv_2pv_nolen   |SV* sv
 Apd    |char*  |sv_2pvutf8_nolen|SV* sv
 Apd    |char*  |sv_2pvbyte_nolen|SV* sv
-Ap     |char*  |sv_pv          |SV *sv
+Apd    |char*  |sv_pv          |SV *sv
 Apd    |char*  |sv_pvutf8      |SV *sv
 Apd    |char*  |sv_pvbyte      |SV *sv
 Aopd   |STRLEN |sv_utf8_upgrade|SV *sv
index 87468f2..91d6b31 100644 (file)
@@ -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