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 so small such that being individual extensions would be wasteful.
19 By default "Scalar::Util" does not export any subroutines. The
21 subroutines defined are
22 blessed EXPR
24 If EXPR evaluates to a blessed reference the name of the package
25 that it is blessed into is returned. Otherwise "undef" is returned.
26 $scalar = "foo";
28 $class = blessed $scalar; # undef
29 $ref = [];
31 $class = blessed $ref; # undef
32 $obj = bless [], "Foo";
34 $class = blessed $obj; # "Foo"
35 dualvar NUM, STRING
37 Returns a scalar that has the value NUM in a numeric context and
38 the value STRING in a string context.
39 $foo = dualvar 10, "Hello";
41 $num = $foo + 2; # 12
42 $str = $foo . " world"; # Hello world
43 isdual EXPR
45 If EXPR is a scalar that is a dualvar, the result is true.
46 $foo = dualvar 86, "Nix";
48 $dual = isdual($foo); # true
49 Note that a scalar can be made to have both string and numeric
51 content through numeric operations:
52 $foo = "10";
54 $dual = isdual($foo); # false
55 $bar = $foo + 0;
56 $dual = isdual($foo); # true
57 Note that although $! appears to be dual-valued variable, it is
59 actually implemented using a tied scalar:
60 $! = 1;
62 print("$!\n"); # "Operation not permitted"
63 $dual = isdual($!); # false
64 You can capture its numeric and string content using:
66 $err = dualvar $!, $!;
68 $dual = isdual($err); # true
69 isvstring EXPR
71 If EXPR is a scalar which was coded as a vstring the result is
72 true.
73 $vs = v49.46.48;
75 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
76 printf($fmt,$vs);
77 looks_like_number EXPR
79 Returns true if perl thinks EXPR is a number. See
80 "looks_like_number" in perlapi.
81 openhandle FH
83 Returns FH if FH may be used as a filehandle and is open, or FH is
84 a tied handle. Otherwise "undef" is returned.
85 $fh = openhandle(*STDIN); # \*STDIN
87 $fh = openhandle(\*STDIN); # \*STDIN
88 $fh = openhandle(*NOTOPEN); # undef
89 $fh = openhandle("scalar"); # undef
90 readonly SCALAR
92 Returns true if SCALAR is readonly.
93 sub foo { readonly($_[0]) }
95 $readonly = foo($bar); # false
97 $readonly = foo(0); # true
98 refaddr EXPR
100 If EXPR evaluates to a reference the internal memory address of the
101 referenced value is returned. Otherwise "undef" is returned.
102 $addr = refaddr "string"; # undef
104 $addr = refaddr \$var; # eg 12345678
105 $addr = refaddr []; # eg 23456784
106 $obj = bless {}, "Foo";
108 $addr = refaddr $obj; # eg 88123488
109 reftype EXPR
111 If EXPR evaluates to a reference the type of the variable
112 referenced is returned. Otherwise "undef" is returned.
113 $type = reftype "string"; # undef
115 $type = reftype \$var; # SCALAR
116 $type = reftype []; # ARRAY
117 $obj = bless {}, "Foo";
119 $type = reftype $obj; # HASH
120 set_prototype CODEREF, PROTOTYPE
122 Sets the prototype of the given function, or deletes it if
123 PROTOTYPE is undef. Returns the CODEREF.
124 set_prototype \&foo, '$$';
126 tainted EXPR
128 Return true if the result of EXPR is tainted
129 $taint = tainted("constant"); # false
131 $taint = tainted($ENV{PWD}); # true if running under -T
132 weaken REF
134 REF will be turned into a weak reference. This means that it will
135 not hold a reference count on the object it references. Also when
136 the reference count on that object reaches zero, REF will be set to
137 undef.
138 This is useful for keeping copies of references , but you don't
140 want to prevent the object being DESTROY-ed at its usual time.
141 {
143 my $var;
144 $ref = \$var;
145 weaken($ref); # Make $ref a weak reference
146 }
147 # $ref is now undef
148 Note that if you take a copy of a scalar with a weakened reference,
150 the copy will be a strong reference.
151 my $var;
153 my $foo = \$var;
154 weaken($foo); # Make $foo a weak reference
155 my $bar = $foo; # $bar is now a strong reference
156 This may be less obvious in other situations, such as "grep()", for
158 instance when grepping through a list of weakened references to
159 objects that may have been destroyed already:
160 @object = grep { defined } @object;
162 This will indeed remove all references to destroyed objects, but
164 the remaining references to objects will be strong, causing the
165 remaining objects to never be destroyed because there is now always
166 a strong reference to them in the @object array.
167 isweak EXPR
169 If EXPR is a scalar which is a weak reference the result is true.
170 $ref = \$foo;
172 $weak = isweak($ref); # false
173 weaken($ref);
174 $weak = isweak($ref); # true
175 NOTE: Copying a weak reference creates a normal, strong, reference.
177 $copy = $ref;
179 $weak = isweak($copy); # false
180
182 Module use may give one of the following errors during import.
183 Weak references are not implemented in the version of perl
185 The version of perl that you are using does not implement weak
186 references, to use "isweak" or "weaken" you will need to use a
187 newer release of perl.
188 Vstrings are not implemented in the version of perl
190 The version of perl that you are using does not implement Vstrings,
191 to use "isvstring" you will need to use a newer release of perl.
192 "NAME" is only available with the XS version of Scalar::Util
194 "Scalar::Util" contains both perl and C implementations of many of
195 its functions so that those without access to a C compiler may
196 still use it. However some of the functions are only available when
197 a C compiler was available to compile the XS version of the
198 extension.
199 At present that list is: weaken, isweak, dualvar, isvstring,
201 set_prototype
202
204 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show
205 up as tests 8 and 9 of dualvar.t failing
206
208 List::Util
209
211 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
212 reserved. This program is free software; you can redistribute it
213 and/or modify it under the same terms as Perl itself.
214 Except weaken and isweak which are
216 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
218 This program is free software; you can redistribute it and/or modify it
219 under the same terms as perl itself.
220perl v5.16.3 2012-12-27 Scalar::Util(3)