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 weaken
73 weaken( $ref );
74 The lvalue $ref will be turned into a weak reference. This means that
76 it will not hold a reference count on the object it references. Also,
77 when the reference count on that object reaches zero, the reference
78 will be set to undef. This function mutates the lvalue passed as its
79 argument and returns no value.
80 This is useful for keeping copies of references, but you don't want to
82 prevent the object being DESTROY-ed at its usual time.
83 {
85 my $var;
86 $ref = \$var;
87 weaken($ref); # Make $ref a weak reference
88 }
89 # $ref is now undef
90 Note that if you take a copy of a scalar with a weakened reference, the
92 copy will be a strong reference.
93 my $var;
95 my $foo = \$var;
96 weaken($foo); # Make $foo a weak reference
97 my $bar = $foo; # $bar is now a strong reference
98 This may be less obvious in other situations, such as "grep()", for
100 instance when grepping through a list of weakened references to objects
101 that may have been destroyed already:
102 @object = grep { defined } @object;
104 This will indeed remove all references to destroyed objects, but the
106 remaining references to objects will be strong, causing the remaining
107 objects to never be destroyed because there is now always a strong
108 reference to them in the @object array.
109 unweaken
111 unweaken( $ref );
112 Since version 1.36.
114 The lvalue "REF" will be turned from a weak reference back into a
116 normal (strong) reference again. This function mutates the lvalue
117 passed as its argument and returns no value. This undoes the action
118 performed by "weaken".
119 This function is slightly neater and more convenient than the
121 otherwise-equivalent code
122 my $tmp = $REF;
124 undef $REF;
125 $REF = $tmp;
126 (because in particular, simply assigning a weak reference back to
128 itself does not work to unweaken it; "$REF = $REF" does not work).
129 isweak
131 my $weak = isweak( $ref );
132 Returns true if $ref is a weak reference.
134 $ref = \$foo;
136 $weak = isweak($ref); # false
137 weaken($ref);
138 $weak = isweak($ref); # true
139 NOTE: Copying a weak reference creates a normal, strong, reference.
141 $copy = $ref;
143 $weak = isweak($copy); # false
144
146 dualvar
147 my $var = dualvar( $num, $string );
148 Returns a scalar that has the value $num in a numeric context and the
150 value $string in a string context.
151 $foo = dualvar 10, "Hello";
153 $num = $foo + 2; # 12
154 $str = $foo . " world"; # Hello world
155 isdual
157 my $dual = isdual( $var );
158 Since version 1.26.
160 If $var is a scalar that has both numeric and string values, the result
162 is true.
163 $foo = dualvar 86, "Nix";
165 $dual = isdual($foo); # true
166 Note that a scalar can be made to have both string and numeric content
168 through numeric operations:
169 $foo = "10";
171 $dual = isdual($foo); # false
172 $bar = $foo + 0;
173 $dual = isdual($foo); # true
174 Note that although $! appears to be a dual-valued variable, it is
176 actually implemented as a magical variable inside the interpreter:
177 $! = 1;
179 print("$!\n"); # "Operation not permitted"
180 $dual = isdual($!); # false
181 You can capture its numeric and string content using:
183 $err = dualvar $!, $!;
185 $dual = isdual($err); # true
186 isvstring
188 my $vstring = isvstring( $var );
189 If $var is a scalar which was coded as a vstring, the result is true.
191 $vs = v49.46.48;
193 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
194 printf($fmt,$vs);
195 looks_like_number
197 my $isnum = looks_like_number( $var );
198 Returns true if perl thinks $var is a number. See "looks_like_number"
200 in perlapi.
201 openhandle
203 my $fh = openhandle( $fh );
204 Returns $fh itself if $fh may be used as a filehandle and is open, or
206 is is a tied handle. Otherwise "undef" is returned.
207 $fh = openhandle(*STDIN); # \*STDIN
209 $fh = openhandle(\*STDIN); # \*STDIN
210 $fh = openhandle(*NOTOPEN); # undef
211 $fh = openhandle("scalar"); # undef
212 readonly
214 my $ro = readonly( $var );
215 Returns true if $var is readonly.
217 sub foo { readonly($_[0]) }
219 $readonly = foo($bar); # false
221 $readonly = foo(0); # true
222 set_prototype
224 my $code = set_prototype( $code, $prototype );
225 Sets the prototype of the function given by the $code reference, or
227 deletes it if $prototype is "undef". Returns the $code reference
228 itself.
229 set_prototype \&foo, '$$';
231 tainted
233 my $t = tainted( $var );
234 Return true if $var is tainted.
236 $taint = tainted("constant"); # false
238 $taint = tainted($ENV{PWD}); # true if running under -T
239
241 Module use may give one of the following errors during import.
242 Weak references are not implemented in the version of perl
244 The version of perl that you are using does not implement weak
245 references, to use "isweak" or "weaken" you will need to use a
246 newer release of perl.
247 Vstrings are not implemented in the version of perl
249 The version of perl that you are using does not implement Vstrings,
250 to use "isvstring" you will need to use a newer release of perl.
251
253 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show
254 up as tests 8 and 9 of dualvar.t failing
255
257 List::Util
258
260 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
261 reserved. This program is free software; you can redistribute it
262 and/or modify it under the same terms as Perl itself.
263 Additionally "weaken" and "isweak" which are
265 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
267 This program is free software; you can redistribute it and/or modify it
268 under the same terms as perl itself.
269 Copyright (C) 2004, 2008 Matthijs van Duin. All rights reserved.
271 Copyright (C) 2014 cPanel Inc. All rights reserved. This program is
272 free software; you can redistribute it and/or modify it under the same
273 terms as Perl itself.
274perl v5.28.0 2018-02-20 Scalar::Util(3)