From: Gurusamy Sarathy Date: Wed, 13 May 1998 10:08:13 +0000 (+0000) Subject: [win32] merge change#683 from maintbranch X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9abd00ed50d0f365eaf966f7c6c43a9e54e91a44;p=p5sagit%2Fp5-mst-13.2.git [win32] merge change#683 from maintbranch p4raw-link: @683 on //depot/maint-5.004/perl: f43943baae55347834538dc5bcb4fbc3fe2e1c72 p4raw-id: //depot/win32/perl@928 --- diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 83986c9..b46ccc3 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -51,6 +51,7 @@ To change the value of an *already-existing* SV, there are seven routines: void sv_setpv(SV*, char*); void sv_setpvn(SV*, char*, int) void sv_setpvf(SV*, const char*, ...); + void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_setsv(SV*, SV*); Notice that you can choose to specify the length of the string to be @@ -58,8 +59,20 @@ assigned by using C, C, or C, or you may allow Perl to calculate the length by using C or by specifying 0 as the second argument to C. Be warned, though, that Perl will determine the string's length by using C, which depends on the -string terminating with a NUL character. The arguments of C -are processed like C, and the formatted output becomes the value. +string terminating with a NUL character. + +The arguments of C are processed like C, and the +formatted output becomes the value. + +C is an analogue of C, but it allows you to specify +either a pointer to a variable argument list or the address and length of +an array of SVs. The last argument points to a boolean; on return, if that +boolean is true, then locale-specific information has been used to format +the string, and the string's contents are therefore untrustworty (see +L). This pointer may be NULL if that information is not +important. Note that this function requires you to specify the length of +the format. + The C functions are not generic enough to operate on values that have "magic". See L later in this document. @@ -127,16 +140,20 @@ you can use the following functions: void sv_catpv(SV*, char*); void sv_catpvn(SV*, char*, int); void sv_catpvf(SV*, const char*, ...); + void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool); void sv_catsv(SV*, SV*); The first function calculates the length of the string to be appended by using C. In the second, you specify the length of the string yourself. The third function processes its arguments like C and -appends the formatted output. The fourth function extends the string -stored in the first SV with the string stored in the second SV. It also -forces the second SV to be interpreted as a string. The C -functions are not generic enough to operate on values that have "magic". -See L later in this document. +appends the formatted output. The fourth function works like C. +You can specify the address and length of an array of SVs instead of the +va_list argument. The fifth function extends the string stored in the first +SV with the string stored in the second SV. It also forces the second SV +to be interpreted as a string. + +The C functions are not generic enough to operate on values that +have "magic". See L later in this document. If you know the name of a scalar variable, you can get a pointer to its SV by using the following: @@ -473,8 +490,25 @@ Perl calculate the string length. SV is blessed if C is non-null. SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length); - int sv_isa(SV* sv, char* name); - int sv_isobject(SV* sv); +Tests whether the SV is blessed into the specified class. It does not +check inheritance relationships. + + int sv_isa(SV* sv, char* name); + +Tests whether the SV is a reference to a blessed object. + + int sv_isobject(SV* sv); + +Tests whether the SV is derived from the specified class. SV can be either +a reference to a blessed object or a string containing a class name. This +is the function implementing the C functionality. + + bool sv_derived_from(SV* sv, char* name); + +To check if you've got an object derived from a specific class you have +to write: + + if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... } =head2 Creating New Variables @@ -2670,6 +2704,14 @@ specified class. int sv_derived_from(SV* sv, char* class) +=item sv_derived_from + +Returns a boolean indicating whether the SV is derived from the specified +class. This is the function that implements C. It works +for class names as well as for objects. + + bool sv_derived_from _((SV* sv, char* name)); + =item SvEND Returns a pointer to the last character in the string which is in the SV. @@ -2754,7 +2796,7 @@ B setting. Use C. =item sv_isa Returns a boolean indicating whether the SV is blessed into the specified -class. This does not know how to check for subtype, so it doesn't work in +class. This does not check for subtypes; use C to verify an inheritance relationship. int sv_isa (SV* sv, char* name) @@ -2771,8 +2813,8 @@ will return false. Returns the integer which is in the SV. - int SvIV (SV* sv) - + int SvIV (SV* sv) + =item SvIVX Returns the integer which is stored in the SV. @@ -3284,6 +3326,25 @@ Like C, but also handles 'set' magic. void sv_usepvn_mg (SV* sv, char* ptr, STRLEN len) +=item sv_vcatpvfn(sv, pat, patlen, args, svargs, svmax, used_locale) + +Processes its arguments like C and appends the formatted output +to an SV. Uses an array of SVs if the C style variable argument list is +missing (NULL). Indicates if locale information has been used for formatting. + + void sv_catpvfn _((SV* sv, const char* pat, STRLEN patlen, + va_list *args, SV **svargs, I32 svmax, + bool *used_locale)); + +=item sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale) + +Works like C but copies the text into the SV instead of +appending it. + + void sv_setpvfn _((SV* sv, const char* pat, STRLEN patlen, + va_list *args, SV **svargs, I32 svmax, + bool *used_locale)); + =item SvUV Returns the unsigned integer which is in the SV.