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