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