This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document CVf_UNIQUE flag better
[perl5.git] / pod / perlapi.pod
index 44e83be..61e52a1 100644 (file)
@@ -1085,6 +1085,21 @@ Clears a hash, making it empty.
 =for hackers
 Found in file hv.c
 
+=item hv_clear_placeholders
+
+Clears any placeholders from a hash.  If a restricted hash has any of its keys
+marked as readonly and the key is subsequently deleted, the key is not actually
+deleted but is marked by assigning it a value of &PL_sv_placeholder.  This tags
+it so it will be ignored by future operations such as iterating over the hash,
+but will still allow the hash to have a value reaasigned to the key at some
+future point.  This function clears any such placeholder keys from the hash.
+See Hash::Util::lock_keys() for an example of its use.
+
+       void    hv_clear_placeholders(HV* hb)
+
+=for hackers
+Found in file hv.c
+
 =item hv_delete
 
 Deletes a key/value pair in the hash.  The value SV is removed from the
@@ -1265,6 +1280,15 @@ Adds magic to a hash.  See C<sv_magic>.
 =for hackers
 Found in file hv.c
 
+=item hv_scalar
+
+Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
+
+       SV*     hv_scalar(HV* hv)
+
+=for hackers
+Found in file hv.c
+
 =item hv_store
 
 Stores an SV in a hash.  The hash key is specified as C<key> and C<klen> is
@@ -2879,6 +2903,16 @@ version which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
+=item SvIVx
+
+Coerces the given SV to an integer and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvIV> otherwise.
+
+       IV      SvIVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvIVX
 
 Returns the raw value in the SV's IV slot, without checks or conversions.
@@ -2889,12 +2923,11 @@ Only use when you are sure SvIOK is true. See also C<SvIV()>.
 =for hackers
 Found in file sv.h
 
-=item SvIVx
+=item SvIV_nomg
 
-Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvIV> otherwise.
+Like C<SvIV> but doesn't process magic.
 
-       IV      SvIVx(SV* sv)
+       IV      SvIV_nomg(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2994,22 +3027,22 @@ which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
-=item SvNVX
+=item SvNVx
 
-Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
+Coerces the given SV to a double and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvNV> otherwise.
 
-       NV      SvNVX(SV* sv)
+       NV      SvNVx(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvNVx
+=item SvNVX
 
-Coerces the given SV to a double and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvNV> otherwise.
+Returns the raw value in the SV's NV slot, without checks or conversions.
+Only use when you are sure SvNOK is true. See also C<SvNV()>.
 
-       NV      SvNVx(SV* sv)
+       NV      SvNVX(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -3203,21 +3236,21 @@ Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
 =for hackers
 Found in file sv.h
 
-=item SvPVx
+=item SvPVX
 
-A version of C<SvPV> which guarantees to evaluate sv only once.
+Returns a pointer to the physical string in the SV.  The SV must contain a
+string.
 
-       char*   SvPVx(SV* sv, STRLEN len)
+       char*   SvPVX(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvPVX
+=item SvPVx
 
-Returns a pointer to the physical string in the SV.  The SV must contain a
-string.
+A version of C<SvPV> which guarantees to evaluate sv only once.
 
-       char*   SvPVX(SV* sv)
+       char*   SvPVx(SV* sv, STRLEN len)
 
 =for hackers
 Found in file sv.h
@@ -3255,6 +3288,15 @@ stringified form becoming C<SvPOK>.  Handles 'get' magic.
 =for hackers
 Found in file sv.h
 
+=item SvPV_nomg
+
+Like C<SvPV> but doesn't process magic.
+
+       char*   SvPV_nomg(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
 =item SvREFCNT
 
 Returns the value of the object's reference count.
@@ -3456,6 +3498,16 @@ for a version which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
+=item SvUVx
+
+Coerces the given SV to an unsigned integer and returns it. Guarantees to
+evaluate sv only once. Use the more efficient C<SvUV> otherwise.
+
+       UV      SvUVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
 =item SvUVX
 
 Returns the raw value in the SV's UV slot, without checks or conversions.
@@ -3466,12 +3518,11 @@ Only use when you are sure SvIOK is true. See also C<SvUV()>.
 =for hackers
 Found in file sv.h
 
-=item SvUVx
+=item SvUV_nomg
 
-Coerces the given SV to an unsigned integer and returns it. Guarantees to
-evaluate sv only once. Use the more efficient C<SvUV> otherwise.
+Like C<SvUV> but doesn't process magic.
 
-       UV      SvUVx(SV* sv)
+       UV      SvUV_nomg(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -3516,12 +3567,13 @@ named after the PV if we're a string.
 =for hackers
 Found in file sv.c
 
-=item sv_2iv
+=item sv_2iv_flags
 
-Return the integer value of an SV, doing any necessary string conversion,
-magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
+Return the integer value of an SV, doing any necessary string
+conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
 
-       IV      sv_2iv(SV* sv)
+       IV      sv_2iv_flags(SV* sv, I32 flags)
 
 =for hackers
 Found in file sv.c
@@ -3619,13 +3671,13 @@ use the macro wrapper C<SvPV_nolen(sv)> instead.
 =for hackers
 Found in file sv.c
 
-=item sv_2uv
+=item sv_2uv_flags
 
 Return the unsigned integer value of an SV, doing any necessary string
-conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
-macros.
+conversion.  If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
 
-       UV      sv_2uv(SV* sv)
+       UV      sv_2uv_flags(SV* sv, I32 flags)
 
 =for hackers
 Found in file sv.c