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