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