This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
officially support Visual C++ 2022
[perl5.git] / cpan / Scalar-List-Utils / lib / Scalar / Util.pm
CommitLineData
2ff28616 1# Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
2# This program is free software; you can redistribute it and/or
3# modify it under the same terms as Perl itself.
e99e4210
SH
4#
5# Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
f4a2945e
JH
6
7package Scalar::Util;
8
4984adac 9use strict;
e8164ee7 10use warnings;
f4a2945e 11require Exporter;
f4a2945e 12
3630f57e 13our @ISA = qw(Exporter);
8b198969 14our @EXPORT_OK = qw(
8c167fd9
CBW
15 blessed refaddr reftype weaken unweaken isweak
16
d81c2d6a
CBW
17 dualvar isdual isvstring looks_like_number openhandle readonly set_prototype
18 tainted
8b198969 19);
741719f1 20our $VERSION = "1.60";
2ad8e1fa 21$VERSION =~ tr/_//d;
09c2a9b8 22
3d58dd24
SH
23require List::Util; # List::Util loads the XS
24List::Util->VERSION( $VERSION ); # Ensure we got the right XS version (RT#100863)
25
741719f1 26# populating @EXPORT_FAIL is done in the XS code
09c2a9b8 27sub export_fail {
3630f57e 28 if (grep { /^isvstring$/ } @_ ) {
09c2a9b8 29 require Carp;
d0a5ecaa
PLE
30 Carp::croak("Vstrings are not implemented in this version of perl");
31 }
32
09c2a9b8
GB
33 @_;
34}
f4a2945e 35
d81c2d6a
CBW
36# set_prototype has been moved to Sub::Util with a different interface
37sub set_prototype(&$)
38{
39 my ( $code, $proto ) = @_;
40 return Sub::Util::set_prototype( $proto, $code );
41}
42
f4a2945e
JH
431;
44
45__END__
46
47=head1 NAME
48
49Scalar::Util - A selection of general-utility scalar subroutines
50
51=head1 SYNOPSIS
52
8b198969
CBW
53 use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
54 tainted weaken isweak isvstring looks_like_number
55 set_prototype);
2ff28616 56 # and other useful utils appearing below
f4a2945e
JH
57
58=head1 DESCRIPTION
59
8c167fd9
CBW
60C<Scalar::Util> contains a selection of subroutines that people have expressed
61would be nice to have in the perl core, but the usage would not really be high
e8164ee7
JH
62enough to warrant the use of a keyword, and the size would be so small that
63being individual extensions would be wasteful.
8c167fd9
CBW
64
65By default C<Scalar::Util> does not export any subroutines.
66
67=cut
68
69=head1 FUNCTIONS FOR REFERENCES
f4a2945e 70
8c167fd9 71The following functions all perform some useful activity on reference values.
f4a2945e 72
d81c2d6a
CBW
73=head2 blessed
74
75 my $pkg = blessed( $ref );
f4a2945e 76
e8164ee7 77If C<$ref> is a blessed reference, the name of the package that it is blessed
8c167fd9 78into is returned. Otherwise C<undef> is returned.
f4a2945e 79
8c167fd9
CBW
80 $scalar = "foo";
81 $class = blessed $scalar; # undef
c29e891d 82
8c167fd9
CBW
83 $ref = [];
84 $class = blessed $ref; # undef
c29e891d 85
8c167fd9
CBW
86 $obj = bless [], "Foo";
87 $class = blessed $obj; # "Foo"
c29e891d 88
ad434879 89Take care when using this function simply as a truth test (such as in
8c167fd9
CBW
90C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
91
d81c2d6a
CBW
92=head2 refaddr
93
94 my $addr = refaddr( $ref );
8c167fd9 95
e8164ee7 96If C<$ref> is reference, the internal memory address of the referenced value is
8c167fd9
CBW
97returned as a plain integer. Otherwise C<undef> is returned.
98
99 $addr = refaddr "string"; # undef
100 $addr = refaddr \$var; # eg 12345678
101 $addr = refaddr []; # eg 23456784
102
103 $obj = bless {}, "Foo";
104 $addr = refaddr $obj; # eg 88123488
105
d81c2d6a
CBW
106=head2 reftype
107
108 my $type = reftype( $ref );
8c167fd9 109
e8164ee7 110If C<$ref> is a reference, the basic Perl type of the variable referenced is
8c167fd9
CBW
111returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
112is returned.
113
114 $type = reftype "string"; # undef
115 $type = reftype \$var; # SCALAR
116 $type = reftype []; # ARRAY
117
118 $obj = bless {}, "Foo";
119 $type = reftype $obj; # HASH
120
cac6698e
S
121Note that for internal reasons, all precompiled regexps (C<qr/.../>) are
122blessed references; thus C<ref()> returns the package name string C<"Regexp">
123on these but C<reftype()> will return the underlying C structure type of
124C<"REGEXP"> in all capitals.
125
d81c2d6a 126=head2 weaken
8c167fd9 127
d81c2d6a
CBW
128 weaken( $ref );
129
130The lvalue C<$ref> will be turned into a weak reference. This means that it
e8164ee7 131will not hold a reference count on the object it references. Also, when the
8c167fd9
CBW
132reference count on that object reaches zero, the reference will be set to
133undef. This function mutates the lvalue passed as its argument and returns no
134value.
135
136This is useful for keeping copies of references, but you don't want to prevent
137the object being DESTROY-ed at its usual time.
138
139 {
140 my $var;
141 $ref = \$var;
142 weaken($ref); # Make $ref a weak reference
143 }
144 # $ref is now undef
145
146Note that if you take a copy of a scalar with a weakened reference, the copy
147will be a strong reference.
148
149 my $var;
150 my $foo = \$var;
151 weaken($foo); # Make $foo a weak reference
152 my $bar = $foo; # $bar is now a strong reference
153
154This may be less obvious in other situations, such as C<grep()>, for instance
155when grepping through a list of weakened references to objects that may have
156been destroyed already:
157
158 @object = grep { defined } @object;
159
160This will indeed remove all references to destroyed objects, but the remaining
161references to objects will be strong, causing the remaining objects to never be
162destroyed because there is now always a strong reference to them in the @object
163array.
164
d81c2d6a
CBW
165=head2 unweaken
166
167 unweaken( $ref );
8c167fd9 168
b823713c
CBW
169I<Since version 1.36.>
170
8c167fd9
CBW
171The lvalue C<REF> will be turned from a weak reference back into a normal
172(strong) reference again. This function mutates the lvalue passed as its
173argument and returns no value. This undoes the action performed by
d81c2d6a 174L</weaken>.
8c167fd9
CBW
175
176This function is slightly neater and more convenient than the
177otherwise-equivalent code
178
179 my $tmp = $REF;
180 undef $REF;
181 $REF = $tmp;
182
183(because in particular, simply assigning a weak reference back to itself does
184not work to unweaken it; C<$REF = $REF> does not work).
185
d81c2d6a
CBW
186=head2 isweak
187
188 my $weak = isweak( $ref );
8c167fd9
CBW
189
190Returns true if C<$ref> is a weak reference.
191
192 $ref = \$foo;
193 $weak = isweak($ref); # false
194 weaken($ref);
195 $weak = isweak($ref); # true
ad434879 196
8c167fd9
CBW
197B<NOTE>: Copying a weak reference creates a normal, strong, reference.
198
199 $copy = $ref;
200 $weak = isweak($copy); # false
f4a2945e 201
8c167fd9
CBW
202=head1 OTHER FUNCTIONS
203
d81c2d6a
CBW
204=head2 dualvar
205
206 my $var = dualvar( $num, $string );
8c167fd9
CBW
207
208Returns a scalar that has the value C<$num> in a numeric context and the value
209C<$string> in a string context.
f4a2945e
JH
210
211 $foo = dualvar 10, "Hello";
c29e891d
GB
212 $num = $foo + 2; # 12
213 $str = $foo . " world"; # Hello world
f4a2945e 214
d81c2d6a
CBW
215=head2 isdual
216
217 my $dual = isdual( $var );
60f3865b 218
b823713c
CBW
219I<Since version 1.26.>
220
8c167fd9
CBW
221If C<$var> is a scalar that has both numeric and string values, the result is
222true.
60f3865b 223
8b198969
CBW
224 $foo = dualvar 86, "Nix";
225 $dual = isdual($foo); # true
60f3865b 226
8c167fd9 227Note that a scalar can be made to have both string and numeric content through
741719f1 228standard operations:
f4a2945e 229
8b198969
CBW
230 $foo = "10";
231 $dual = isdual($foo); # false
232 $bar = $foo + 0;
233 $dual = isdual($foo); # true
f4a2945e 234
741719f1
LT
235The C<$!> variable is commonly dual-valued, though it is also magical in other
236ways:
c29e891d 237
8b198969 238 $! = 1;
741719f1 239 $dual = isdual($!); # true
8b198969 240 print("$!\n"); # "Operation not permitted"
4984adac 241
741719f1
LT
242B<CAUTION>: This function is not as useful as it may seem. Dualvars are not a
243distinct concept in Perl, but a standard internal construct of all scalar
244values. Almost any value could be considered as a dualvar by this function
245through the course of normal operations.
8b198969 246
d81c2d6a
CBW
247=head2 isvstring
248
249 my $vstring = isvstring( $var );
8b198969 250
e8164ee7 251If C<$var> is a scalar which was coded as a vstring, the result is true.
8b198969
CBW
252
253 $vs = v49.46.48;
254 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
255 printf($fmt,$vs);
4984adac 256
d81c2d6a
CBW
257=head2 looks_like_number
258
259 my $isnum = looks_like_number( $var );
9e7deb6c 260
8c167fd9 261Returns true if perl thinks C<$var> is a number. See
9e7deb6c
GB
262L<perlapi/looks_like_number>.
263
d81c2d6a
CBW
264=head2 openhandle
265
266 my $fh = openhandle( $fh );
c0f790df 267
2ad8e1fa
MM
268Returns C<$fh> itself, if C<$fh> may be used as a filehandle and is open, or if
269it is a tied handle. Otherwise C<undef> is returned.
c0f790df 270
8b198969
CBW
271 $fh = openhandle(*STDIN); # \*STDIN
272 $fh = openhandle(\*STDIN); # \*STDIN
273 $fh = openhandle(*NOTOPEN); # undef
274 $fh = openhandle("scalar"); # undef
275
d81c2d6a
CBW
276=head2 readonly
277
278 my $ro = readonly( $var );
ee4ffb48 279
8c167fd9 280Returns true if C<$var> is readonly.
ee4ffb48 281
c29e891d
GB
282 sub foo { readonly($_[0]) }
283
284 $readonly = foo($bar); # false
285 $readonly = foo(0); # true
286
d81c2d6a
CBW
287=head2 set_prototype
288
289 my $code = set_prototype( $code, $prototype );
f4a2945e 290
8c167fd9
CBW
291Sets the prototype of the function given by the C<$code> reference, or deletes
292it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
97605c51
GB
293
294 set_prototype \&foo, '$$';
295
d81c2d6a
CBW
296=head2 tainted
297
298 my $t = tainted( $var );
ee4ffb48 299
8c167fd9 300Return true if C<$var> is tainted.
ee4ffb48 301
c29e891d
GB
302 $taint = tainted("constant"); # false
303 $taint = tainted($ENV{PWD}); # true if running under -T
304
2ff28616
GB
305=head1 DIAGNOSTICS
306
307Module use may give one of the following errors during import.
308
309=over
310
d0a5ecaa 311=item Vstrings are not implemented in this version of perl
2ff28616
GB
312
313The version of perl that you are using does not implement Vstrings, to use
d81c2d6a 314L</isvstring> you will need to use a newer release of perl.
2ff28616 315
2ff28616
GB
316=back
317
9c3c560b
JH
318=head1 KNOWN BUGS
319
320There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
321show up as tests 8 and 9 of dualvar.t failing
322
ddf53ba4
GB
323=head1 SEE ALSO
324
325L<List::Util>
326
f4a2945e
JH
327=head1 COPYRIGHT
328
2ff28616 329Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
c29e891d 330This program is free software; you can redistribute it and/or modify it
f4a2945e
JH
331under the same terms as Perl itself.
332
d81c2d6a 333Additionally L</weaken> and L</isweak> which are
f4a2945e
JH
334
335Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
336This program is free software; you can redistribute it and/or modify it
337under the same terms as perl itself.
338
d81c2d6a
CBW
339Copyright (C) 2004, 2008 Matthijs van Duin. All rights reserved.
340Copyright (C) 2014 cPanel Inc. All rights reserved.
341This program is free software; you can redistribute it and/or modify
342it under the same terms as Perl itself.
343
f4a2945e 344=cut