av.c apidoc
[p5sagit/p5-mst-13.2.git] / pod / perlapi.pod
index effbda4..c7edea9 100644 (file)
@@ -38,6 +38,28 @@ array itself.
 =for hackers
 Found in file av.c
 
+=item av_delete
+
+Deletes the element indexed by C<key> from the array.  Returns the
+deleted element. C<flags> is currently ignored.
+
+       SV*     av_delete(AV* ar, I32 key, I32 flags)
+
+=for hackers
+Found in file av.c
+
+=item av_exists
+
+Returns true if the element indexed by C<key> has been initialized.
+
+This relies on the fact that uninitialized array elements are set to
+C<&PL_sv_undef>.
+
+       bool    av_exists(AV* ar, I32 key)
+
+=for hackers
+Found in file av.c
+
 =item av_extend
 
 Pre-extend an array.  The C<key> is the index to which the array should be
@@ -62,6 +84,16 @@ more information on how to use this function on tied arrays.
 =for hackers
 Found in file av.c
 
+=item av_fill
+
+Ensure than an array has a given number of elements, equivalent to
+Perl's C<$#array = $fill;>.
+
+       void    av_fill(AV* ar, I32 fill)
+
+=for hackers
+Found in file av.c
+
 =item av_len
 
 Returns the highest index in the array.  Returns -1 if the array is
@@ -2272,19 +2304,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<svtype>.
+=item svtype
 
-       svtype  SvTYPE(SV* sv)
+An enum of flags for Perl types.  These are found in the file B<sv.h> 
+in the C<svtype> enum.  Test these flags with the C<SvTYPE> 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<sv.h> 
-in the C<svtype> enum.  Test these flags with the C<SvTYPE> macro.
+Returns the type of the SV.  See C<svtype>.
+
+       svtype  SvTYPE(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2478,6 +2510,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 +2531,16 @@ C<sv2>.
 =for hackers
 Found in file sv.c
 
+=item sv_cmp_locale
+
+Compares the strings in two SVs in a locale-aware manner. See
+L</sv_cmp_locale>
+
+       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 +2571,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<sv_unref> and will
@@ -2580,6 +2651,16 @@ Returns the length of the string in the SV.  See also C<SvCUR>.
 =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 +2689,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</sv_pvn_force>.
+
+       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 +2950,24 @@ Like C<sv_setuv>, 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 +3013,43 @@ Like C<sv_usepvn>, 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<fail_ok> 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<SvUTF8>
+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<vsprintf> and appends the formatted output