This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
officially support Visual C++ 2022
[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.60";
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 =cut
68
69 =head1 FUNCTIONS FOR REFERENCES
70
71 The following functions all perform some useful activity on reference values.
72
73 =head2 blessed
74
75     my $pkg = blessed( $ref );
76
77 If C<$ref> is a blessed reference, the name of the package that it is blessed
78 into is returned. Otherwise C<undef> is returned.
79
80     $scalar = "foo";
81     $class  = blessed $scalar;           # undef
82
83     $ref    = [];
84     $class  = blessed $ref;              # undef
85
86     $obj    = bless [], "Foo";
87     $class  = blessed $obj;              # "Foo"
88
89 Take care when using this function simply as a truth test (such as in
90 C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
91
92 =head2 refaddr
93
94     my $addr = refaddr( $ref );
95
96 If C<$ref> is reference, the internal memory address of the referenced value is
97 returned as a plain integer. Otherwise C<undef> is returned.
98
99     $addr = refaddr "string";           # undef
100     $addr = refaddr \$var;              # eg 12345678
101     $addr = refaddr [];                 # eg 23456784
102
103     $obj  = bless {}, "Foo";
104     $addr = refaddr $obj;               # eg 88123488
105
106 =head2 reftype
107
108     my $type = reftype( $ref );
109
110 If C<$ref> is a reference, the basic Perl type of the variable referenced is
111 returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
112 is returned.
113
114     $type = reftype "string";           # undef
115     $type = reftype \$var;              # SCALAR
116     $type = reftype [];                 # ARRAY
117
118     $obj  = bless {}, "Foo";
119     $type = reftype $obj;               # HASH
120
121 Note that for internal reasons, all precompiled regexps (C<qr/.../>) are
122 blessed references; thus C<ref()> returns the package name string C<"Regexp">
123 on these but C<reftype()> will return the underlying C structure type of
124 C<"REGEXP"> in all capitals.
125
126 =head2 weaken
127
128     weaken( $ref );
129
130 The lvalue C<$ref> will be turned into a weak reference. This means that it
131 will not hold a reference count on the object it references. Also, when the
132 reference count on that object reaches zero, the reference will be set to
133 undef. This function mutates the lvalue passed as its argument and returns no
134 value.
135
136 This is useful for keeping copies of references, but you don't want to prevent
137 the object being DESTROY-ed at its usual time.
138
139     {
140       my $var;
141       $ref = \$var;
142       weaken($ref);                     # Make $ref a weak reference
143     }
144     # $ref is now undef
145
146 Note that if you take a copy of a scalar with a weakened reference, the copy
147 will be a strong reference.
148
149     my $var;
150     my $foo = \$var;
151     weaken($foo);                       # Make $foo a weak reference
152     my $bar = $foo;                     # $bar is now a strong reference
153
154 This may be less obvious in other situations, such as C<grep()>, for instance
155 when grepping through a list of weakened references to objects that may have
156 been destroyed already:
157
158     @object = grep { defined } @object;
159
160 This will indeed remove all references to destroyed objects, but the remaining
161 references to objects will be strong, causing the remaining objects to never be
162 destroyed because there is now always a strong reference to them in the @object
163 array.
164
165 =head2 unweaken
166
167     unweaken( $ref );
168
169 I<Since version 1.36.>
170
171 The lvalue C<REF> will be turned from a weak reference back into a normal
172 (strong) reference again. This function mutates the lvalue passed as its
173 argument and returns no value. This undoes the action performed by
174 L</weaken>.
175
176 This function is slightly neater and more convenient than the
177 otherwise-equivalent code
178
179     my $tmp = $REF;
180     undef $REF;
181     $REF = $tmp;
182
183 (because in particular, simply assigning a weak reference back to itself does
184 not work to unweaken it; C<$REF = $REF> does not work).
185
186 =head2 isweak
187
188     my $weak = isweak( $ref );
189
190 Returns true if C<$ref> is a weak reference.
191
192     $ref  = \$foo;
193     $weak = isweak($ref);               # false
194     weaken($ref);
195     $weak = isweak($ref);               # true
196
197 B<NOTE>: Copying a weak reference creates a normal, strong, reference.
198
199     $copy = $ref;
200     $weak = isweak($copy);              # false
201
202 =head1 OTHER FUNCTIONS
203
204 =head2 dualvar
205
206     my $var = dualvar( $num, $string );
207
208 Returns a scalar that has the value C<$num> in a numeric context and the value
209 C<$string> in a string context.
210
211     $foo = dualvar 10, "Hello";
212     $num = $foo + 2;                    # 12
213     $str = $foo . " world";             # Hello world
214
215 =head2 isdual
216
217     my $dual = isdual( $var );
218
219 I<Since version 1.26.>
220
221 If C<$var> is a scalar that has both numeric and string values, the result is
222 true.
223
224     $foo = dualvar 86, "Nix";
225     $dual = isdual($foo);               # true
226
227 Note that a scalar can be made to have both string and numeric content through
228 standard operations:
229
230     $foo = "10";
231     $dual = isdual($foo);               # false
232     $bar = $foo + 0;
233     $dual = isdual($foo);               # true
234
235 The C<$!> variable is commonly dual-valued, though it is also magical in other
236 ways:
237
238     $! = 1;
239     $dual = isdual($!);                 # true
240     print("$!\n");                      # "Operation not permitted"
241
242 B<CAUTION>: This function is not as useful as it may seem. Dualvars are not a
243 distinct concept in Perl, but a standard internal construct of all scalar
244 values. Almost any value could be considered as a dualvar by this function
245 through the course of normal operations.
246
247 =head2 isvstring
248
249     my $vstring = isvstring( $var );
250
251 If C<$var> is a scalar which was coded as a vstring, the result is true.
252
253     $vs   = v49.46.48;
254     $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
255     printf($fmt,$vs);
256
257 =head2 looks_like_number
258
259     my $isnum = looks_like_number( $var );
260
261 Returns true if perl thinks C<$var> is a number. See
262 L<perlapi/looks_like_number>.
263
264 =head2 openhandle
265
266     my $fh = openhandle( $fh );
267
268 Returns C<$fh> itself, if C<$fh> may be used as a filehandle and is open, or if
269 it is a tied handle. Otherwise C<undef> is returned.
270
271     $fh = openhandle(*STDIN);           # \*STDIN
272     $fh = openhandle(\*STDIN);          # \*STDIN
273     $fh = openhandle(*NOTOPEN);         # undef
274     $fh = openhandle("scalar");         # undef
275
276 =head2 readonly
277
278     my $ro = readonly( $var );
279
280 Returns true if C<$var> is readonly.
281
282     sub foo { readonly($_[0]) }
283
284     $readonly = foo($bar);              # false
285     $readonly = foo(0);                 # true
286
287 =head2 set_prototype
288
289     my $code = set_prototype( $code, $prototype );
290
291 Sets the prototype of the function given by the C<$code> reference, or deletes
292 it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
293
294     set_prototype \&foo, '$$';
295
296 =head2 tainted
297
298     my $t = tainted( $var );
299
300 Return true if C<$var> is tainted.
301
302     $taint = tainted("constant");       # false
303     $taint = tainted($ENV{PWD});        # true if running under -T
304
305 =head1 DIAGNOSTICS
306
307 Module use may give one of the following errors during import.
308
309 =over
310
311 =item Vstrings are not implemented in this version of perl
312
313 The version of perl that you are using does not implement Vstrings, to use
314 L</isvstring> you will need to use a newer release of perl.
315
316 =back
317
318 =head1 KNOWN BUGS
319
320 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
321 show up as tests 8 and 9 of dualvar.t failing
322
323 =head1 SEE ALSO
324
325 L<List::Util>
326
327 =head1 COPYRIGHT
328
329 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
330 This program is free software; you can redistribute it and/or modify it
331 under the same terms as Perl itself.
332
333 Additionally L</weaken> and L</isweak> which are
334
335 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
336 This program is free software; you can redistribute it and/or modify it
337 under the same terms as perl itself.
338
339 Copyright (C) 2004, 2008  Matthijs van Duin.  All rights reserved.
340 Copyright (C) 2014 cPanel Inc.  All rights reserved.
341 This program is free software; you can redistribute it and/or modify
342 it under the same terms as Perl itself.
343
344 =cut