Scalar::Util#

📦 std

General-utility subroutines for inspecting and tagging scalar values.

What kind of thing a value is - an object of which class (blessed), which basic type underneath (reftype), which address (refaddr), a number in disguise (looks_like_number), a v-string (isvstring), read-only (readonly), tainted (tainted), an open filehandle (openhandle) - and two ways of making one: a value with separate number and string sides (dualvar), and a reference that does not keep its target alive (weaken). Nothing is exported by default; name what you need.

This is Scalar::Util from Scalar-List-Utils 1.70; Scalar/Util.pm is upstream’s. On perl 5.40 and later it makes blessed, refaddr, reftype, weaken, unweaken and isweak the builtin:: functions of the same names (isweak is builtin::is_weak), as upstream does; the others are ListUtil.xs’s XS functions.

Synopsis#

use Scalar::Util qw(blessed reftype refaddr looks_like_number dualvar
                    isdual readonly weaken isweak openhandle);

my $obj = bless {}, 'My::Class';
print blessed($obj), ' ', reftype($obj), "\n";        # My::Class HASH
print defined(blessed({})) ? "blessed\n" : "plain\n";  # plain

print join(',', map { looks_like_number($_) ? 1 : 0 }
                    42, '4.2e1', ' 42 ', 'abc', undef), "\n";  # 1,1,1,0,0

my $v = dualvar(5, 'five');
print $v + 1, ' ', "$v", "\n";                         # 6 five

my $ref = { name => 'x' };
my %cache = (x => $ref);
weaken($cache{x});                 # the cache does not keep it alive
undef $ref;
print defined $cache{x} ? "kept\n" : "gone\n";         # gone

print openhandle(\*STDIN) ? "open\n" : "closed\n";     # open

The builtin functions#

  • blessed($ref) - the class name of an object, undef for anything else (an unblessed reference, a plain scalar).

  • reftype($ref) - the type a reference points to - HASH, ARRAY, SCALAR, CODE, GLOB, REGEXP, … - ignoring any blessing; undef for a non-reference.

  • refaddr($ref) - the address a reference points to, as a number; the same for every reference to the same thing, whatever its class or overloading.

  • weaken($ref) - make this copy of a reference weak: it does not count towards keeping the target alive, and becomes undef when the target is freed. Copying it gives a strong reference again.

  • unweaken($ref) - make a weak reference strong again.

  • isweak($ref) - true if the reference is weak.

Differences from upstream#

None: every function is checked against perl 5.44 by t/81-xs-native/Scalar-Util, and upstream’s own tests pass unchanged (t/81-xs-native/List-Util, the upstream files).

Functions#

Inspection#

looks_like_number#

True if perl would use the value as a number without a “not numeric” warning: a number, or a string of digits with an optional sign, decimal point and exponent, surrounding whitespace allowed ("42", "-.5", " 4.2e1 "), or "Inf", "Infinity", "NaN". False for undef, the empty string, "abc", "1e", and for the notations only literals have ("0x10", "1_000"). An object that overloads 0+ counts by the value it converts to.

tainted#

tainted($var) - returns true if $var is tainted.

readonly#

readonly($var) - returns true if $var is read-only.

openhandle#

The argument itself if it is an open filehandle - a glob, a reference to one, or an IO object, opened (or tied) - and undef otherwise: for a handle never opened, one already closed, or anything that is no handle.

isdual#

True if the value currently has both a string and a numeric side - a dualvar, $!, but also an ordinary string once it has been used as a number (my $n = "10"; $n + 0; makes isdual($n) true), as perl caches the conversion.

isvstring#

True if the value is a v-string - written as v1.2.3, or as a bare number with two or more dots (1.2.3) - and false for the string "1.2.3".

Construction#

dualvar#

dualvar($num, $str): a value that is $num where a number is used and $str where a string is - as $! is both an error number and its message.

Other Functions#

reftype#

reftype($ref) - returns type string without blessing.

set_prototype#

set_prototype($code, $prototype) - sets the prototype of the subroutine given by the $code reference, or deletes it if $prototype is undef.