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       Note that for internal reasons, all precompiled regexps ("qr/.../") are
73       blessed references; thus "ref()" returns the package name string
74       "Regexp" on these but "reftype()" will return the underlying C
75       structure type of "REGEXP" in all capitals.
76
77   weaken
78           weaken( $ref );
79
80       The lvalue $ref will be turned into a weak reference. This means that
81       it will not hold a reference count on the object it references. Also,
82       when the reference count on that object reaches zero, the reference
83       will be set to undef. This function mutates the lvalue passed as its
84       argument and returns no value.
85
86       This is useful for keeping copies of references, but you don't want to
87       prevent the object being DESTROY-ed at its usual time.
88
89           {
90             my $var;
91             $ref = \$var;
92             weaken($ref);                     # Make $ref a weak reference
93           }
94           # $ref is now undef
95
96       Note that if you take a copy of a scalar with a weakened reference, the
97       copy will be a strong reference.
98
99           my $var;
100           my $foo = \$var;
101           weaken($foo);                       # Make $foo a weak reference
102           my $bar = $foo;                     # $bar is now a strong reference
103
104       This may be less obvious in other situations, such as "grep()", for
105       instance when grepping through a list of weakened references to objects
106       that may have been destroyed already:
107
108           @object = grep { defined } @object;
109
110       This will indeed remove all references to destroyed objects, but the
111       remaining references to objects will be strong, causing the remaining
112       objects to never be destroyed because there is now always a strong
113       reference to them in the @object array.
114
115   unweaken
116           unweaken( $ref );
117
118       Since version 1.36.
119
120       The lvalue "REF" will be turned from a weak reference back into a
121       normal (strong) reference again. This function mutates the lvalue
122       passed as its argument and returns no value. This undoes the action
123       performed by "weaken".
124
125       This function is slightly neater and more convenient than the
126       otherwise-equivalent code
127
128           my $tmp = $REF;
129           undef $REF;
130           $REF = $tmp;
131
132       (because in particular, simply assigning a weak reference back to
133       itself does not work to unweaken it; "$REF = $REF" does not work).
134
135   isweak
136           my $weak = isweak( $ref );
137
138       Returns true if $ref is a weak reference.
139
140           $ref  = \$foo;
141           $weak = isweak($ref);               # false
142           weaken($ref);
143           $weak = isweak($ref);               # true
144
145       NOTE: Copying a weak reference creates a normal, strong, reference.
146
147           $copy = $ref;
148           $weak = isweak($copy);              # false
149

OTHER FUNCTIONS

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

DIAGNOSTICS

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

KNOWN BUGS

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

SEE ALSO

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