X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=ab0463f9a33f7157c70b7767b90392e80b4af319;hb=8cebccf496af9176158accf26e9c154b6de36ffe;hp=cd84734aeff6090d364adc1b39401e8879313789;hpb=907b3e23950be4dd31c150e1902fbd26201355bd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index cd84734..ab0463f 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -848,9 +848,9 @@ will also be escaped. Normally the SV will be cleared before the escaped string is prepared, but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur. -If PERL_PV_ESCAPE_UNI is set then the input string is treated as unicode, +If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode, if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned -using C to determine if it is unicode. +using C to determine if it is Unicode. If PERL_PV_ESCAPE_ALL is set then all input chars will be output using C<\x01F1> style escapes, otherwise only chars above 255 will be @@ -887,21 +887,21 @@ X |const U32 flags Converts a string into something presentable, handling escaping via -pv_escape() and supporting quoting and elipses. +pv_escape() and supporting quoting and ellipses. If the PERL_PV_PRETTY_QUOTE flag is set then the result will be double quoted with any double quotes in the string escaped. Otherwise if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in angle brackets. -If the PERL_PV_PRETTY_ELIPSES flag is set and not all characters in -string were output then an elipses C<...> will be appended to the +If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in +string were output then an ellipsis C<...> will be appended to the string. Note that this happens AFTER it has been quoted. If start_color is non-null then it will be inserted after the opening quote (if there is one) but before the escaped text. If end_color is non-null then it will be inserted after the escaped text but before -any quotes or elipses. +any quotes or ellipses. Returns a pointer to the prettified text as held by dsv. @@ -1193,6 +1193,28 @@ Found in file mathoms.c =back +=head1 Functions in file pp_ctl.c + + +=over 8 + +=item find_runcv +X + +Locate the CV corresponding to the currently executing sub or eval. +If db_seqp is non_null, skip CVs that are in the DB package and populate +*db_seqp with the cop sequence number at the point that the DB:: code was +entered. (allows debuggers to eval in the scope of the breakpoint rather +than in the scope of the debugger itself). + + CV* find_runcv(U32 *db_seqp) + +=for hackers +Found in file pp_ctl.c + + +=back + =head1 Functions in file pp_pack.c @@ -2572,6 +2594,19 @@ wrapper for C). =for hackers Found in file handy.h +=item sv_destroyable +X + +Dummy routine which reports that object can be destroyed when there is no +sharing module present. It ignores its single SV argument, and returns +'true'. Exists to avoid test for a NULL function pointer and because it +could potentially warn under some level of strict-ness. + + bool sv_destroyable(SV *sv) + +=for hackers +Found in file util.c + =item sv_nosharing X @@ -2698,44 +2733,6 @@ invalidated). =for hackers Found in file mro.c -=item mro_get_linear_isa_c3 -X - -Returns the C3 linearization of @ISA -the given stash. The return value is a read-only AV*. -C should be 0 (it is used internally in this -function's recursion). - -You are responsible for C on the -return value if you plan to store it anywhere -semi-permanently (otherwise it might be deleted -out from under you the next time the cache is -invalidated). - - AV* mro_get_linear_isa_c3(HV* stash, I32 level) - -=for hackers -Found in file mro.c - -=item mro_get_linear_isa_dfs -X - -Returns the Depth-First Search linearization of @ISA -the given stash. The return value is a read-only AV*. -C should be 0 (it is used internally in this -function's recursion). - -You are responsible for C on the -return value if you plan to store it anywhere -semi-permanently (otherwise it might be deleted -out from under you the next time the cache is -invalidated). - - AV* mro_get_linear_isa_dfs(HV* stash, I32 level) - -=for hackers -Found in file mro.c - =item mro_method_changed_in X @@ -3135,6 +3132,50 @@ Found in file intrpvar.h =back +=head1 REGEXP Functions + +=over 8 + +=item SvRX +X + +Convenience macro to get the REGEXP from a SV. This is approximately +equivalent to the following snippet: + + if (SvMAGICAL(sv)) + mg_get(sv); + if (SvROK(sv) && + (tmpsv = (SV*)SvRV(sv)) && + SvTYPE(tmpsv) == SVt_PVMG && + (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr))) + { + return (REGEXP *)tmpmg->mg_obj; + } + +NULL will be returned if a REGEXP* is not found. + + REGEXP * SvRX(SV *sv) + +=for hackers +Found in file regexp.h + +=item SvRXOK +X + +Returns a boolean indicating whether the SV contains qr magic +(PERL_MAGIC_qr). + +If you want to do something with the REGEXP* later use SvRX instead +and check for NULL. + + bool SvRXOK(SV* sv) + +=for hackers +Found in file regexp.h + + +=back + =head1 Simple Exception Handling Macros =over 8 @@ -5101,11 +5142,11 @@ X Creates a new SV with its SvPVX_const pointing to a shared string in the string table. If the string does not already exist in the table, it is created -first. Turns on READONLY and FAKE. The string's hash is stored in the UV -slot of the SV; if the C parameter is non-zero, that value is used; -otherwise the hash is computed. The idea here is that as the string table -is used for shared hash keys these strings will have SvPVX_const == HeKEY and -hash lookup will avoid string compare. +first. Turns on READONLY and FAKE. If the C parameter is non-zero, that +value is used; otherwise the hash is computed. The string's hash can be later +be retrieved from the SV with the C macro. The idea here is +that as the string table is used for shared hash keys these strings will have +SvPVX_const == HeKEY and hash lookup will avoid string compare. SV* newSVpvn_share(const char* s, I32 len, U32 hash) @@ -5171,7 +5212,7 @@ Found in file sv.c =item newSV_type X -Creates a new SV, of the type specificied. The reference count for the new SV +Creates a new SV, of the type specified. The reference count for the new SV is set to 1. SV* newSV_type(svtype type) @@ -6727,7 +6768,7 @@ Found in file utf8.c X Bottom level UTF-8 decode routine. -Returns the unicode code point value of the first character in the string C +Returns the Unicode code point value of the first character in the string C which is assumed to be in UTF-8 encoding and no longer than C; C will be set to the length, in bytes, of that character.