X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=08420967a83f26791ab7cf8d87e2f51380a8c08d;hb=b03ad8f690c4dcc613a1ec77d747e2d429945b16;hp=94f26eb63a9c674e8f744ebef8d8906f3b033d13;hpb=62375a601d6dbbc42fa6d70d83d0a60b73d1b86d;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 94f26eb..0842096 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -297,6 +297,8 @@ Sort an array. Here is an example: sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); +See lib/sort.pm for details about controlling the sorting algorithm. + void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) =for hackers @@ -1098,6 +1100,7 @@ NOTE: Before version 5.004_65, C used to return the number of hash buckets that happen to be in use. If you still need that esoteric value, you can get it through the macro C. + I32 hv_iterinit(HV* tb) =for hackers @@ -1128,6 +1131,14 @@ Found in file hv.c Returns entries from a hash iterator. See C. +You may call C or C on the hash entry that the +iterator currently points to, without losing your place or invalidating your +iterator. Note that in this case the current entry is deleted from the hash +with your iterator holding the last reference to it. Your iterator is flagged +to free the entry on the next call to C, so you must not discard +your iterator immediately else the entry will leak - call C to +trigger the resource deallocation. + HE* hv_iternext(HV* tb) =for hackers @@ -1143,6 +1154,26 @@ operation. =for hackers Found in file hv.c +=item hv_iternext_flags + +Returns entries from a hash iterator. See C and C. +The C value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is +set the placeholders keys (for restricted hashes) will be returned in addition +to normal keys. By default placeholders are automatically skipped over. +Currently a placeholder is implemented with a value that is literally +<&Perl_sv_undef> (a regular C value is a normal read-write SV for which +C is false). Note that the implementation of placeholders and +restricted hashes may change, and the implementation currently is +insufficiently abstracted for any change to be tidy. + +NOTE: this function is experimental and may change or be +removed without notice. + + HE* hv_iternext_flags(HV* tb, I32 flags) + +=for hackers +Found in file hv.c + =item hv_iterval Returns the value from the current position of the hash iterator. See @@ -1456,6 +1487,16 @@ memory is zeroed with C. =for hackers Found in file handy.h +=item Poison + +Fill up memory with a pattern (byte 0xAB over and over again) that +hopefully catches attempts to access uninitialized memory. + + void Poison(void* dest, int nitems, type) + +=for hackers +Found in file handy.h + =item Renew The XSUB-writer's interface to the C C function. @@ -1486,30 +1527,34 @@ Found in file handy.h =item savepv -Copy a string to a safe spot. This does not use an SV. +Perl's version of C. Returns a pointer to a newly allocated +string which is a duplicate of C. The size of the string is +determined by C. The memory allocated for the new string can +be freed with the C function. - char* savepv(const char* sv) + char* savepv(const char* pv) =for hackers Found in file util.c =item savepvn -Copy a string to a safe spot. The C indicates number of bytes to -copy. If pointer is NULL allocate space for a string of size specified. -This does not use an SV. +Perl's version of what C would be if it existed. Returns a +pointer to a newly allocated string which is a duplicate of the first +C bytes from C. The memory allocated for the new string can be +freed with the C function. - char* savepvn(const char* sv, I32 len) + char* savepvn(const char* pv, I32 len) =for hackers Found in file util.c =item savesharedpv -Copy a string to a safe spot in memory shared between threads. -This does not use an SV. +A version of C which allocates the duplicate string in memory +which is shared between threads. - char* savesharedpv(const char* sv) + char* savesharedpv(const char* pv) =for hackers Found in file util.c @@ -4067,25 +4112,6 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_setpviv - -Copies an integer into the given SV, also updating its string value. -Does not handle 'set' magic. See C. - - void sv_setpviv(SV* sv, IV num) - -=for hackers -Found in file sv.c - -=item sv_setpviv_mg - -Like C, but also handles 'set' magic. - - void sv_setpviv_mg(SV *sv, IV iv) - -=for hackers -Found in file sv.c - =item sv_setpvn Copies a string into an SV. The C parameter indicates the number of @@ -4200,7 +4226,6 @@ You probably want to use one of the assortment of wrappers, such as C, C, C and C. - void sv_setsv(SV* dsv, SV* ssv) =for hackers @@ -4544,9 +4569,9 @@ Found in file utf8.c =item is_utf8_char Tests if some arbitrary number of bytes begins in a valid UTF-8 -character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character. -The actual number of bytes in the UTF-8 character will be returned if -it is valid, otherwise 0. +character. Note that an INVARIANT (i.e. ASCII) character is a valid +UTF-8 character. The actual number of bytes in the UTF-8 character +will be returned if it is valid, otherwise 0. STRLEN is_utf8_char(U8 *p)