Ref::Util(3pm)

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

NAME

6       Ref::Util - Utility functions for checking references
7

VERSION

9       version 0.204
10

SYNOPSIS

12           use Ref::Util qw( is_plain_arrayref is_plain_hashref );
13
14           if ( is_plain_arrayref( $something ) ) {
15               print for @{ $something };
16           } elsif ( is_plain_hashref( $something ) ) {
17               print for sort values %{ $something };
18           }
19

DESCRIPTION

21       Ref::Util introduces several functions to help identify references in a
22       smarter (and usually faster) way. In short:
23
24           # conventional approach             # with Ref::Util
25
26           ref( $foo ) eq 'ARRAY'              is_plain_arrayref( $foo )
27
28           use Scalar::Util qw( reftype );
29           reftype( $foo ) eq 'ARRAY'          is_arrayref( $foo )
30
31       The difference:
32
33       •   No comparison against a string constant
34
35           When you call "ref", you stringify the reference and then compare
36           it to some string constant (like "ARRAY" or "HASH"). Not just
37           awkward, it's brittle since you can mispell the string.
38
39           If you use Scalar::Util's "reftype", you still compare it as a
40           string:
41
42               if ( reftype($foo) eq 'ARRAY' ) { ... }
43
44       •   Supports blessed variables
45
46           Note: In future versions, the idea is to make the default functions
47           use the plain variation, which means explicitly non-blessed
48           references.
49
50           If you want to explicitly check for blessed references, you should
51           use the "is_blessed_*" functions. There will be an "is_any_*"
52           variation which will act like the current main functions - not
53           caring whether it's blessed or not.
54
55           When calling "ref", you receive either the reference type (SCALAR,
56           ARRAY, HASH, etc.) or the package it's blessed into.
57
58           When calling "is_arrayref" (et. al.), you check the variable flags,
59           so even if it's blessed, you know what type of variable is blessed.
60
61               my $foo = bless {}, 'PKG';
62               ref($foo) eq 'HASH'; # fails
63
64               use Ref::Util 'is_hashref';
65               my $foo = bless {}, 'PKG';
66               is_hashref($foo); # works
67
68           On the other hand, in some situations it might be better to
69           specifically exclude blessed references. The rationale for that
70           might be that merely because some object happens to be implemented
71           using a hash doesn't mean it's necessarily correct to treat it as a
72           hash. For these situations, you can use "is_plain_hashref" and
73           friends, which have the same performance benefits as "is_hashref".
74
75           There is also a family of functions with names like
76           "is_blessed_hashref"; these return true for blessed object
77           instances that are implemented using the relevant underlying type.
78
79       •   Supports tied variables and magic
80
81           Tied variables (used in Readonly, for example) are supported.
82
83               use Ref::Util qw<is_plain_hashref>;
84               use Readonly;
85
86               Readonly::Scalar my $rh2 => { a => { b => 2 } };
87               is_plain_hashref($rh2); # success
88
89           Ref::Util added support for this in 0.100. Prior to this version
90           the test would fail.
91
92       •   Ignores overloading
93
94           These functions ignore overloaded operators and simply check the
95           variable type. Overloading will likely not ever be supported, since
96           I deem it problematic and confusing.
97
98           Overloading makes your variables opaque containers and hides away
99           what they are and instead require you to figure out how to use
100           them. This leads to code that has to test different abilities (in
101           "eval", so it doesn't crash) and to interfaces that get around what
102           a person thought you would do with a variable. This would have been
103           alright, except there is no clear way of introspecting it.
104
105       •   Ignores subtle types:
106
107           The following types, provided by Scalar::Util's "reftype", are not
108           supported:
109
110           •   "VSTRING"
111
112               This is a "PVMG" ("normal" variable) with a flag set for
113               VSTRINGs.  Since this is not a reference, it is not supported.
114
115           •   "LVALUE"
116
117               A variable that delegates to another scalar. Since this is not
118               a reference, it is not supported.
119
120           •   "INVLIST"
121
122               I couldn't find documentation for this type.
123
124           Support might be added, if a good reason arises.
125
126       •   Usually fast
127
128           When possible, Ref::Util uses Ref::Util::XS as its implementation.
129           (If you don't have a C compiler available, it uses a pure Perl
130           fallback that has all the other advantages of Ref::Util, but isn't
131           as fast.)
132
133           In fact, Ref::Util::XS has two alternative implementations
134           available internally, depending on the features supported by the
135           version of Perl you're using. For Perls that supports custom OPs,
136           we actually add an OP (which is faster); for other Perls, the
137           implementation that simply calls an XS function (which is still
138           faster than the pure-Perl equivalent).
139
140           See below for benchmark results.
141

EXPORT

143       Nothing is exported by default. You can ask for specific subroutines
144       (described below) or ask for all subroutines at once:
145
146           use Ref::Util qw<is_scalarref is_arrayref is_hashref ...>;
147
148           # or
149
150           use Ref::Util ':all';
151

SUBROUTINES

153   is_ref($ref)
154       Check for a reference to anything.
155
156           is_ref([]);
157
158   is_scalarref($ref)
159       Check for a scalar reference.
160
161           is_scalarref(\"hello");
162           is_scalarref(\30);
163           is_scalarref(\$value);
164
165       Note that, even though a reference is itself a type of scalar value, a
166       reference to another reference is not treated as a scalar reference:
167
168           !is_scalarref(\\1);
169
170       The rationale for this is two-fold. First, callers that want to decide
171       how to handle inputs based on their reference type will usually want to
172       treat a ref-ref and a scalar-ref differently. Secondly, this more
173       closely matches the behavior of the "ref" built-in and of "reftype" in
174       Scalar::Util, which report a ref-ref as "REF" rather than "SCALAR".
175
176   is_arrayref($ref)
177       Check for an array reference.
178
179           is_arrayref([]);
180
181   is_hashref($ref)
182       Check for a hash reference.
183
184           is_hashref({});
185
186   is_coderef($ref)
187       Check for a code reference.
188
189           is_coderef( sub {} );
190
191   is_regexpref($ref)
192       Check for a regular expression (regex, regexp) reference.
193
194           is_regexpref( qr// );
195
196   is_globref($ref)
197       Check for a glob reference.
198
199           is_globref( \*STDIN );
200
201   is_formatref($ref)
202       Check for a format reference.
203
204           # set up format in STDOUT
205           format STDOUT =
206           .
207
208           # now we can test it
209           is_formatref( *main::STDOUT{'FORMAT'} );
210
211       This function is not available in Perl 5.6 and will trigger a
212       "croak()".
213
214   is_ioref($ref)
215       Check for an IO reference.
216
217           is_ioref( *STDOUT{IO} );
218
219   is_refref($ref)
220       Check for a reference to a reference.
221
222           is_refref( \[] ); # reference to array reference
223
224   is_plain_scalarref($ref)
225       Check for an unblessed scalar reference.
226
227           is_plain_scalarref(\"hello");
228           is_plain_scalarref(\30);
229           is_plain_scalarref(\$value);
230
231   is_plain_ref($ref)
232       Check for an unblessed reference to anything.
233
234           is_plain_ref([]);
235
236   is_plain_arrayref($ref)
237       Check for an unblessed array reference.
238
239           is_plain_arrayref([]);
240
241   is_plain_hashref($ref)
242       Check for an unblessed hash reference.
243
244           is_plain_hashref({});
245
246   is_plain_coderef($ref)
247       Check for an unblessed code reference.
248
249           is_plain_coderef( sub {} );
250
251   is_plain_globref($ref)
252       Check for an unblessed glob reference.
253
254           is_plain_globref( \*STDIN );
255
256   is_plain_formatref($ref)
257       Check for an unblessed format reference.
258
259           # set up format in STDOUT
260           format STDOUT =
261           .
262
263           # now we can test it
264           is_plain_formatref(bless *main::STDOUT{'FORMAT'} );
265
266   is_plain_refref($ref)
267       Check for an unblessed reference to a reference.
268
269           is_plain_refref( \[] ); # reference to array reference
270
271   is_blessed_scalarref($ref)
272       Check for a blessed scalar reference.
273
274           is_blessed_scalarref(bless \$value);
275
276   is_blessed_ref($ref)
277       Check for a blessed reference to anything.
278
279           is_blessed_ref(bless [], $class);
280
281   is_blessed_arrayref($ref)
282       Check for a blessed array reference.
283
284           is_blessed_arrayref(bless [], $class);
285
286   is_blessed_hashref($ref)
287       Check for a blessed hash reference.
288
289           is_blessed_hashref(bless {}, $class);
290
291   is_blessed_coderef($ref)
292       Check for a blessed code reference.
293
294           is_blessed_coderef( bless sub {}, $class );
295
296   is_blessed_globref($ref)
297       Check for a blessed glob reference.
298
299           is_blessed_globref( bless \*STDIN, $class );
300
301   is_blessed_formatref($ref)
302       Check for a blessed format reference.
303
304           # set up format for FH
305           format FH =
306           .
307
308           # now we can test it
309           is_blessed_formatref(bless *FH{'FORMAT'}, $class );
310
311   is_blessed_refref($ref)
312       Check for a blessed reference to a reference.
313
314           is_blessed_refref( bless \[], $class ); # reference to array reference
315

BENCHMARKS

317       Here is a benchmark comparing similar checks.
318
319           my $bench = Dumbbench->new(
320               target_rel_precision => 0.005,
321               initial_runs         => 20,
322           );
323
324           my $amount = 1e7;
325           my $ref    = [];
326           $bench->add_instances(
327               Dumbbench::Instance::PerlSub->new(
328                   name => 'Ref::Util::is_plain_arrayref (CustomOP)',
329                   code => sub {
330                       Ref::Util::is_plain_arrayref($ref) for ( 1 .. $amount )
331                   },
332               ),
333
334               Dumbbench::Instance::PerlSub->new(
335                   name => 'ref(), reftype(), !blessed()',
336                   code => sub {
337                       ref $ref
338                           && Scalar::Util::reftype($ref) eq 'ARRAY'
339                           && !Scalar::Util::blessed($ref)
340                           for ( 1 .. $amount );
341                   },
342               ),
343
344               Dumbbench::Instance::PerlSub->new(
345                   name => 'ref()',
346                   code => sub { ref($ref) eq 'ARRAY' for ( 1 .. $amount ) },
347               ),
348
349               Dumbbench::Instance::PerlSub->new(
350                   name => 'Data::Util::is_array_ref',
351                   code => sub { is_array_ref($ref) for ( 1 .. $amount ) },
352               ),
353
354           );
355
356       The results:
357
358           ref():                                   5.335e+00 +/- 1.8e-02 (0.3%)
359           ref(), reftype(), !blessed():            1.5545e+01 +/- 3.1e-02 (0.2%)
360           Ref::Util::is_plain_arrayref (CustomOP): 2.7951e+00 +/- 6.2e-03 (0.2%)
361           Data::Util::is_array_ref:                5.9074e+00 +/- 7.5e-03 (0.1%)
362
363       (Rounded run time per iteration)
364
365       A benchmark against Data::Util:
366
367           Ref::Util::is_plain_arrayref: 3.47157e-01 +/- 6.8e-05 (0.0%)
368           Data::Util::is_array_ref:     6.7562e-01 +/- 7.5e-04 (0.1%)
369

THANKS

378       The following people have been invaluable in their feedback and
379       support.
380
381       •   Yves Orton
382
383       •   Steffen Müller
384
385       •   Jarkko Hietaniemi
386
387       •   Mattia Barbon
388
389       •   Zefram
390
391       •   Tony Cook
392
393       •   Sergey Aleynikov
394

AUTHORS

396       •   Aaron Crane
397
398       •   Vikentiy Fesunov
399
400       •   Sawyer X
401
402       •   Gonzalo Diethelm
403
404       •   p5pclub
405

LICENSE

407       This software is made available under the MIT Licence as stated in the
408       accompanying LICENSE file.
409

AUTHORS

411       •   Sawyer X <xsawyerx@cpan.org>
412
413       •   Aaron Crane <arc@cpan.org>
414
415       •   Vikenty Fesunov <vyf@cpan.org>
416
417       •   Gonzalo Diethelm <gonzus@cpan.org>
418
419       •   Karen Etheridge <ether@cpan.org>
420

COPYRIGHT AND LICENSE

422       This software is Copyright (c) 2017 by Sawyer X.
423
424       This is free software, licensed under:
425
426         The MIT (X11) License
427
428
429
430perl v5.36.0                      2022-07-22                      Ref::Util(3)