1Scalar::Util(3)       User Contributed Perl Documentation      Scalar::Util(3)
2
3
4

NAME

6       Scalar::Util - A selection of general-utility scalar subroutines
7

SYNOPSIS

9           use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
10                               tainted weaken isweak isvstring looks_like_number
11                               set_prototype);
12                               # and other useful utils appearing below
13

DESCRIPTION

15       "Scalar::Util" contains a selection of subroutines that people have
16       expressed would be nice to have in the perl core, but the usage would
17       not really be high enough to warrant the use of a keyword, and the size
18       would be so small that being individual extensions would be wasteful.
19
20       By default "Scalar::Util" does not export any subroutines.
21

FUNCTIONS FOR REFERENCES

23       The following functions all perform some useful activity on reference
24       values.
25
26   blessed
27           my $pkg = blessed( $ref );
28
29       If $ref is a blessed reference, the name of the package that it is
30       blessed into is returned. Otherwise "undef" is returned.
31
32           $scalar = "foo";
33           $class  = blessed $scalar;           # undef
34
35           $ref    = [];
36           $class  = blessed $ref;              # undef
37
38           $obj    = bless [], "Foo";
39           $class  = blessed $obj;              # "Foo"
40
41       Take care when using this function simply as a truth test (such as in
42       "if(blessed $ref)...") because the package name "0" is defined yet
43       false.
44
45   refaddr
46           my $addr = refaddr( $ref );
47
48       If $ref is reference, the internal memory address of the referenced
49       value is returned as a plain integer. Otherwise "undef" is returned.
50
51           $addr = refaddr "string";           # undef
52           $addr = refaddr \$var;              # eg 12345678
53           $addr = refaddr [];                 # eg 23456784
54
55           $obj  = bless {}, "Foo";
56           $addr = refaddr $obj;               # eg 88123488
57
58   reftype
59           my $type = reftype( $ref );
60
61       If $ref is a reference, the basic Perl type of the variable referenced
62       is returned as a plain string (such as "ARRAY" or "HASH"). Otherwise
63       "undef" is returned.
64
65           $type = reftype "string";           # undef
66           $type = reftype \$var;              # SCALAR
67           $type = reftype [];                 # ARRAY
68
69           $obj  = bless {}, "Foo";
70           $type = reftype $obj;               # HASH
71
72   weaken
73           weaken( $ref );
74
75       The lvalue $ref will be turned into a weak reference. This means that
76       it will not hold a reference count on the object it references. Also,
77       when the reference count on that object reaches zero, the reference
78       will be set to undef. This function mutates the lvalue passed as its
79       argument and returns no value.
80
81       This is useful for keeping copies of references, but you don't want to
82       prevent the object being DESTROY-ed at its usual time.
83
84           {
85             my $var;
86             $ref = \$var;
87             weaken($ref);                     # Make $ref a weak reference
88           }
89           # $ref is now undef
90
91       Note that if you take a copy of a scalar with a weakened reference, the
92       copy will be a strong reference.
93
94           my $var;
95           my $foo = \$var;
96           weaken($foo);                       # Make $foo a weak reference
97           my $bar = $foo;                     # $bar is now a strong reference
98
99       This may be less obvious in other situations, such as "grep()", for
100       instance when grepping through a list of weakened references to objects
101       that may have been destroyed already:
102
103           @object = grep { defined } @object;
104
105       This will indeed remove all references to destroyed objects, but the
106       remaining references to objects will be strong, causing the remaining
107       objects to never be destroyed because there is now always a strong
108       reference to them in the @object array.
109
110   unweaken
111           unweaken( $ref );
112
113       Since version 1.36.
114
115       The lvalue "REF" will be turned from a weak reference back into a
116       normal (strong) reference again. This function mutates the lvalue
117       passed as its argument and returns no value. This undoes the action
118       performed by "weaken".
119
120       This function is slightly neater and more convenient than the
121       otherwise-equivalent code
122
123           my $tmp = $REF;
124           undef $REF;
125           $REF = $tmp;
126
127       (because in particular, simply assigning a weak reference back to
128       itself does not work to unweaken it; "$REF = $REF" does not work).
129
130   isweak
131           my $weak = isweak( $ref );
132
133       Returns true if $ref is a weak reference.
134
135           $ref  = \$foo;
136           $weak = isweak($ref);               # false
137           weaken($ref);
138           $weak = isweak($ref);               # true
139
140       NOTE: Copying a weak reference creates a normal, strong, reference.
141
142           $copy = $ref;
143           $weak = isweak($copy);              # false
144

