From: Dave Mitchell Date: Mon, 18 Jun 2001 21:29:45 +0000 (+0100) Subject: Re: [PATCH 5.7.1] sv.c documentation X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=451be7b116e8b0e099d3a444fe04e0d21895efcb;p=p5sagit%2Fp5-mst-13.2.git Re: [PATCH 5.7.1] sv.c documentation Message-Id: <200106182029.VAA06503@gizmo.fdgroup.co.uk> p4raw-id: //depot/perl@10691 --- diff --git a/embed.pl b/embed.pl index c685d3b..5f44ceb 100755 --- 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 diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 87468f2..91d6b31 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -1323,6 +1323,17 @@ SV is B 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 +macro. + + SV* newSV(STRLEN len) + +=for hackers +Found in file sv.c + =item NEWSV Creates a new SV. A non-zero C 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. +Coerces the given SV to an integer and returns it. Guarantees to evaluate +sv only once. Use the more efficent C 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 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. - 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. +=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 @@ -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. +Coerces the given SV to an unsigned integer and returns it. Guarantees to +evaluate sv only once. Use the more efficent C 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 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. - 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 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 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 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 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 macro for compilers @@ -3370,6 +3416,16 @@ instead. =for hackers Found in file sv.c +=item sv_pvn + +A private implementation of the C 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 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 flag on this RV; give the @@ -3746,6 +3812,14 @@ Taint an SV. Use C instead. =for hackers Found in file sv.c +=item sv_tainted + +Test an SV for taintedness. Use C 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. =for hackers Found in file sv.c +=item sv_untaint + +Untaint an SV. Use C 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