Scalar::Util(3perl)

📦

version 5.44.0 · 14 versions

💖 Scalar::Util — the perl manual, but make it make sense 💖

okay so bestie, you're looking at Scalar::Util(3perl), and honestly? it's a little sleeper hit. it's a grab bag of scalar subroutines that live in the Perl Programmers Reference Guide, and once you know what's in here you're gonna be obsessed. let's go 🦋

✨ NAME ✨

Scalar::Util — a whole lil selection of general-utility scalar subroutines. that's it, that's the pitch 💅

✨ SYNOPSIS ✨

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

like yes, you can import the whole squad, or you can just grab the ones you need. no pressure 🫶

✨ DESCRIPTION ✨

Scalar::Util is a little collection of subroutines that people kept saying "omg can this be in perl core pls" about. but here's the thing — the usage isn't really high enough to justify giving them their own keyword, and each one is so small that making them individual extensions would just be wasteful. so they all live here together, like a cute little friend group 🎀

By default Scalar::Util does not export any subroutines. nothing shows up unless you ask for it, respectful king behavior 👑

🌈 Core Perl `builtin` Functions 🌈

so this is the glow-up era. lots of functions in this module were the inspiration for a new experimental facility in recent Perl versions. starting at various development versions from 5.35.7 onward, equivalent functions to many of these utilities are available in the builtin:: package. iconic.

use Scalar::Util qw(blessed);

$class = blessed $obj;

$class = builtin::blessed $obj;  # equivalent

for more info, go read the documentation on builtin. go on, we'll wait 💜

🔥 FUNCTIONS FOR REFERENCES 🔥

these ones all do useful lil things to reference values. reference girlies rise 🙌

`blessed` 👑

my $pkg = blessed( $ref );

if $ref is a blessed reference, you get back the name of the package it's blessed into. otherwise you get undef, sorry bestie.

$scalar = "foo";
$class  = blessed $scalar;           # undef

$ref    = [];
$class  = blessed $ref;              # undef

$obj    = bless [], "Foo";
$class  = blessed $obj;              # "Foo"

⚠️ careful bestie: do NOT just use this as a truth test, like in if(blessed $ref).... because the package name "0" is defined but false. that's a trap and it will get you 💀

Since Perl version 5.35.7, an equivalent function is available as builtin::blessed.

`refaddr` 📍

my $addr = refaddr( $ref );

if $ref is a reference, you get the internal memory address of the referenced value as a plain integer. otherwise, undef. it's giving "where does this actually live" energy.

$addr = refaddr "string";           # undef
$addr = refaddr \$var;              # eg 12345678
$addr = refaddr [];                 # eg 23456784

$obj  = bless {}, "Foo";
$addr = refaddr $obj;               # eg 88123488

Since Perl version 5.35.7, an equivalent function is available as builtin::refaddr.

`reftype` 🔍

my $type = reftype( $ref );

if $ref is a reference, you get the basic Perl type of the thing it points at, as a plain string — stuff like "ARRAY" or "HASH". otherwise undef.

$type = reftype "string";           # undef
$type = reftype \$var;              # SCALAR
$type = reftype [];                 # ARRAY

$obj  = bless {}, "Foo";
$type = reftype $obj;               # HASH

ok now listen, this one's important: for internal reasons, all precompiled regexps (qr/.../) are blessed references. so ref() returns the package name string "Regexp" on those, but reftype() returns the underlying C structure type of "REGEXP" in ALL CAPS. no cap, that's just how it is.

Since Perl version 5.35.7, an equivalent function is available as builtin::reftype.

`weaken` 🥀

weaken( $ref );

the lvalue $ref gets turned into a weak reference. meaning: it no longer holds a reference count on the object it references. and also, when the reference count on that object hits zero, the reference gets set to undef. this function mutates the lvalue passed as its argument and returns no value.

it's handy for keeping copies of references when you don't wanna prevent the object from being DESTROY-ed at its usual time.

{
  my $var;
  $ref = \$var;
  weaken($ref);                     # Make $ref a weak reference
}
# $ref is now undef

ok but here's the gotcha: if you take a copy of a scalar with a weakened reference, the copy becomes a strong reference. sneaky.

my $var;
my $foo = \$var;
weaken($foo);                       # Make $foo a weak reference
my $bar = $foo;                     # $bar is now a strong reference

and this gets even less obvious in other situations, like grep(). for example when you grep through a list of weakened references to objects that might already be destroyed:

@object = grep { defined } @object;

this will indeed remove all references to destroyed objects, BUT the remaining references to objects will be strong — which means those remaining objects will never be destroyed, because there's now always a strong reference to them sitting in the @object array. it's giving "you thought you cleaned up but you actually made it permanent" 😭

Since Perl version 5.35.7, an equivalent function is available as builtin::weaken.

`unweaken` 💪

unweaken( $ref );

Since version 1.36.

the lvalue REF gets turned from a weak reference back into a normal (strong) reference again. this function mutates the lvalue passed as its argument and returns no value. it undoes exactly what weaken did. the character arc is complete ✨

