← Index
NYTProf Performance Profile   « line view »
For /Users/brian/bin/perls/cpan5.26.1
  Run on Sat Dec 30 01:41:10 2017
Reported on Sat Dec 30 01:44:15 2017

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