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