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