1Scalar::Util(3pm) Perl Programmers Reference Guide Scalar::Util(3pm)
2
6 Scalar::Util - A selection of general-utility scalar subroutines
7
9 use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
10 weaken isvstring looks_like_number set_prototype);
11 # and other useful utils appearing below
12
14 "Scalar::Util" contains a selection of subroutines that people have
15 expressed would be nice to have in the perl core, but the usage would
16 not really be high enough to warrant the use of a keyword, and the size
17 so small such that being individual extensions would be wasteful.
18 By default "Scalar::Util" does not export any subroutines. The
20 subroutines defined are
21 blessed EXPR
23 If EXPR evaluates to a blessed reference the name of the package
24 that it is blessed into is returned. Otherwise "undef" is returned.
25 $scalar = "foo";
27 $class = blessed $scalar; # undef
28 $ref = [];
30 $class = blessed $ref; # undef
31 $obj = bless [], "Foo";
33 $class = blessed $obj; # "Foo"
34 dualvar NUM, STRING
36 Returns a scalar that has the value NUM in a numeric context and
37 the value STRING in a string context.
38 $foo = dualvar 10, "Hello";
40 $num = $foo + 2; # 12
41 $str = $foo . " world"; # Hello world
42 isvstring EXPR
44 If EXPR is a scalar which was coded as a vstring the result is
45 true.
46 $vs = v49.46.48;
48 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
49 printf($fmt,$vs);
50 isweak EXPR
52 If EXPR is a scalar which is a weak reference the result is true.
53 $ref = \$foo;
55 $weak = isweak($ref); # false
56 weaken($ref);
57 $weak = isweak($ref); # true
58 NOTE: Copying a weak reference creates a normal, strong, reference.
60 $copy = $ref;
62 $weak = isweak($copy); # false
63 looks_like_number EXPR
65 Returns true if perl thinks EXPR is a number. See
66 "looks_like_number" in perlapi.
67 openhandle FH
69 Returns FH if FH may be used as a filehandle and is open, or FH is
70 a tied handle. Otherwise "undef" is returned.
71 $fh = openhandle(*STDIN); # \*STDIN
73 $fh = openhandle(\*STDIN); # \*STDIN
74 $fh = openhandle(*NOTOPEN); # undef
75 $fh = openhandle("scalar"); # undef
76 readonly SCALAR
78 Returns true if SCALAR is readonly.
79 sub foo { readonly($_[0]) }
81 $readonly = foo($bar); # false
83 $readonly = foo(0); # true
84 refaddr EXPR
86 If EXPR evaluates to a reference the internal memory address of the
87 referenced value is returned. Otherwise "undef" is returned.
88 $addr = refaddr "string"; # undef
90 $addr = refaddr \$var; # eg 12345678
91 $addr = refaddr []; # eg 23456784
92 $obj = bless {}, "Foo";
94 $addr = refaddr $obj; # eg 88123488
95 reftype EXPR
97 If EXPR evaluates to a reference the type of the variable
98 referenced is returned. Otherwise "undef" is returned.
99 $type = reftype "string"; # undef
101 $type = reftype \$var; # SCALAR
102 $type = reftype []; # ARRAY
103 $obj = bless {}, "Foo";
105 $type = reftype $obj; # HASH
106 set_prototype CODEREF, PROTOTYPE
108 Sets the prototype of the given function, or deletes it if
109 PROTOTYPE is undef. Returns the CODEREF.
110 set_prototype \&foo, '$$';
112 tainted EXPR
114 Return true if the result of EXPR is tainted
115 $taint = tainted("constant"); # false
117 $taint = tainted($ENV{PWD}); # true if running under -T
118 weaken REF
120 REF will be turned into a weak reference. This means that it will
121 not hold a reference count on the object it references. Also when
122 the reference count on that object reaches zero, REF will be set to
123 undef.
124 This is useful for keeping copies of references , but you don't
126 want to prevent the object being DESTROY-ed at its usual time.
127 {
129 my $var;
130 $ref = \$var;
131 weaken($ref); # Make $ref a weak reference
132 }
133 # $ref is now undef
134 Note that if you take a copy of a scalar with a weakened reference,
136 the copy will be a strong reference.
137 my $var;
139 my $foo = \$var;
140 weaken($foo); # Make $foo a weak reference
141 my $bar = $foo; # $bar is now a strong reference
142 This may be less obvious in other situations, such as "grep()", for
144 instance when grepping through a list of weakened references to
145 objects that may have been destroyed already:
146 @object = grep { defined } @object;
148 This will indeed remove all references to destroyed objects, but
150 the remaining references to objects will be strong, causing the
151 remaining objects to never be destroyed because there is now always
152 a strong reference to them in the @object array.
153
155 Module use may give one of the following errors during import.
156 Weak references are not implemented in the version of perl
158 The version of perl that you are using does not implement weak
159 references, to use "isweak" or "weaken" you will need to use a
160 newer release of perl.
161 Vstrings are not implemented in the version of perl
163 The version of perl that you are using does not implement Vstrings,
164 to use "isvstring" you will need to use a newer release of perl.
165 "NAME" is only available with the XS version of Scalar::Util
167 "Scalar::Util" contains both perl and C implementations of many of
168 its functions so that those without access to a C compiler may
169 still use it. However some of the functions are only available when
170 a C compiler was available to compile the XS version of the
171 extension.
172 At present that list is: weaken, isweak, dualvar, isvstring,
174 set_prototype
175
177 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show
178 up as tests 8 and 9 of dualvar.t failing
179
181 List::Util
182
184 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
185 reserved. This program is free software; you can redistribute it
186 and/or modify it under the same terms as Perl itself.
187 Except weaken and isweak which are
189 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
191 This program is free software; you can redistribute it and/or modify it
192 under the same terms as perl itself.
193perl v5.10.1 2009-07-03 Scalar::Util(3pm)