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