# Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
# This program is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
+#
+# Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
package Scalar::Util;
require List::Util; # List::Util loads the XS
our @ISA = qw(Exporter);
-our @EXPORT_OK = qw(blessed dualvar reftype weaken isweak tainted readonly openhandle refaddr isvstring looks_like_number set_prototype);
-our $VERSION = "1.25";
+our @EXPORT_OK = qw(
+ blessed
+ dualvar
+ isdual
+ isvstring
+ isweak
+ looks_like_number
+ openhandle
+ readonly
+ refaddr
+ reftype
+ set_prototype
+ tainted
+ weaken
+);
+our $VERSION = "1.35";
$VERSION = eval $VERSION;
our @EXPORT_FAIL;
=head1 SYNOPSIS
- use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
- weaken isvstring looks_like_number set_prototype);
+ use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
+ tainted weaken isweak isvstring looks_like_number
+ set_prototype);
# and other useful utils appearing below
=head1 DESCRIPTION
By default C<Scalar::Util> does not export any subroutines. The
subroutines defined are
-=over 4
-
-=item blessed EXPR
+=head2 blessed EXPR
If EXPR evaluates to a blessed reference the name of the package
that it is blessed into is returned. Otherwise C<undef> is returned.
$obj = bless [], "Foo";
$class = blessed $obj; # "Foo"
-=item dualvar NUM, STRING
+Take care when using this function simply as a truth test (such as in
+C<if(blessed $ref)...>) because the package name C<"0"> is defined yet
+false.
+
+=head2 dualvar NUM, STRING
Returns a scalar that has the value NUM in a numeric context and the
value STRING in a string context.
$num = $foo + 2; # 12
$str = $foo . " world"; # Hello world
-=item isvstring EXPR
+=head2 isdual EXPR
-If EXPR is a scalar which was coded as a vstring the result is true.
+If EXPR is a scalar that is a dualvar, the result is true.
- $vs = v49.46.48;
- $fmt = isvstring($vs) ? "%vd" : "%s"; #true
- printf($fmt,$vs);
+ $foo = dualvar 86, "Nix";
+ $dual = isdual($foo); # true
-=item isweak EXPR
+Note that a scalar can be made to have both string and numeric content
+through numeric operations:
-If EXPR is a scalar which is a weak reference the result is true.
+ $foo = "10";
+ $dual = isdual($foo); # false
+ $bar = $foo + 0;
+ $dual = isdual($foo); # true
- $ref = \$foo;
- $weak = isweak($ref); # false
- weaken($ref);
- $weak = isweak($ref); # true
+Note that although C<$!> appears to be dual-valued variable, it is
+actually implemented using a tied scalar:
-B<NOTE>: Copying a weak reference creates a normal, strong, reference.
+ $! = 1;
+ print("$!\n"); # "Operation not permitted"
+ $dual = isdual($!); # false
- $copy = $ref;
- $weak = isweak($copy); # false
+You can capture its numeric and string content using:
-=item looks_like_number EXPR
+ $err = dualvar $!, $!;
+ $dual = isdual($err); # true
+
+=head2 isvstring EXPR
+
+If EXPR is a scalar which was coded as a vstring the result is true.
+
+ $vs = v49.46.48;
+ $fmt = isvstring($vs) ? "%vd" : "%s"; #true
+ printf($fmt,$vs);
+
+=head2 looks_like_number EXPR
Returns true if perl thinks EXPR is a number. See
L<perlapi/looks_like_number>.
-=item openhandle FH
+=head2 openhandle FH
Returns FH if FH may be used as a filehandle and is open, or FH is a tied
handle. Otherwise C<undef> is returned.
- $fh = openhandle(*STDIN); # \*STDIN
- $fh = openhandle(\*STDIN); # \*STDIN
- $fh = openhandle(*NOTOPEN); # undef
- $fh = openhandle("scalar"); # undef
-
-=item readonly SCALAR
+ $fh = openhandle(*STDIN); # \*STDIN
+ $fh = openhandle(\*STDIN); # \*STDIN
+ $fh = openhandle(*NOTOPEN); # undef
+ $fh = openhandle("scalar"); # undef
+
+=head2 readonly SCALAR
Returns true if SCALAR is readonly.
$readonly = foo($bar); # false
$readonly = foo(0); # true
-=item refaddr EXPR
+=head2 refaddr EXPR
If EXPR evaluates to a reference the internal memory address of
the referenced value is returned. Otherwise C<undef> is returned.
$obj = bless {}, "Foo";
$addr = refaddr $obj; # eg 88123488
-=item reftype EXPR
+=head2 reftype EXPR
If EXPR evaluates to a reference the type of the variable referenced
is returned. Otherwise C<undef> is returned.
$obj = bless {}, "Foo";
$type = reftype $obj; # HASH
-=item set_prototype CODEREF, PROTOTYPE
+=head2 set_prototype CODEREF, PROTOTYPE
Sets the prototype of the given function, or deletes it if PROTOTYPE is
undef. Returns the CODEREF.
set_prototype \&foo, '$$';
-=item tainted EXPR
+=head2 tainted EXPR
Return true if the result of EXPR is tainted
$taint = tainted("constant"); # false
$taint = tainted($ENV{PWD}); # true if running under -T
-=item weaken REF
+=head2 weaken REF
REF will be turned into a weak reference. This means that it will not
hold a reference count on the object it references. Also when the reference
be destroyed because there is now always a strong reference to them in the
@object array.
-=back
+=head2 isweak EXPR
+
+If EXPR is a scalar which is a weak reference the result is true.
+
+ $ref = \$foo;
+ $weak = isweak($ref); # false
+ weaken($ref);
+ $weak = isweak($ref); # true
+
+B<NOTE>: Copying a weak reference creates a normal, strong, reference.
+
+ $copy = $ref;
+ $weak = isweak($copy); # false
=head1 DIAGNOSTICS
https://perl5.git.perl.org / perl5.git / blobdiff