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