More docs for sv functions.

Subject: [PATCH cfgperl] sv.c apidoc
From: simon@brecon.co.uk (Simon Cozens)
Date: 13 Jul 2000 09:00:20 GMT
Message-ID: <slrn8mr194.2em.simon@justanother.perlhacker.org>

Subject: Re: [PATCH cfgperl] sv.c apidoc
From: "M.J.T. Guy" <mjtg@cus.cam.ac.uk>
Date: Thu, 13 Jul 2000 12:27:41 +0100
Message-Id: <E13Ch9Z-0006QL-00@libra.cus.cam.ac.uk>

Subject: Re: [PATCH cfgperl] sv.c apidoc
From: "M.J.T. Guy" <mjtg@cus.cam.ac.uk>
Date: Thu, 13 Jul 2000 13:23:09 +0100
Message-Id: <E13Ci1F-0007WR-00@libra.cus.cam.ac.uk>

Subject: Re: [PATCH cfgperl] sv.c apidoc
From: simon@brecon.co.uk (Simon Cozens)
Date: 14 Jul 2000 06:51:02 GMT
Message-ID: <slrn8mte2m.1qo.simon@justanother.perlhacker.org>

p4raw-id: //depot/perl@6412

3 files changed, 306 insertions, 25 deletions

diff --git a/embed.pl b/embed.pl
index 0b4c5450ae..27d6bcedb9 100755
--- a/embed.pl
+++ b/embed.pl
@@ -1130,6 +1130,8 @@ sub docout ($$$) { # output the docs for one function
     my($fh, $name, $docref) = @_;
     my($flags, $docs, $ret, $file, @args) = @$docref;
 
+    $docs .= "NOTE: this function is experimental and may change or be
+removed without notice.\n\n" if $flags =~ /x/;
     $docs .= "NOTE: the perl_ form of this function is deprecated.\n\n" 
 	if $flags =~ /p/;
 
@@ -1169,6 +1171,7 @@ walk_table {	# load documented functions into approriate hash
 	if ($flags =~ /A/) {
 	    my $docref = delete $docfuncs{$func};
 	    warn "no docs for $func\n" unless $docref and @$docref;
+        $docref->[0].="x" if $flags =~ /M/;
 	    $apidocs{$func} = [$docref->[0] . 'A', $docref->[1], $retval,
 			       $docref->[3], @args];
 	} else {
@@ -1302,6 +1305,7 @@ __END__
 :       o		has no compatibility macro (#define foo Perl_foo)
 :       j		not a member of CPerlObj
 :       x		not exported
+:       M		may change
 :
 : Individual flags may be separated by whitespace.
 :
@@ -1966,7 +1970,7 @@ Ap	|NV	|sv_nv		|SV* sv
 Ap	|char*	|sv_pvn		|SV *sv|STRLEN *len
 Ap	|char*	|sv_pvutf8n	|SV *sv|STRLEN *len
 Ap	|char*	|sv_pvbyten	|SV *sv|STRLEN *len
-Ap	|I32	|sv_true	|SV *sv
+Apd	|I32	|sv_true	|SV *sv
 p	|void	|sv_add_arena	|char* ptr|U32 size|U32 flags
 Ap	|int	|sv_backoff	|SV* sv
 Apd	|SV*	|sv_bless	|SV* sv|HV* stash
@@ -1978,9 +1982,9 @@ Apd	|void	|sv_catsv	|SV* dsv|SV* ssv
 Apd	|void	|sv_chop	|SV* sv|char* ptr
 p	|void	|sv_clean_all
 p	|void	|sv_clean_objs
-Ap	|void	|sv_clear	|SV* sv
+Apd	|void	|sv_clear	|SV* sv
 Apd	|I32	|sv_cmp		|SV* sv1|SV* sv2
-Ap	|I32	|sv_cmp_locale	|SV* sv1|SV* sv2
+Apd	|I32	|sv_cmp_locale	|SV* sv1|SV* sv2
 #if defined(USE_LOCALE_COLLATE)
 Ap	|char*	|sv_collxfrm	|SV* sv|STRLEN* nxp
 #endif
@@ -1989,9 +1993,9 @@ Apd	|void	|sv_dec		|SV* sv
 Ap	|void	|sv_dump	|SV* sv
 Apd	|bool	|sv_derived_from|SV* sv|const char* name
 Apd	|I32	|sv_eq		|SV* sv1|SV* sv2
-Ap	|void	|sv_free	|SV* sv
+Apd	|void	|sv_free	|SV* sv
 p	|void	|sv_free_arenas
-Ap	|char*	|sv_gets	|SV* sv|PerlIO* fp|I32 append
+Apd	|char*	|sv_gets	|SV* sv|PerlIO* fp|I32 append
 Apd	|char*	|sv_grow	|SV* sv|STRLEN newlen
 Apd	|void	|sv_inc		|SV* sv
 Apd	|void	|sv_insert	|SV* bigsv|STRLEN offset|STRLEN len \
@@ -1999,7 +2003,7 @@ Apd	|void	|sv_insert	|SV* bigsv|STRLEN offset|STRLEN len \
 Apd	|int	|sv_isa		|SV* sv|const char* name
 Apd	|int	|sv_isobject	|SV* sv
 Apd	|STRLEN	|sv_len		|SV* sv
-Ap	|STRLEN	|sv_len_utf8	|SV* sv
+Apd	|STRLEN	|sv_len_utf8	|SV* sv
 Apd	|void	|sv_magic	|SV* sv|SV* obj|int how|const char* name \
 				|I32 namlen
 Apd	|SV*	|sv_mortalcopy	|SV* oldsv
@@ -2008,11 +2012,11 @@ Ap	|SV*	|sv_newref	|SV* sv
 Ap	|char*	|sv_peek	|SV* sv
 Ap	|void	|sv_pos_u2b	|SV* sv|I32* offsetp|I32* lenp
 Ap	|void	|sv_pos_b2u	|SV* sv|I32* offsetp
-Ap	|char*	|sv_pvn_force	|SV* sv|STRLEN* lp
-Ap	|char*	|sv_pvutf8n_force|SV* sv|STRLEN* lp
+Apd	|char*	|sv_pvn_force	|SV* sv|STRLEN* lp
+Apd	|char*	|sv_pvutf8n_force|SV* sv|STRLEN* lp
 Ap	|char*	|sv_pvbyten_force|SV* sv|STRLEN* lp
-Ap	|char*	|sv_reftype	|SV* sv|int ob
-Ap	|void	|sv_replace	|SV* sv|SV* nsv
+Apd	|char*	|sv_reftype	|SV* sv|int ob
+Apd	|void	|sv_replace	|SV* sv|SV* nsv
 Ap	|void	|sv_report_used
 Ap	|void	|sv_reset	|char* s|HV* stash
 Afpd	|void	|sv_setpvf	|SV* sv|const char* pat|...
@@ -2031,7 +2035,7 @@ Apd	|void	|sv_setpvn	|SV* sv|const char* ptr|STRLEN len
 Apd	|void	|sv_setsv	|SV* dsv|SV* ssv
 Ap	|void	|sv_taint	|SV* sv
 Ap	|bool	|sv_tainted	|SV* sv
-Ap	|int	|sv_unmagic	|SV* sv|int type
+Apd	|int	|sv_unmagic	|SV* sv|int type
 Apd	|void	|sv_unref	|SV* sv
 Ap	|void	|sv_untaint	|SV* sv
 Apd	|bool	|sv_upgrade	|SV* sv|U32 mt
@@ -2064,8 +2068,8 @@ Ap	|U8*	|utf16_to_utf8	|U16* p|U8 *d|I32 bytelen
 Ap	|U8*	|utf16_to_utf8_reversed|U16* p|U8 *d|I32 bytelen
 Ap	|I32	|utf8_distance	|U8 *a|U8 *b
 Ap	|U8*	|utf8_hop	|U8 *s|I32 off
-Ap	|U8*	|utf8_to_bytes	|U8 *s|STRLEN len
-Ap	|U8*	|bytes_to_utf8	|U8 *s|STRLEN *len
+ApM	|U8*	|utf8_to_bytes	|U8 *s|STRLEN len
+ApM	|U8*	|bytes_to_utf8	|U8 *s|STRLEN *len
 Ap	|UV	|utf8_to_uv	|U8 *s|I32* retlen
 Ap	|U8*	|uv_to_utf8	|U8 *d|UV uv
 p	|void	|vivify_defelem	|SV* sv
@@ -2153,13 +2157,13 @@ Ap	|char*	|sv_2pvbyte_nolen|SV* sv
 Ap	|char*	|sv_pv		|SV *sv
 Ap	|char*	|sv_pvutf8	|SV *sv
 Ap	|char*	|sv_pvbyte	|SV *sv
-Ap      |void   |sv_utf8_upgrade|SV *sv
-Ap      |bool   |sv_utf8_downgrade|SV *sv|bool fail_ok
-Ap      |void   |sv_utf8_encode |SV *sv
+Apd      |void   |sv_utf8_upgrade|SV *sv
+ApdM      |bool   |sv_utf8_downgrade|SV *sv|bool fail_ok
+ApdM      |void   |sv_utf8_encode |SV *sv
 Ap      |bool   |sv_utf8_decode |SV *sv
 Ap	|void	|sv_force_normal|SV *sv
 Ap	|void	|tmps_grow	|I32 n
-Ap	|SV*	|sv_rvweaken	|SV *sv
+Apd	|SV*	|sv_rvweaken	|SV *sv
 p	|int	|magic_killbackrefs|SV *sv|MAGIC *mg
 Ap	|OP*	|newANONATTRSUB	|I32 floor|OP *proto|OP *attrs|OP *block
 Ap	|CV*	|newATTRSUB	|I32 floor|OP *o|OP *proto|OP *attrs|OP *block
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index effbda443e..6bf970a901 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -2272,19 +2272,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
@@ -2478,6 +2478,16 @@ string.
 =for hackers
 Found in file sv.c
 
+=item sv_clear
+
+Clear an SV, making it empty. Does not free the memory used by the SV
+itself.
+
+	void	sv_clear(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_cmp
 
 Compares the strings in two SVs.  Returns -1, 0, or 1 indicating whether the
@@ -2489,6 +2499,16 @@ C<sv2>.
 =for hackers
 Found in file sv.c
 
+=item sv_cmp_locale
+
+Compares the strings in two SVs in a locale-aware manner. See
+L</sv_cmp_locale>
+
+	I32	sv_cmp_locale(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
 =item sv_dec
 
 Auto-decrement of the value in the SV.
@@ -2519,6 +2539,25 @@ identical.
 =for hackers
 Found in file sv.c
 
+=item sv_free
+
+Free the memory used by an SV.
+
+	void	sv_free(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_gets
+
+Get a line from the filehandle and store it into the SV, optionally
+appending to the currently-stored string.
+
+	char*	sv_gets(SV* sv, PerlIO* fp, I32 append)
+
+=for hackers
+Found in file sv.c
+
 =item sv_grow
 
 Expands the character buffer in the SV.  This will use C<sv_unref> and will
@@ -2580,6 +2619,16 @@ Returns the length of the string in the SV.  See also C<SvCUR>.
 =for hackers
 Found in file sv.c
 
+=item sv_len_utf8
+
+Returns the number of characters in the string in an SV, counting wide
+UTF8 bytes as a single character.
+
+	STRLEN	sv_len_utf8(SV* sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_magic
 
 Adds magic to an SV.
@@ -2608,6 +2657,52 @@ Creates a new SV which is mortal.  The reference count of the SV is set to 1.
 =for hackers
 Found in file sv.c
 
+=item sv_pvn_force
+
+Get a sensible string out of the SV somehow.
+
+	char*	sv_pvn_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvutf8n_force
+
+Get a sensible UTF8-encoded string out of the SV somehow. See
+L</sv_pvn_force>.
+
+	char*	sv_pvutf8n_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_reftype
+
+Returns a string describing what the SV is a reference to.
+
+	char*	sv_reftype(SV* sv, int ob)
+
+=for hackers
+Found in file sv.c
+
+=item sv_replace
+
+Make the first argument a copy of the second, then delete the original.
+
+	void	sv_replace(SV* sv, SV* nsv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_rvweaken
+
+Weaken a reference.
+
+	SV*	sv_rvweaken(SV *sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_setiv
 
 Copies an integer into the given SV.  Does not handle 'set' magic.  See
@@ -2823,6 +2918,24 @@ Like C<sv_setuv>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_true
+
+Returns true if the SV has a true value by Perl's rules.
+
+	I32	sv_true(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_unmagic
+
+Removes magic from an SV.
+
+	int	sv_unmagic(SV* sv, int type)
+
+=for hackers
+Found in file sv.c
+
 =item sv_unref
 
 Unsets the RV status of the SV, and decrements the reference count of
@@ -2868,6 +2981,43 @@ Like C<sv_usepvn>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
+=item sv_utf8_downgrade
+
+Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
+This may not be possible if the PV contains non-byte encoding characters;
+if this is the case, either returns false or, if C<fail_ok> is not
+true, croaks.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+	bool	sv_utf8_downgrade(SV *sv, bool fail_ok)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_encode
+
+Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
+flag so that it looks like bytes again. Nothing calls this. 
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+	void	sv_utf8_encode(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_upgrade
+
+Convert the PV of an SV to its UTF8-encoded form.
+
+	void	sv_utf8_upgrade(SV *sv)
+
+=for hackers
+Found in file sv.c
+
 =item sv_vcatpvfn
 
 Processes its arguments like C<vsprintf> and appends the formatted output
diff --git a/sv.c b/sv.c
index 5f5d2819e4..60db71848f 100644
--- a/sv.c
+++ b/sv.c
@@ -2390,6 +2390,14 @@ Perl_sv_2bool(pTHX_ register SV *sv)
     }
 }
 
+/*
+=for apidoc sv_utf8_upgrade
+
+Convert the PV of an SV to its UTF8-encoded form.
+
+=cut
+*/
+
 void
 Perl_sv_utf8_upgrade(pTHX_ register SV *sv)
 {
@@ -2431,6 +2439,17 @@ Perl_sv_utf8_upgrade(pTHX_ register SV *sv)
     }
 }
 
+/*
+=for apidoc sv_utf8_downgrade
+
+Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
+This may not be possible if the PV contains non-byte encoding characters;
+if this is the case, either returns false or, if C<fail_ok> is not
+true, croaks.
+
+=cut
+*/
+
 bool
 Perl_sv_utf8_downgrade(pTHX_ register SV* sv, bool fail_ok)
 {
@@ -2480,6 +2499,15 @@ Perl_sv_utf8_downgrade(pTHX_ register SV* sv, bool fail_ok)
     return TRUE;
 }
 
+/*
+=for apidoc sv_utf8_encode
+
+Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
+flag so that it looks like bytes again. Nothing calls this. 
+
+=cut
+*/
+
 void
 Perl_sv_utf8_encode(pTHX_ register SV *sv)
 {
@@ -3451,6 +3479,14 @@ Perl_sv_magic(pTHX_ register SV *sv, SV *obj, int how, const char *name, I32 nam
 	SvFLAGS(sv) &= ~(SVf_IOK|SVf_NOK|SVf_POK);
 }
 
+/*
+=for apidoc sv_unmagic
+
+Removes magic from an SV.
+
+=cut
+*/
+
 int
 Perl_sv_unmagic(pTHX_ SV *sv, int type)
 {
@@ -3485,6 +3521,14 @@ Perl_sv_unmagic(pTHX_ SV *sv, int type)
     return 0;
 }
 
+/*
+=for apidoc sv_rvweaken
+
+Weaken a reference.
+
+=cut
+*/
+
 SV *
 Perl_sv_rvweaken(pTHX_ SV *sv)
 {
@@ -3636,7 +3680,13 @@ Perl_sv_insert(pTHX_ SV *bigstr, STRLEN offset, STRLEN len, char *little, STRLEN
     SvSETMAGIC(bigstr);
 }
 
-/* make sv point to what nstr did */
+/*
+=for apidoc sv_replace
+
+Make the first argument a copy of the second, then delete the original.
+
+=cut
+*/
 
 void
 Perl_sv_replace(pTHX_ register SV *sv, register SV *nsv)
@@ -3665,6 +3715,15 @@ Perl_sv_replace(pTHX_ register SV *sv, register SV *nsv)
     del_SV(nsv);
 }
 
+/*
+=for apidoc sv_clear
+
+Clear an SV, making it empty. Does not free the memory used by the SV
+itself.
+
+=cut
+*/
+
 void
 Perl_sv_clear(pTHX_ register SV *sv)
 {
@@ -3858,6 +3917,14 @@ Perl_sv_newref(pTHX_ SV *sv)
     return sv;
 }
 
+/*
+=for apidoc sv_free
+
+Free the memory used by an SV.
+
+=cut
+*/
+
 void
 Perl_sv_free(pTHX_ SV *sv)
 {
@@ -3926,6 +3993,15 @@ Perl_sv_len(pTHX_ register SV *sv)
     return len;
 }
 
+/*
+=for apidoc sv_len_utf8
+
+Returns the number of characters in the string in an SV, counting wide
+UTF8 bytes as a single character.
+
+=cut
+*/
+
 STRLEN
 Perl_sv_len_utf8(pTHX_ register SV *sv)
 {
@@ -4121,6 +4197,15 @@ Perl_sv_cmp(pTHX_ register SV *str1, register SV *str2)
 	return cur1 < cur2 ? -1 : 1;
 }
 
+/*
+=for apidoc sv_cmp_locale
+
+Compares the strings in two SVs in a locale-aware manner. See
+L</sv_cmp_locale>
+
+=cut
+*/
+
 I32
 Perl_sv_cmp_locale(pTHX_ register SV *sv1, register SV *sv2)
 {
@@ -4222,6 +4307,15 @@ Perl_sv_collxfrm(pTHX_ SV *sv, STRLEN *nxp)
 
 #endif /* USE_LOCALE_COLLATE */
 
+/*
+=for apidoc sv_gets
+
+Get a line from the filehandle and store it into the SV, optionally
+appending to the currently-stored string.
+
+=cut
+*/
+
 char *
 Perl_sv_gets(pTHX_ register SV *sv, register PerlIO *fp, I32 append)
 {
@@ -5128,6 +5222,14 @@ Perl_sv_2cv(pTHX_ SV *sv, HV **st, GV **gvp, I32 lref)
     }
 }
 
+/*
+=for apidoc sv_true
+
+Returns true if the SV has a true value by Perl's rules.
+
+=cut
+*/
+
 I32
 Perl_sv_true(pTHX_ register SV *sv)
 {
@@ -5206,6 +5308,14 @@ Perl_sv_pvn(pTHX_ SV *sv, STRLEN *lp)
     return sv_2pv(sv, lp);
 }
 
+/*
+=for apidoc sv_pvn_force
+
+Get a sensible string out of the SV somehow.
+
+=cut
+*/
+
 char *
 Perl_sv_pvn_force(pTHX_ SV *sv, STRLEN *lp)
 {
@@ -5278,6 +5388,15 @@ Perl_sv_pvutf8n(pTHX_ SV *sv, STRLEN *lp)
     return sv_pvn(sv,lp);
 }
 
+/*
+=for apidoc sv_pvutf8n_force
+
+Get a sensible UTF8-encoded string out of the SV somehow. See
+L</sv_pvn_force>.
+
+=cut
+*/
+
 char *
 Perl_sv_pvutf8n_force(pTHX_ SV *sv, STRLEN *lp)
 {
@@ -5285,6 +5404,14 @@ Perl_sv_pvutf8n_force(pTHX_ SV *sv, STRLEN *lp)
     return sv_pvn_force(sv,lp);
 }
 
+/*
+=for apidoc sv_reftype
+
+Returns a string describing what the SV is a reference to.
+
+=cut
+*/
+
 char *
 Perl_sv_reftype(pTHX_ SV *sv, int ob)
 {