Commit | Line | Data |
---|---|---|
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 | |
9 | package Scalar::Util; | |
10 | ||
4984adac | 11 | use strict; |
f4a2945e JH |
12 | require Exporter; |
13 | require List::Util; # List::Util loads the XS | |
14 | ||
3630f57e | 15 | our @ISA = qw(Exporter); |
8b198969 CBW |
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 | ); | |
98eca5fa | 31 | our $VERSION = "1.35"; |
09c2a9b8 GB |
32 | $VERSION = eval $VERSION; |
33 | ||
3630f57e CBW |
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); | |
2ff28616 GB |
44 | } |
45 | ||
09c2a9b8 | 46 | sub 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 |
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 | ||
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 | ||
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 | ||
ad434879 | 85 | =head2 blessed EXPR |
f4a2945e JH |
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 | ||
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 |
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 | |
f4a2945e JH |
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"; | |
c29e891d GB |
109 | $num = $foo + 2; # 12 |
110 | $str = $foo . " world"; # Hello world | |
f4a2945e | 111 | |
ad434879 | 112 | =head2 isdual EXPR |
60f3865b | 113 | |
8b198969 | 114 | If 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 |
119 | Note that a scalar can be made to have both string and numeric content |
120 | through 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 |
127 | Note that although C<$!> appears to be dual-valued variable, it is |
128 | actually 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 |
134 | You 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 | |
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); | |
4984adac | 146 | |
ad434879 | 147 | =head2 looks_like_number EXPR |
9e7deb6c GB |
148 | |
149 | Returns true if perl thinks EXPR is a number. See | |
150 | L<perlapi/looks_like_number>. | |
151 | ||
ad434879 | 152 | =head2 openhandle FH |
c0f790df GB |
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 | ||
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 | |
164 | Returns 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 | |
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 | ||
ad434879 | 183 | =head2 reftype EXPR |
f4a2945e JH |
184 | |
185 | If EXPR evaluates to a reference the type of the variable referenced | |
186 | is 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 | |
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 | ||
ad434879 | 202 | =head2 tainted EXPR |
ee4ffb48 JH |
203 | |
204 | Return 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 | |
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 | |
022735b4 | 216 | prevent 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 |
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 | ||
ad434879 | 244 | =head2 isweak EXPR |
8b198969 CBW |
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 | ||
2ff28616 GB |
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 | ||
9c3c560b JH |
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 | ||
ddf53ba4 GB |
289 | =head1 SEE ALSO |
290 | ||
291 | L<List::Util> | |
292 | ||
f4a2945e JH |
293 | =head1 COPYRIGHT |
294 | ||
2ff28616 | 295 | Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved. |
c29e891d | 296 | This program is free software; you can redistribute it and/or modify it |
f4a2945e JH |
297 | under the same terms as Perl itself. |
298 | ||
c29e891d | 299 | Except weaken and isweak which are |
f4a2945e JH |
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 | ||
f4a2945e | 305 | =cut |