This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
t/29a_upcopy.t - under parallel builds allow more time for test
[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.63";
21 $VERSION =~ tr/_//d;
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 # populating @EXPORT_FAIL is done in the XS code
27 sub export_fail {
28   if (grep { /^isvstring$/ } @_ ) {
29     require Carp;
30     Carp::croak("Vstrings are not implemented in this version of perl");
31   }
32
33   @_;
34 }
35
36 # set_prototype has been moved to Sub::Util with a different interface
37 sub set_prototype(&$)
38 {
39   my ( $code, $proto ) = @_;
40   return Sub::Util::set_prototype( $proto, $code );
41 }
42
43 1;
44
45 __END__
46
47 =head1 NAME
48
49 Scalar::Util - A selection of general-utility scalar subroutines
50
51 =head1 SYNOPSIS
52
53     use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
54                         tainted weaken isweak isvstring looks_like_number
55                         set_prototype);
56                         # and other useful utils appearing below
57
58 =head1 DESCRIPTION
59
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.
64
65 By default C<Scalar::Util> does not export any subroutines.
66
67 =head2 Core Perl C<builtin> Functions
68
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.
73
74     use Scalar::Util qw(blessed);
75
76     $class = blessed $obj;
77
78     $class = builtin::blessed $obj;  # equivalent
79
80 For more information, see the documentation on L<builtin>.
81
82 =cut
83
84 =head1 FUNCTIONS FOR REFERENCES
85
86 The following functions all perform some useful activity on reference values.
87
88 =head2 blessed
89
90     my $pkg = blessed( $ref );
91
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.
94
95     $scalar = "foo";
96     $class  = blessed $scalar;           # undef
97
98     $ref    = [];
99     $class  = blessed $ref;              # undef
100
101     $obj    = bless [], "Foo";
102     $class  = blessed $obj;              # "Foo"
103
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.
106
107 I<Since Perl version 5.35.7> an equivalent function is available as
108 C<builtin::blessed>.
109
110 =head2 refaddr
111
112     my $addr = refaddr( $ref );
113
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.
116
117     $addr = refaddr "string";           # undef
118     $addr = refaddr \$var;              # eg 12345678
119     $addr = refaddr [];                 # eg 23456784
120
121     $obj  = bless {}, "Foo";
122     $addr = refaddr $obj;               # eg 88123488
123
124 I<Since Perl version 5.35.7> an equivalent function is available as
125 C<builtin::refaddr>.
126
127 =head2 reftype
128
129     my $type = reftype( $ref );
130
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>
133 is returned.
134
135     $type = reftype "string";           # undef
136     $type = reftype \$var;              # SCALAR
137     $type = reftype [];                 # ARRAY
138
139     $obj  = bless {}, "Foo";
140     $type = reftype $obj;               # HASH
141
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.
146
147 I<Since Perl version 5.35.7> an equivalent function is available as
148 C<builtin::reftype>.
149
150 =head2 weaken
151
152     weaken( $ref );
153
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
158 value.
159
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.
162
163     {
164       my $var;
165       $ref = \$var;
166       weaken($ref);                     # Make $ref a weak reference
167     }
168     # $ref is now undef
169
170 Note that if you take a copy of a scalar with a weakened reference, the copy
171 will be a strong reference.
172
173     my $var;
174     my $foo = \$var;
175     weaken($foo);                       # Make $foo a weak reference
176     my $bar = $foo;                     # $bar is now a strong reference
177
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:
181
182     @object = grep { defined } @object;
183
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
187 array.
188
189 I<Since Perl version 5.35.7> an equivalent function is available as
190 C<builtin::weaken>.
191
192 =head2 unweaken
193
194     unweaken( $ref );
195
196 I<Since version 1.36.>
197
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
201 L</weaken>.
202
203 This function is slightly neater and more convenient than the
204 otherwise-equivalent code
205
206     my $tmp = $REF;
207     undef $REF;
208     $REF = $tmp;
209
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).
212
213 I<Since Perl version 5.35.7> an equivalent function is available as
214 C<builtin::unweaken>.
215
216 =head2 isweak
217
218     my $weak = isweak( $ref );
219
220 Returns true if C<$ref> is a weak reference.
221
222     $ref  = \$foo;
223     $weak = isweak($ref);               # false
224     weaken($ref);
225     $weak = isweak($ref);               # true
226
227 B<NOTE>: Copying a weak reference creates a normal, strong, reference.
228
229     $copy = $ref;
230     $weak = isweak($copy);              # false
231
232 I<Since Perl version 5.35.7> an equivalent function is available as
233 C<builtin::is_weak>.
234
235 =head1 OTHER FUNCTIONS
236
237 =head2 dualvar
238
239     my $var = dualvar( $num, $string );
240
241 Returns a scalar that has the value C<$num> in a numeric context and the value
242 C<$string> in a string context.
243
244     $foo = dualvar 10, "Hello";
245     $num = $foo + 2;                    # 12
246     $str = $foo . " world";             # Hello world
247
248 =head2 isdual
249
250     my $dual = isdual( $var );
251
252 I<Since version 1.26.>
253
254 If C<$var> is a scalar that has both numeric and string values, the result is
255 true.
256
257     $foo = dualvar 86, "Nix";
258     $dual = isdual($foo);               # true
259
260 Note that a scalar can be made to have both string and numeric content through
261 standard operations:
262
263     $foo = "10";
264     $dual = isdual($foo);               # false
265     $bar = $foo + 0;
266     $dual = isdual($foo);               # true
267
268 The C<$!> variable is commonly dual-valued, though it is also magical in other
269 ways:
270
271     $! = 1;
272     $dual = isdual($!);                 # true
273     print("$!\n");                      # "Operation not permitted"
274
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.
279
280 =head2 isvstring
281
282     my $vstring = isvstring( $var );
283
284 If C<$var> is a scalar which was coded as a vstring, the result is true.
285
286     $vs   = v49.46.48;
287     $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
288     printf($fmt,$vs);
289
290 =head2 looks_like_number
291
292     my $isnum = looks_like_number( $var );
293
294 Returns true if perl thinks C<$var> is a number. See
295 L<perlapi/looks_like_number>.
296
297 =head2 openhandle
298
299     my $fh = openhandle( $fh );
300
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.
303
304     $fh = openhandle(*STDIN);           # \*STDIN
305     $fh = openhandle(\*STDIN);          # \*STDIN
306     $fh = openhandle(*NOTOPEN);         # undef
307     $fh = openhandle("scalar");         # undef
308
309 =head2 readonly
310
311     my $ro = readonly( $var );
312
313 Returns true if C<$var> is readonly.
314
315     sub foo { readonly($_[0]) }
316
317     $readonly = foo($bar);              # false
318     $readonly = foo(0);                 # true
319
320 =head2 set_prototype
321
322     my $code = set_prototype( $code, $prototype );
323
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.
326
327     set_prototype \&foo, '$$';
328
329 =head2 tainted
330
331     my $t = tainted( $var );
332
333 Return true if C<$var> is tainted.
334
335     $taint = tainted("constant");       # false
336     $taint = tainted($ENV{PWD});        # true if running under -T
337
338 =head1 DIAGNOSTICS
339
340 Module use may give one of the following errors during import.
341
342 =over
343
344 =item Vstrings are not implemented in this version of perl
345
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.
348
349 =back
350
351 =head1 KNOWN BUGS
352
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
355
356 =head1 SEE ALSO
357
358 L<List::Util>
359
360 =head1 COPYRIGHT
361
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.
365
366 Additionally L</weaken> and L</isweak> which are
367
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.
371
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.
376
377 =cut