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
23 The following functions all perform some useful activity on reference
24 values.
25 blessed
27 my $pkg = blessed( $ref );
28 If $ref is a blessed reference, the name of the package that it is
30 blessed into is returned. Otherwise "undef" is returned.
31 $scalar = "foo";
33 $class = blessed $scalar; # undef
34 $ref = [];
36 $class = blessed $ref; # undef
37 $obj = bless [], "Foo";
39 $class = blessed $obj; # "Foo"
40 Take care when using this function simply as a truth test (such as in
42 "if(blessed $ref)...") because the package name "0" is defined yet
43 false.
44 refaddr
46 my $addr = refaddr( $ref );
47 If $ref is reference, the internal memory address of the referenced
49 value is returned as a plain integer. Otherwise "undef" is returned.
50 $addr = refaddr "string"; # undef
52 $addr = refaddr \$var; # eg 12345678
53 $addr = refaddr []; # eg 23456784
54 $obj = bless {}, "Foo";
56 $addr = refaddr $obj; # eg 88123488
57 reftype
59 my $type = reftype( $ref );
60 If $ref is a reference, the basic Perl type of the variable referenced
62 is returned as a plain string (such as "ARRAY" or "HASH"). Otherwise
63 "undef" is returned.
64 $type = reftype "string"; # undef
66 $type = reftype \$var; # SCALAR
67 $type = reftype []; # ARRAY
68 $obj = bless {}, "Foo";
70 $type = reftype $obj; # HASH
71 Note that for internal reasons, all precompiled regexps ("qr/.../") are
73 blessed references; thus "ref()" returns the package name string
74 "Regexp" on these but "reftype()" will return the underlying C
75 structure type of "REGEXP" in all capitals.
76 weaken
78 weaken( $ref );
79 The lvalue $ref will be turned into a weak reference. This means that
81 it will not hold a reference count on the object it references. Also,
82 when the reference count on that object reaches zero, the reference
83 will be set to undef. This function mutates the lvalue passed as its
84 argument and returns no value.
85 This is useful for keeping copies of references, but you don't want to
87 prevent the object being DESTROY-ed at its usual time.
88 {
90 my $var;
91 $ref = \$var;
92 weaken($ref); # Make $ref a weak reference
93 }
94 # $ref is now undef
95 Note that if you take a copy of a scalar with a weakened reference, the
97 copy will be a strong reference.
98 my $var;
100 my $foo = \$var;
101 weaken($foo); # Make $foo a weak reference
102 my $bar = $foo; # $bar is now a strong reference
103 This may be less obvious in other situations, such as "grep()", for
105 instance when grepping through a list of weakened references to objects
106 that may have been destroyed already:
107 @object = grep { defined } @object;
109 This will indeed remove all references to destroyed objects, but the
111 remaining references to objects will be strong, causing the remaining
112 objects to never be destroyed because there is now always a strong
113 reference to them in the @object array.
114 unweaken
116 unweaken( $ref );
117 Since version 1.36.
119 The lvalue "REF" will be turned from a weak reference back into a
121 normal (strong) reference again. This function mutates the lvalue
122 passed as its argument and returns no value. This undoes the action
123 performed by "weaken".
124 This function is slightly neater and more convenient than the
126 otherwise-equivalent code
127 my $tmp = $REF;
129 undef $REF;
130 $REF = $tmp;
131 (because in particular, simply assigning a weak reference back to
133 itself does not work to unweaken it; "$REF = $REF" does not work).
134 isweak
136 my $weak = isweak( $ref );
137 Returns true if $ref is a weak reference.
139 $ref = \$foo;
141 $weak = isweak($ref); # false
142 weaken($ref);
143 $weak = isweak($ref); # true
144 NOTE: Copying a weak reference creates a normal, strong, reference.
146 $copy = $ref;
148 $weak = isweak($copy); # false
149
151 dualvar
152 my $var = dualvar( $num, $string );
153 Returns a scalar that has the value $num in a numeric context and the
155 value $string in a string context.
156 $foo = dualvar 10, "Hello";
158 $num = $foo + 2; # 12
159 $str = $foo . " world"; # Hello world
160 isdual
162 my $dual = isdual( $var );
163 Since version 1.26.
165 If $var is a scalar that has both numeric and string values, the result
167 is true.
168 $foo = dualvar 86, "Nix";
170 $dual = isdual($foo); # true
171 Note that a scalar can be made to have both string and numeric content
173 through numeric operations:
174 $foo = "10";
176 $dual = isdual($foo); # false
177 $bar = $foo + 0;
178 $dual = isdual($foo); # true
179 Note that although $! appears to be a dual-valued variable, it is
181 actually implemented as a magical variable inside the interpreter:
182 $! = 1;
184 print("$!\n"); # "Operation not permitted"
185 $dual = isdual($!); # false
186 You can capture its numeric and string content using:
188 $err = dualvar $!, $!;
190 $dual = isdual($err); # true
191 isvstring
193 my $vstring = isvstring( $var );
194 If $var is a scalar which was coded as a vstring, the result is true.
196 $vs = v49.46.48;
198 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
199 printf($fmt,$vs);
200 looks_like_number
202 my $isnum = looks_like_number( $var );
203 Returns true if perl thinks $var is a number. See "looks_like_number"
205 in perlapi.
206 openhandle
208 my $fh = openhandle( $fh );
209 Returns $fh itself, if $fh may be used as a filehandle and is open, or
211 if it is a tied handle. Otherwise "undef" is returned.
212 $fh = openhandle(*STDIN); # \*STDIN
214 $fh = openhandle(\*STDIN); # \*STDIN
215 $fh = openhandle(*NOTOPEN); # undef
216 $fh = openhandle("scalar"); # undef
217 readonly
219 my $ro = readonly( $var );
220 Returns true if $var is readonly.
222 sub foo { readonly($_[0]) }
224 $readonly = foo($bar); # false
226 $readonly = foo(0); # true
227 set_prototype
229 my $code = set_prototype( $code, $prototype );
230 Sets the prototype of the function given by the $code reference, or
232 deletes it if $prototype is "undef". Returns the $code reference
233 itself.
234 set_prototype \&foo, '$$';
236 tainted
238 my $t = tainted( $var );
239 Return true if $var is tainted.
241 $taint = tainted("constant"); # false
243 $taint = tainted($ENV{PWD}); # true if running under -T
244
246 Module use may give one of the following errors during import.
247 Weak references are not implemented in the version of perl
249 The version of perl that you are using does not implement weak
250 references, to use "isweak" or "weaken" you will need to use a
251 newer release of perl.
252 Vstrings are not implemented in the version of perl
254 The version of perl that you are using does not implement Vstrings,
255 to use "isvstring" you will need to use a newer release of perl.
256
258 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show
259 up as tests 8 and 9 of dualvar.t failing
260
262 List::Util
263
265 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
266 reserved. This program is free software; you can redistribute it
267 and/or modify it under the same terms as Perl itself.
268 Additionally "weaken" and "isweak" which are
270 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
272 This program is free software; you can redistribute it and/or modify it
273 under the same terms as perl itself.
274 Copyright (C) 2004, 2008 Matthijs van Duin. All rights reserved.
276 Copyright (C) 2014 cPanel Inc. All rights reserved. This program is
277 free software; you can redistribute it and/or modify it under the same
278 terms as Perl itself.
279perl v5.32.1 2021-04-01 Scalar::Util(3)