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 croak().
212
213   is_ioref($ref)
214       Check for an IO reference.
215
216           is_ioref( *STDOUT{IO} );
217
218   is_refref($ref)
219       Check for a reference to a reference.
220
221           is_refref( \[] ); # reference to array reference
222
223   is_plain_scalarref($ref)
224       Check for an unblessed scalar reference.
225
226           is_plain_scalarref(\"hello");
227           is_plain_scalarref(\30);
228           is_plain_scalarref(\$value);
229
230   is_plain_ref($ref)
231       Check for an unblessed reference to anything.
232
233           is_plain_ref([]);
234
235   is_plain_arrayref($ref)
236       Check for an unblessed array reference.
237
238           is_plain_arrayref([]);
239
240   is_plain_hashref($ref)
241       Check for an unblessed hash reference.
242
243           is_plain_hashref({});
244
245   is_plain_coderef($ref)
246       Check for an unblessed code reference.
247
248           is_plain_coderef( sub {} );
249
250   is_plain_globref($ref)
251       Check for an unblessed glob reference.
252
253           is_plain_globref( \*STDIN );
254
255   is_plain_formatref($ref)
256       Check for an unblessed format reference.
257
258           # set up format in STDOUT
259           format STDOUT =
260           .
261
262           # now we can test it
263           is_plain_formatref(bless *main::STDOUT{'FORMAT'} );
264
265   is_plain_refref($ref)
266       Check for an unblessed reference to a reference.
267
268           is_plain_refref( \[] ); # reference to array reference
269
270   is_blessed_scalarref($ref)
271       Check for a blessed scalar reference.
272
273           is_blessed_scalarref(bless \$value);
274
275   is_blessed_ref($ref)
276       Check for a blessed reference to anything.
277
278           is_blessed_ref(bless [], $class);
279
280   is_blessed_arrayref($ref)
281       Check for a blessed array reference.
282
283           is_blessed_arrayref(bless [], $class);
284
285   is_blessed_hashref($ref)
286       Check for a blessed hash reference.
287
288           is_blessed_hashref(bless {}, $class);
289
290   is_blessed_coderef($ref)
291       Check for a blessed code reference.
292
293           is_blessed_coderef( bless sub {}, $class );
294
295   is_blessed_globref($ref)
296       Check for a blessed glob reference.
297
298           is_blessed_globref( bless \*STDIN, $class );
299
300   is_blessed_formatref($ref)
301       Check for a blessed format reference.
302
303           # set up format for FH
304           format FH =
305           .
306
307           # now we can test it
308           is_blessed_formatref(bless *FH{'FORMAT'}, $class );
309
310   is_blessed_refref($ref)
311       Check for a blessed reference to a reference.
312
313           is_blessed_refref( bless \[], $class ); # reference to array reference
314

BENCHMARKS

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

THANKS

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

AUTHORS

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

LICENSE

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

AUTHORS

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

COPYRIGHT AND LICENSE

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