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