From: Jarkko Hietaniemi Date: Sat, 15 Jul 2000 00:31:05 +0000 (+0000) Subject: More docs for sv functions. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=c461cf8fdae82a63e76dea27773096e29e6505b0;p=p5sagit%2Fp5-mst-13.2.git 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: Subject: Re: [PATCH cfgperl] sv.c apidoc From: "M.J.T. Guy" Date: Thu, 13 Jul 2000 12:27:41 +0100 Message-Id: Subject: Re: [PATCH cfgperl] sv.c apidoc From: "M.J.T. Guy" Date: Thu, 13 Jul 2000 13:23:09 +0100 Message-Id: Subject: Re: [PATCH cfgperl] sv.c apidoc From: simon@brecon.co.uk (Simon Cozens) Date: 14 Jul 2000 06:51:02 GMT Message-ID: p4raw-id: //depot/perl@6412 --- diff --git a/embed.pl b/embed.pl index 0b4c545..27d6bce 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 effbda4..6bf970a 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. +=item svtype - svtype SvTYPE(SV* sv) +An enum of flags for Perl types. These are found in the file B +in the C enum. Test these flags with the C 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 -in the C enum. Test these flags with the C macro. +Returns the type of the SV. See C. + + 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. =for hackers Found in file sv.c +=item sv_cmp_locale + +Compares the strings in two SVs in a locale-aware manner. See +L + + 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 and will @@ -2580,6 +2619,16 @@ Returns the length of the string in the SV. See also C. =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. + + 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, 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, 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 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 +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 and appends the formatted output diff --git a/sv.c b/sv.c index 5f5d281..60db718 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 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 +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 + +=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. + +=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) {