this function is slightly neater and more convenient than the otherwise-equivalent code:

my $tmp = $REF;
undef $REF;
$REF = $tmp;

(because in particular, simply assigning a weak reference back to itself does not work to unweaken it; $REF = $REF does not work. periodt.)

Since Perl version 5.35.7, an equivalent function is available as builtin::unweaken.

`isweak` 🌾

my $weak = isweak( $ref );

returns true if $ref is a weak reference. simple as.

$ref  = \$foo;
$weak = isweak($ref);               # false
weaken($ref);
$weak = isweak($ref);               # true

NOTE: copying a weak reference creates a normal, strong reference. yes really.

$copy = $ref;
$weak = isweak($copy);              # false

Since Perl version 5.35.7, an equivalent function is available as builtin::is_weak.

🌸 OTHER FUNCTIONS 🌸

the rest of the squad, all together, slaying in their own ways 🧚

`dualvar` 🎭

my $var = dualvar( $num, $string );

returns a scalar that has the value $num in a numeric context and the value $string in a string context. two faces, one variable. main character energy fr fr.

$foo = dualvar 10, "Hello";
$num = $foo + 2;                    # 12
$str = $foo . " world";             # Hello world

`isdual` 🧬

my $dual = isdual( $var );

Since version 1.26.

if $var is a scalar that has both numeric and string values, the result is true.

$foo = dualvar 86, "Nix";
$dual = isdual($foo);               # true

ngl a scalar can be made to have both string and numeric content through standard operations:

$foo = "10";
$dual = isdual($foo);               # false
$bar = $foo + 0;
$dual = isdual($foo);               # true

the $! variable is commonly dual-valued — though it's also magical in other ways, because of course it is 🙈

$! = 1;
$dual = isdual($!);                 # true
print("$!\n");                      # "Operation not permitted"

CAUTION: this function is not as useful as it may seem. dualvars aren't actually a distinct concept in Perl — they're a standard internal construct of all scalar values. almost any value could be considered a dualvar by this function through the course of normal operations. so like, don't build your whole personality around it 💀

`isvstring` 🔤

my $vstring = isvstring( $var );

if $var is a scalar which was coded as a vstring, you get true.

$vs   = v49.46.48;
$fmt  = isvstring($vs) ? "%vd" : "%s"; #true
printf($fmt,$vs);

`looks_like_number` 🔢

my $isnum = looks_like_number( $var );

returns true if perl thinks $var is a number. yes, "thinks" — it's a vibe check, not a guarantee. see "looks_like_number" in perlapi for the details.

`openhandle` 🚪

my $fh = openhandle( $fh );

returns $fh itself if $fh may be used as a filehandle and is open, or if it's a tied handle. otherwise undef is returned. it's giving "are you actually open or just pretending" 🔥

$fh = openhandle(*STDIN);           # \*STDIN
$fh = openhandle(\*STDIN);          # \*STDIN
$fh = openhandle(*NOTOPEN);         # undef
$fh = openhandle("scalar");         # undef

`readonly` 🔒

my $ro = readonly( $var );

returns true if $var is readonly. locked down, protected, unbothered.

sub foo { readonly($_[0]) }

$readonly = foo($bar);              # false
$readonly = foo(0);                 # true

`set_prototype` 🛠️

my $code = set_prototype( $code, $prototype );

sets the prototype of the function given by the $code reference — or deletes it if $prototype is undef. returns the $code reference itself.

set_prototype \&foo, '$$';

`tainted` ☣️

my $t = tainted( $var );

returns true if $var is tainted. stay safe out here bestie.

$taint = tainted("constant");       # false
$taint = tainted($ENV{PWD});        # true if running under -T

🚨 DIAGNOSTICS 🚨

using the module might throw one of these errors during import. don't panic, just read 💅

Vstrings are not implemented in this version of perl — the version of perl you're using doesn't implement Vstrings. to use isvstring you're gonna need a newer release of perl. upgrade era 🌱

💀 KNOWN BUGS 💀

there is a bug in perl5.6.0 with UVs that are >= 1<<31. it shows up as tests 8 and 9 of dualvar.t failing. not us, not our problem, but now you know 🫠

👀 SEE ALSO 👀

List::Util

👑 COPYRIGHT 👑

Additionally weaken and isweak, which are:

okay that's the whole page babes, you ate it, you read it, you're a reference-handling legend now. this was perl v5.44.0, dated 2026-10-17, part of the Perl Programmers Reference Guide — mwah, go write something cute 🎀💖✨

📦 where this page comes from

arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Scalar::Util(3perl)

💖 Scalar::Util — the perl manual, but make it make sense 💖

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

🌈 Core Perl builtin Functions 🌈

🔥 FUNCTIONS FOR REFERENCES 🔥

blessed 👑

refaddr 📍

reftype 🔍

weaken 🥀

unweaken 💪

isweak 🌾