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
7package Scalar::Util;
8
9use strict;
10use warnings;
11require Exporter;
12
13our @ISA       = qw(Exporter);
14our @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);
20our $VERSION    = "1.63";
21$VERSION =~ tr/_//d;
22
23require List::Util; # List::Util loads the XS
24List::Util->VERSION( $VERSION ); # Ensure we got the right XS version (RT#100863)
25
26# populating @EXPORT_FAIL is done in the XS code
27sub 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
37sub set_prototype(&$)
38{
39  my ( $code, $proto ) = @_;
40  return Sub::Util::set_prototype( $proto, $code );
41}
42
431;
44
45__END__
46
47=head1 NAME
48
49Scalar::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
60C<Scalar::Util> contains a selection of subroutines that people have expressed
61would be nice to have in the perl core, but the usage would not really be high
62enough to warrant the use of a keyword, and the size would be so small that
63being individual extensions would be wasteful.
64
65By default C<Scalar::Util> does not export any subroutines.
66
67=head2 Core Perl C<builtin> Functions
68
69Many functions in this module have served as the inspiration for a new
70experimental facility in recent versions of Perl. From various development
71versions, starting at 5.35.7, equivalent functions to many of these utilities
72are 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
80For more information, see the documentation on L<builtin>.
81
82=cut
83
84=head1 FUNCTIONS FOR REFERENCES
85
86The following functions all perform some useful activity on reference values.
87
88=head2 blessed
89
90    my $pkg = blessed( $ref );
91
92If C<$ref> is a blessed reference, the name of the package that it is blessed
93into 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
104Take care when using this function simply as a truth test (such as in
105C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
106
107I<Since Perl version 5.35.7> an equivalent function is available as
108C<builtin::blessed>.
109
110=head2 refaddr
111
112    my $addr = refaddr( $ref );
113
114If C<$ref> is reference, the internal memory address of the referenced value is
115returned 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
124I<Since Perl version 5.35.7> an equivalent function is available as
125C<builtin::refaddr>.
126
127=head2 reftype
128
129    my $type = reftype( $ref );
130
131If C<$ref> is a reference, the basic Perl type of the variable referenced is
132returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
133is 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
142Note that for internal reasons, all precompiled regexps (C<qr/.../>) are
143blessed references; thus C<ref()> returns the package name string C<"Regexp">
144on these but C<reftype()> will return the underlying C structure type of
145C<"REGEXP"> in all capitals.
146
147I<Since Perl version 5.35.7> an equivalent function is available as
148C<builtin::reftype>.
149
150=head2 weaken
151
152    weaken( $ref );
153
154The lvalue C<$ref> will be turned into a weak reference. This means that it
155will not hold a reference count on the object it references. Also, when the
156reference count on that object reaches zero, the reference will be set to
157undef. This function mutates the lvalue passed as its argument and returns no
158value.
159
160This is useful for keeping copies of references, but you don't want to prevent
161the 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
170Note that if you take a copy of a scalar with a weakened reference, the copy
171will 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
178This may be less obvious in other situations, such as C<grep()>, for instance
179when grepping through a list of weakened references to objects that may have
180been destroyed already:
181
182    @object = grep { defined } @object;
183
184This will indeed remove all references to destroyed objects, but the remaining
185references to objects will be strong, causing the remaining objects to never be
186destroyed because there is now always a strong reference to them in the @object
187array.
188
189I<Since Perl version 5.35.7> an equivalent function is available as
190C<builtin::weaken>.
191
192=head2 unweaken
193
194    unweaken( $ref );
195
196I<Since version 1.36.>
197
198The 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
200argument and returns no value. This undoes the action performed by
201L</weaken>.
202
203This function is slightly neater and more convenient than the
204otherwise-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
211not work to unweaken it; C<$REF = $REF> does not work).
212
213I<Since Perl version 5.35.7> an equivalent function is available as
214C<builtin::unweaken>.
215
216=head2 isweak
217
218    my $weak = isweak( $ref );
219
220Returns 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
227B<NOTE>: Copying a weak reference creates a normal, strong, reference.
228
229    $copy = $ref;
230    $weak = isweak($copy);              # false
231
232I<Since Perl version 5.35.7> an equivalent function is available as
233C<builtin::is_weak>.
234
235=head1 OTHER FUNCTIONS
236
237=head2 dualvar
238
239    my $var = dualvar( $num, $string );
240
241Returns a scalar that has the value C<$num> in a numeric context and the value
242C<$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
252I<Since version 1.26.>
253
254If C<$var> is a scalar that has both numeric and string values, the result is
255true.
256
257    $foo = dualvar 86, "Nix";
258    $dual = isdual($foo);               # true
259
260Note that a scalar can be made to have both string and numeric content through
261standard operations:
262
263    $foo = "10";
264    $dual = isdual($foo);               # false
265    $bar = $foo + 0;
266    $dual = isdual($foo);               # true
267
268The C<$!> variable is commonly dual-valued, though it is also magical in other
269ways:
270
271    $! = 1;
272    $dual = isdual($!);                 # true
273    print("$!\n");                      # "Operation not permitted"
274
275B<CAUTION>: This function is not as useful as it may seem. Dualvars are not a
276distinct concept in Perl, but a standard internal construct of all scalar
277values. Almost any value could be considered as a dualvar by this function
278through the course of normal operations.
279
280=head2 isvstring
281
282    my $vstring = isvstring( $var );
283
284If 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
294Returns true if perl thinks C<$var> is a number. See
295L<perlapi/looks_like_number>.
296
297=head2 openhandle
298
299    my $fh = openhandle( $fh );
300
301Returns C<$fh> itself, if C<$fh> may be used as a filehandle and is open, or if
302it 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
313Returns 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
324Sets the prototype of the function given by the C<$code> reference, or deletes
325it 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
333Return 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
340Module 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
346The version of perl that you are using does not implement Vstrings, to use
347L</isvstring> you will need to use a newer release of perl.
348
349=back
350
351=head1 KNOWN BUGS
352
353There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
354show up as tests 8 and 9 of dualvar.t failing
355
356=head1 SEE ALSO
357
358L<List::Util>
359
360=head1 COPYRIGHT
361
362Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
363This program is free software; you can redistribute it and/or modify it
364under the same terms as Perl itself.
365
366Additionally L</weaken> and L</isweak> which are
367
368Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
369This program is free software; you can redistribute it and/or modify it
370under the same terms as perl itself.
371
372Copyright (C) 2004, 2008  Matthijs van Duin.  All rights reserved.
373Copyright (C) 2014 cPanel Inc.  All rights reserved.
374This program is free software; you can redistribute it and/or modify
375it under the same terms as Perl itself.
376
377=cut
378