1Scalar::Util(3) User Contributed Perl Documentation Scalar::Util(3)
2
6 Scalar::Util - A selection of general-utility scalar subroutines
7
9 use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
10 tainted weaken isweak isvstring looks_like_number
11 set_prototype);
12 # and other useful utils appearing below
13
15 "Scalar::Util" contains a selection of subroutines that people have
16 expressed would be nice to have in the perl core, but the usage would
17 not really be high enough to warrant the use of a keyword, and the size
18 would be so small that being individual extensions would be wasteful.
19 By default "Scalar::Util" does not export any subroutines.
21 Core Perl "builtin" Functions
23 Many functions in this module have served as the inspiration for a new
24 experimental facility in recent versions of Perl. From various
25 development versions, starting at 5.35.7, equivalent functions to many
26 of these utilities are available in the "builtin::" package.
27 use Scalar::Util qw(blessed);
29 $class = blessed $obj;
31 $class = builtin::blessed $obj; # equivalent
33 For more information, see the documentation on builtin.
35
37 The following functions all perform some useful activity on reference
38 values.
39 blessed
41 my $pkg = blessed( $ref );
42 If $ref is a blessed reference, the name of the package that it is
44 blessed into is returned. Otherwise "undef" is returned.
45 $scalar = "foo";
47 $class = blessed $scalar; # undef
48 $ref = [];
50 $class = blessed $ref; # undef
51 $obj = bless [], "Foo";
53 $class = blessed $obj; # "Foo"
54 Take care when using this function simply as a truth test (such as in
56 "if(blessed $ref)...") because the package name "0" is defined yet
57 false.
58 Since Perl version 5.35.7 an equivalent function is available as
60 "builtin::blessed".
61 refaddr
63 my $addr = refaddr( $ref );
64 If $ref is reference, the internal memory address of the referenced
66 value is returned as a plain integer. Otherwise "undef" is returned.
67 $addr = refaddr "string"; # undef
69 $addr = refaddr \$var; # eg 12345678
70 $addr = refaddr []; # eg 23456784
71 $obj = bless {}, "Foo";
73 $addr = refaddr $obj; # eg 88123488
74 Since Perl version 5.35.7 an equivalent function is available as
76 "builtin::refaddr".
77 reftype
79 my $type = reftype( $ref );
80 If $ref is a reference, the basic Perl type of the variable referenced
82 is returned as a plain string (such as "ARRAY" or "HASH"). Otherwise
83 "undef" is returned.
84 $type = reftype "string"; # undef
86 $type = reftype \$var; # SCALAR
87 $type = reftype []; # ARRAY
88 $obj = bless {}, "Foo";
90 $type = reftype $obj; # HASH
91 Note that for internal reasons, all precompiled regexps ("qr/.../") are
93 blessed references; thus ref() returns the package name string "Regexp"
94 on these but reftype() will return the underlying C structure type of
95 "REGEXP" in all capitals.
96 Since Perl version 5.35.7 an equivalent function is available as
98 "builtin::reftype".
99 weaken
101 weaken( $ref );
102 The lvalue $ref will be turned into a weak reference. This means that
104 it will not hold a reference count on the object it references. Also,
105 when the reference count on that object reaches zero, the reference
106 will be set to undef. This function mutates the lvalue passed as its
107 argument and returns no value.
108 This is useful for keeping copies of references, but you don't want to
110 prevent the object being DESTROY-ed at its usual time.
111 {
113 my $var;
114 $ref = \$var;
115 weaken($ref); # Make $ref a weak reference
116 }
117 # $ref is now undef
118 Note that if you take a copy of a scalar with a weakened reference, the
120 copy will be a strong reference.
121 my $var;
123 my $foo = \$var;
124 weaken($foo); # Make $foo a weak reference
125 my $bar = $foo; # $bar is now a strong reference
126 This may be less obvious in other situations, such as grep(), for
128 instance when grepping through a list of weakened references to objects
129 that may have been destroyed already:
130 @object = grep { defined } @object;
132 This will indeed remove all references to destroyed objects, but the
134 remaining references to objects will be strong, causing the remaining
135 objects to never be destroyed because there is now always a strong
136 reference to them in the @object array.
137 Since Perl version 5.35.7 an equivalent function is available as
139 "builtin::weaken".
140 unweaken
142 unweaken( $ref );
143 Since version 1.36.
145 The lvalue "REF" will be turned from a weak reference back into a
147 normal (strong) reference again. This function mutates the lvalue
148 passed as its argument and returns no value. This undoes the action
149 performed by "weaken".
150 This function is slightly neater and more convenient than the
152 otherwise-equivalent code
153 my $tmp = $REF;
155 undef $REF;
156 $REF = $tmp;
157 (because in particular, simply assigning a weak reference back to
159 itself does not work to unweaken it; "$REF = $REF" does not work).
160 Since Perl version 5.35.7 an equivalent function is available as
162 "builtin::unweaken".
163 isweak
165 my $weak = isweak( $ref );
166 Returns true if $ref is a weak reference.
168 $ref = \$foo;
170 $weak = isweak($ref); # false
171 weaken($ref);
172 $weak = isweak($ref); # true
173 NOTE: Copying a weak reference creates a normal, strong, reference.
175 $copy = $ref;
177 $weak = isweak($copy); # false
178 Since Perl version 5.35.7 an equivalent function is available as
180 "builtin::is_weak".
181
183 dualvar
184 my $var = dualvar( $num, $string );
185 Returns a scalar that has the value $num in a numeric context and the
187 value $string in a string context.
188 $foo = dualvar 10, "Hello";
190 $num = $foo + 2; # 12
191 $str = $foo . " world"; # Hello world
192 isdual
194 my $dual = isdual( $var );
195 Since version 1.26.
197 If $var is a scalar that has both numeric and string values, the result
199 is true.
200 $foo = dualvar 86, "Nix";
202 $dual = isdual($foo); # true
203 Note that a scalar can be made to have both string and numeric content
205 through standard operations:
206 $foo = "10";
208 $dual = isdual($foo); # false
209 $bar = $foo + 0;
210 $dual = isdual($foo); # true
211 The $! variable is commonly dual-valued, though it is also magical in
213 other ways:
214 $! = 1;
216 $dual = isdual($!); # true
217 print("$!\n"); # "Operation not permitted"
218 CAUTION: This function is not as useful as it may seem. Dualvars are
220 not a distinct concept in Perl, but a standard internal construct of
221 all scalar values. Almost any value could be considered as a dualvar by
222 this function through the course of normal operations.
223 isvstring
225 my $vstring = isvstring( $var );
226 If $var is a scalar which was coded as a vstring, the result is true.
228 $vs = v49.46.48;
230 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
231 printf($fmt,$vs);
232 looks_like_number
234 my $isnum = looks_like_number( $var );
235 Returns true if perl thinks $var is a number. See "looks_like_number"
237 in perlapi.
238 openhandle
240 my $fh = openhandle( $fh );
241 Returns $fh itself, if $fh may be used as a filehandle and is open, or
243 if it is a tied handle. Otherwise "undef" is returned.
244 $fh = openhandle(*STDIN); # \*STDIN
246 $fh = openhandle(\*STDIN); # \*STDIN
247 $fh = openhandle(*NOTOPEN); # undef
248 $fh = openhandle("scalar"); # undef
249 readonly
251 my $ro = readonly( $var );
252 Returns true if $var is readonly.
254 sub foo { readonly($_[0]) }
256 $readonly = foo($bar); # false
258 $readonly = foo(0); # true
259 set_prototype
261 my $code = set_prototype( $code, $prototype );
262 Sets the prototype of the function given by the $code reference, or
264 deletes it if $prototype is "undef". Returns the $code reference
265 itself.
266 set_prototype \&foo, '$$';
268 tainted
270 my $t = tainted( $var );
271 Return true if $var is tainted.
273 $taint = tainted("constant"); # false
275 $taint = tainted($ENV{PWD}); # true if running under -T
276
278 Module use may give one of the following errors during import.
279 Vstrings are not implemented in this version of perl
281 The version of perl that you are using does not implement Vstrings,
282 to use "isvstring" you will need to use a newer release of perl.
283
285 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show
286 up as tests 8 and 9 of dualvar.t failing
287
289 List::Util
290
292 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
293 reserved. This program is free software; you can redistribute it
294 and/or modify it under the same terms as Perl itself.
295 Additionally "weaken" and "isweak" which are
297 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
299 This program is free software; you can redistribute it and/or modify it
300 under the same terms as perl itself.
301 Copyright (C) 2004, 2008 Matthijs van Duin. All rights reserved.
303 Copyright (C) 2014 cPanel Inc. All rights reserved. This program is
304 free software; you can redistribute it and/or modify it under the same
305 terms as Perl itself.
306perl v5.38.0 2023-07-21 Scalar::Util(3)