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.
10 use vars qw(@ISA @EXPORT_OK $VERSION @EXPORT_FAIL);
12 require List::Util; # List::Util loads the XS
15 @EXPORT_OK = qw(blessed dualvar reftype weaken isweak tainted readonly openhandle refaddr isvstring looks_like_number set_prototype);
17 $VERSION = eval $VERSION;
19 unless (defined &dualvar) {
20 # Load Pure Perl version if XS not loaded
21 require Scalar::Util::PP;
22 Scalar::Util::PP->import;
23 push @EXPORT_FAIL, qw(weaken isweak dualvar isvstring set_prototype);
27 if (grep { /dualvar/ } @EXPORT_FAIL) { # no XS loaded
28 my $pat = join("|", @EXPORT_FAIL);
29 if (my ($err) = grep { /^($pat)$/ } @_ ) {
31 Carp::croak("$err is only available with the XS version of Scalar::Util");
35 if (grep { /^(weaken|isweak)$/ } @_ ) {
37 Carp::croak("Weak references are not implemented in the version of perl");
40 if (grep { /^(isvstring)$/ } @_ ) {
42 Carp::croak("Vstrings are not implemented in the version of perl");
50 my $rt = reftype($fh) || '';
52 return defined(fileno($fh)) ? $fh : undef
55 if (reftype(\$fh) eq 'GLOB') { # handle openhandle(*DATA)
58 elsif ($rt ne 'GLOB') {
62 (tied(*$fh) or defined(fileno($fh)))
72 Scalar::Util - A selection of general-utility scalar subroutines
76 use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
77 weaken isvstring looks_like_number set_prototype);
78 # and other useful utils appearing below
82 C<Scalar::Util> contains a selection of subroutines that people have
83 expressed would be nice to have in the perl core, but the usage would
84 not really be high enough to warrant the use of a keyword, and the size
85 so small such that being individual extensions would be wasteful.
87 By default C<Scalar::Util> does not export any subroutines. The
88 subroutines defined are
94 If EXPR evaluates to a blessed reference the name of the package
95 that it is blessed into is returned. Otherwise C<undef> is returned.
98 $class = blessed $scalar; # undef
101 $class = blessed $ref; # undef
103 $obj = bless [], "Foo";
104 $class = blessed $obj; # "Foo"
106 =item dualvar NUM, STRING
108 Returns a scalar that has the value NUM in a numeric context and the
109 value STRING in a string context.
111 $foo = dualvar 10, "Hello";
112 $num = $foo + 2; # 12
113 $str = $foo . " world"; # Hello world
117 If EXPR is a scalar which was coded as a vstring the result is true.
120 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
125 If EXPR is a scalar which is a weak reference the result is true.
128 $weak = isweak($ref); # false
130 $weak = isweak($ref); # true
132 B<NOTE>: Copying a weak reference creates a normal, strong, reference.
135 $weak = isweak($copy); # false
137 =item looks_like_number EXPR
139 Returns true if perl thinks EXPR is a number. See
140 L<perlapi/looks_like_number>.
144 Returns FH if FH may be used as a filehandle and is open, or FH is a tied
145 handle. Otherwise C<undef> is returned.
147 $fh = openhandle(*STDIN); # \*STDIN
148 $fh = openhandle(\*STDIN); # \*STDIN
149 $fh = openhandle(*NOTOPEN); # undef
150 $fh = openhandle("scalar"); # undef
152 =item readonly SCALAR
154 Returns true if SCALAR is readonly.
156 sub foo { readonly($_[0]) }
158 $readonly = foo($bar); # false
159 $readonly = foo(0); # true
163 If EXPR evaluates to a reference the internal memory address of
164 the referenced value is returned. Otherwise C<undef> is returned.
166 $addr = refaddr "string"; # undef
167 $addr = refaddr \$var; # eg 12345678
168 $addr = refaddr []; # eg 23456784
170 $obj = bless {}, "Foo";
171 $addr = refaddr $obj; # eg 88123488
175 If EXPR evaluates to a reference the type of the variable referenced
176 is returned. Otherwise C<undef> is returned.
178 $type = reftype "string"; # undef
179 $type = reftype \$var; # SCALAR
180 $type = reftype []; # ARRAY
182 $obj = bless {}, "Foo";
183 $type = reftype $obj; # HASH
185 =item set_prototype CODEREF, PROTOTYPE
187 Sets the prototype of the given function, or deletes it if PROTOTYPE is
188 undef. Returns the CODEREF.
190 set_prototype \&foo, '$$';
194 Return true if the result of EXPR is tainted
196 $taint = tainted("constant"); # false
197 $taint = tainted($ENV{PWD}); # true if running under -T
201 REF will be turned into a weak reference. This means that it will not
202 hold a reference count on the object it references. Also when the reference
203 count on that object reaches zero, REF will be set to undef.
205 This is useful for keeping copies of references , but you don't want to
206 prevent the object being DESTROY-ed at its usual time.
211 weaken($ref); # Make $ref a weak reference
215 Note that if you take a copy of a scalar with a weakened reference,
216 the copy will be a strong reference.
220 weaken($foo); # Make $foo a weak reference
221 my $bar = $foo; # $bar is now a strong reference
223 This may be less obvious in other situations, such as C<grep()>, for instance
224 when grepping through a list of weakened references to objects that may have
225 been destroyed already:
227 @object = grep { defined } @object;
229 This will indeed remove all references to destroyed objects, but the remaining
230 references to objects will be strong, causing the remaining objects to never
231 be destroyed because there is now always a strong reference to them in the
238 Module use may give one of the following errors during import.
242 =item Weak references are not implemented in the version of perl
244 The version of perl that you are using does not implement weak references, to use
245 C<isweak> or C<weaken> you will need to use a newer release of perl.
247 =item Vstrings are not implemented in the version of perl
249 The version of perl that you are using does not implement Vstrings, to use
250 C<isvstring> you will need to use a newer release of perl.
252 =item C<NAME> is only available with the XS version of Scalar::Util
254 C<Scalar::Util> contains both perl and C implementations of many of its functions
255 so that those without access to a C compiler may still use it. However some of the functions
256 are only available when a C compiler was available to compile the XS version of the extension.
258 At present that list is: weaken, isweak, dualvar, isvstring, set_prototype
264 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
265 show up as tests 8 and 9 of dualvar.t failing
273 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
274 This program is free software; you can redistribute it and/or modify it
275 under the same terms as Perl itself.
277 Except weaken and isweak which are
279 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
280 This program is free software; you can redistribute it and/or modify it
281 under the same terms as perl itself.