OTHER FUNCTIONS

146   dualvar
147           my $var = dualvar( $num, $string );
148
149       Returns a scalar that has the value $num in a numeric context and the
150       value $string in a string context.
151
152           $foo = dualvar 10, "Hello";
153           $num = $foo + 2;                    # 12
154           $str = $foo . " world";             # Hello world
155
156   isdual
157           my $dual = isdual( $var );
158
159       Since version 1.26.
160
161       If $var is a scalar that has both numeric and string values, the result
162       is true.
163
164           $foo = dualvar 86, "Nix";
165           $dual = isdual($foo);               # true
166
167       Note that a scalar can be made to have both string and numeric content
168       through numeric operations:
169
170           $foo = "10";
171           $dual = isdual($foo);               # false
172           $bar = $foo + 0;
173           $dual = isdual($foo);               # true
174
175       Note that although $! appears to be a dual-valued variable, it is
176       actually implemented as a magical variable inside the interpreter:
177
178           $! = 1;
179           print("$!\n");                      # "Operation not permitted"
180           $dual = isdual($!);                 # false
181
182       You can capture its numeric and string content using:
183
184           $err = dualvar $!, $!;
185           $dual = isdual($err);               # true
186
187   isvstring
188           my $vstring = isvstring( $var );
189
190       If $var is a scalar which was coded as a vstring, the result is true.
191
192           $vs   = v49.46.48;
193           $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
194           printf($fmt,$vs);
195
196   looks_like_number
197           my $isnum = looks_like_number( $var );
198
199       Returns true if perl thinks $var is a number. See "looks_like_number"
200       in perlapi.
201
202   openhandle
203           my $fh = openhandle( $fh );
204
205       Returns $fh itself if $fh may be used as a filehandle and is open, or
206       is is a tied handle. Otherwise "undef" is returned.
207
208           $fh = openhandle(*STDIN);           # \*STDIN
209           $fh = openhandle(\*STDIN);          # \*STDIN
210           $fh = openhandle(*NOTOPEN);         # undef
211           $fh = openhandle("scalar");         # undef
212
213   readonly
214           my $ro = readonly( $var );
215
216       Returns true if $var is readonly.
217
218           sub foo { readonly($_[0]) }
219
220           $readonly = foo($bar);              # false
221           $readonly = foo(0);                 # true
222
223   set_prototype
224           my $code = set_prototype( $code, $prototype );
225
226       Sets the prototype of the function given by the $code reference, or
227       deletes it if $prototype is "undef". Returns the $code reference
228       itself.
229
230           set_prototype \&foo, '$$';
231
232   tainted
233           my $t = tainted( $var );
234
235       Return true if $var is tainted.
236
237           $taint = tainted("constant");       # false
238           $taint = tainted($ENV{PWD});        # true if running under -T
239

DIAGNOSTICS

241       Module use may give one of the following errors during import.
242
243       Weak references are not implemented in the version of perl
244           The version of perl that you are using does not implement weak
245           references, to use "isweak" or "weaken" you will need to use a
246           newer release of perl.
247
248       Vstrings are not implemented in the version of perl
249           The version of perl that you are using does not implement Vstrings,
250           to use "isvstring" you will need to use a newer release of perl.
251

KNOWN BUGS

253       There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show
254       up as tests 8 and 9 of dualvar.t failing
255

SEE ALSO

257       List::Util
258
260       Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
261       reserved.  This program is free software; you can redistribute it
262       and/or modify it under the same terms as Perl itself.
263
264       Additionally "weaken" and "isweak" which are
265
266       Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
267       This program is free software; you can redistribute it and/or modify it
268       under the same terms as perl itself.
269
270       Copyright (C) 2004, 2008  Matthijs van Duin.  All rights reserved.
271       Copyright (C) 2014 cPanel Inc.  All rights reserved.  This program is
272       free software; you can redistribute it and/or modify it under the same
273       terms as Perl itself.
274
275
276
277perl v5.28.1                      2018-02-20                   Scalar::Util(3)
Impressum