1 # Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
2 # This program is free software; you can redistribute it and/or
3 # modify it under the same terms as Perl itself.
5 # Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
13 our @ISA = qw(Exporter);
15 blessed refaddr reftype weaken unweaken isweak
17 dualvar isdual isvstring looks_like_number openhandle readonly set_prototype
20 our $VERSION = "1.63";
23 require List::Util; # List::Util loads the XS
24 List::Util->VERSION( $VERSION ); # Ensure we got the right XS version (RT#100863)
26 # populating @EXPORT_FAIL is done in the XS code
28 if (grep { /^isvstring$/ } @_ ) {
30 Carp::croak("Vstrings are not implemented in this version of perl");
36 # set_prototype has been moved to Sub::Util with a different interface
39 my ( $code, $proto ) = @_;
40 return Sub::Util::set_prototype( $proto, $code );
49 Scalar::Util - A selection of general-utility scalar subroutines
53 use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
54 tainted weaken isweak isvstring looks_like_number
56 # and other useful utils appearing below
60 C<Scalar::Util> contains a selection of subroutines that people have expressed
61 would be nice to have in the perl core, but the usage would not really be high
62 enough to warrant the use of a keyword, and the size would be so small that
63 being individual extensions would be wasteful.
65 By default C<Scalar::Util> does not export any subroutines.
67 =head2 Core Perl C<builtin> Functions
69 Many functions in this module have served as the inspiration for a new
70 experimental facility in recent versions of Perl. From various development
71 versions, starting at 5.35.7, equivalent functions to many of these utilities
72 are available in the C<builtin::> package.
74 use Scalar::Util qw(blessed);
76 $class = blessed $obj;
78 $class = builtin::blessed $obj; # equivalent
80 For more information, see the documentation on L<builtin>.
84 =head1 FUNCTIONS FOR REFERENCES
86 The following functions all perform some useful activity on reference values.
90 my $pkg = blessed( $ref );
92 If C<$ref> is a blessed reference, the name of the package that it is blessed
93 into is returned. Otherwise C<undef> is returned.
96 $class = blessed $scalar; # undef
99 $class = blessed $ref; # undef
101 $obj = bless [], "Foo";
102 $class = blessed $obj; # "Foo"
104 Take care when using this function simply as a truth test (such as in
105 C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
107 I<Since Perl version 5.35.7> an equivalent function is available as
112 my $addr = refaddr( $ref );
114 If C<$ref> is reference, the internal memory address of the referenced value is
115 returned as a plain integer. Otherwise C<undef> is returned.
117 $addr = refaddr "string"; # undef
118 $addr = refaddr \$var; # eg 12345678
119 $addr = refaddr []; # eg 23456784
121 $obj = bless {}, "Foo";
122 $addr = refaddr $obj; # eg 88123488
124 I<Since Perl version 5.35.7> an equivalent function is available as
129 my $type = reftype( $ref );
131 If C<$ref> is a reference, the basic Perl type of the variable referenced is
132 returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
135 $type = reftype "string"; # undef
136 $type = reftype \$var; # SCALAR
137 $type = reftype []; # ARRAY
139 $obj = bless {}, "Foo";
140 $type = reftype $obj; # HASH
142 Note that for internal reasons, all precompiled regexps (C<qr/.../>) are
143 blessed references; thus C<ref()> returns the package name string C<"Regexp">
144 on these but C<reftype()> will return the underlying C structure type of
145 C<"REGEXP"> in all capitals.
147 I<Since Perl version 5.35.7> an equivalent function is available as
154 The lvalue C<$ref> will be turned into a weak reference. This means that it
155 will not hold a reference count on the object it references. Also, when the
156 reference count on that object reaches zero, the reference will be set to
157 undef. This function mutates the lvalue passed as its argument and returns no
160 This is useful for keeping copies of references, but you don't want to prevent
161 the object being DESTROY-ed at its usual time.
166 weaken($ref); # Make $ref a weak reference
170 Note that if you take a copy of a scalar with a weakened reference, the copy
171 will be a strong reference.
175 weaken($foo); # Make $foo a weak reference
176 my $bar = $foo; # $bar is now a strong reference
178 This may be less obvious in other situations, such as C<grep()>, for instance
179 when grepping through a list of weakened references to objects that may have
180 been destroyed already:
182 @object = grep { defined } @object;
184 This will indeed remove all references to destroyed objects, but the remaining
185 references to objects will be strong, causing the remaining objects to never be
186 destroyed because there is now always a strong reference to them in the @object
189 I<Since Perl version 5.35.7> an equivalent function is available as
196 I<Since version 1.36.>
198 The lvalue C<REF> will be turned from a weak reference back into a normal
199 (strong) reference again. This function mutates the lvalue passed as its
200 argument and returns no value. This undoes the action performed by
203 This function is slightly neater and more convenient than the
204 otherwise-equivalent code
210 (because in particular, simply assigning a weak reference back to itself does
211 not work to unweaken it; C<$REF = $REF> does not work).
213 I<Since Perl version 5.35.7> an equivalent function is available as
214 C<builtin::unweaken>.
218 my $weak = isweak( $ref );
220 Returns true if C<$ref> is a weak reference.
223 $weak = isweak($ref); # false
225 $weak = isweak($ref); # true
227 B<NOTE>: Copying a weak reference creates a normal, strong, reference.
230 $weak = isweak($copy); # false
232 I<Since Perl version 5.35.7> an equivalent function is available as
235 =head1 OTHER FUNCTIONS
239 my $var = dualvar( $num, $string );
241 Returns a scalar that has the value C<$num> in a numeric context and the value
242 C<$string> in a string context.
244 $foo = dualvar 10, "Hello";
245 $num = $foo + 2; # 12
246 $str = $foo . " world"; # Hello world
250 my $dual = isdual( $var );
252 I<Since version 1.26.>
254 If C<$var> is a scalar that has both numeric and string values, the result is
257 $foo = dualvar 86, "Nix";
258 $dual = isdual($foo); # true
260 Note that a scalar can be made to have both string and numeric content through
264 $dual = isdual($foo); # false
266 $dual = isdual($foo); # true
268 The C<$!> variable is commonly dual-valued, though it is also magical in other
272 $dual = isdual($!); # true
273 print("$!\n"); # "Operation not permitted"
275 B<CAUTION>: This function is not as useful as it may seem. Dualvars are not a
276 distinct concept in Perl, but a standard internal construct of all scalar
277 values. Almost any value could be considered as a dualvar by this function
278 through the course of normal operations.
282 my $vstring = isvstring( $var );
284 If C<$var> is a scalar which was coded as a vstring, the result is true.
287 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
290 =head2 looks_like_number
292 my $isnum = looks_like_number( $var );
294 Returns true if perl thinks C<$var> is a number. See
295 L<perlapi/looks_like_number>.
299 my $fh = openhandle( $fh );
301 Returns C<$fh> itself, if C<$fh> may be used as a filehandle and is open, or if
302 it is a tied handle. Otherwise C<undef> is returned.
304 $fh = openhandle(*STDIN); # \*STDIN
305 $fh = openhandle(\*STDIN); # \*STDIN
306 $fh = openhandle(*NOTOPEN); # undef
307 $fh = openhandle("scalar"); # undef
311 my $ro = readonly( $var );
313 Returns true if C<$var> is readonly.
315 sub foo { readonly($_[0]) }
317 $readonly = foo($bar); # false
318 $readonly = foo(0); # true
322 my $code = set_prototype( $code, $prototype );
324 Sets the prototype of the function given by the C<$code> reference, or deletes
325 it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
327 set_prototype \&foo, '$$';
331 my $t = tainted( $var );
333 Return true if C<$var> is tainted.
335 $taint = tainted("constant"); # false
336 $taint = tainted($ENV{PWD}); # true if running under -T
340 Module use may give one of the following errors during import.
344 =item Vstrings are not implemented in this version of perl
346 The version of perl that you are using does not implement Vstrings, to use
347 L</isvstring> you will need to use a newer release of perl.
353 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
354 show up as tests 8 and 9 of dualvar.t failing
362 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
363 This program is free software; you can redistribute it and/or modify it
364 under the same terms as Perl itself.
366 Additionally L</weaken> and L</isweak> which are
368 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
369 This program is free software; you can redistribute it and/or modify it
370 under the same terms as perl itself.
372 Copyright (C) 2004, 2008 Matthijs van Duin. All rights reserved.
373 Copyright (C) 2014 cPanel Inc. All rights reserved.
374 This program is free software; you can redistribute it and/or modify
375 it under the same terms as Perl itself.