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