cpan/Scalar-List-Utils/lib/Scalar/Util.pm

   1 # Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. 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 <leonerd@leonerd.org.uk>
   6
   7 package Scalar::Util;
   8
   9 use strict;
  10 use warnings;
  11 require Exporter;
  12
  13 our @ISA       = qw(Exporter);
  14 our @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 );
  20 our $VERSION    = "1.63";
  21 $VERSION =~ tr/_//d;
  22
  23 require List::Util; # List::Util loads the XS
  24 List::Util->VERSION( $VERSION ); # Ensure we got the right XS version (RT#100863)
  25
  26 # populating @EXPORT_FAIL is done in the XS code
  27 sub export_fail {
  28   if (grep { /^isvstring$/ } @_ ) {
  29     require Carp;
  30     Carp::croak("Vstrings are not implemented in this version of perl");
  31   }
  32
  33   @_;
  34 }
  35
  36 # set_prototype has been moved to Sub::Util with a different interface
  37 sub set_prototype(&$)
  38 {
  39   my ( $code, $proto ) = @_;
  40   return Sub::Util::set_prototype( $proto, $code );
  41 }
  42
  43 1;
  44
  45 __END__
  46
  47 =head1 NAME
  48
  49 Scalar::Util - A selection of general-utility scalar subroutines
  50
  51 =head1 SYNOPSIS
  52
  53     use Scalar::Util qw(blessed dualvar isdual readonly refaddr reftype
  54                         tainted weaken isweak isvstring looks_like_number
  55                         set_prototype);
  56                         # and other useful utils appearing below
  57
  58 =head1 DESCRIPTION
  59
  60 C<Scalar::Util> contains a selection of subroutines that people have expressed
  61 would be nice to have in the perl core, but the usage would not really be high
  62 enough to warrant the use of a keyword, and the size would be so small that
  63 being individual extensions would be wasteful.
  64
  65 By default C<Scalar::Util> does not export any subroutines.
  66
  67 =head2 Core Perl C<builtin> Functions
  68
  69 Many functions in this module have served as the inspiration for a new
  70 experimental facility in recent versions of Perl. From various development
  71 versions, starting at 5.35.7, equivalent functions to many of these utilities
  72 are available in the C<builtin::> package.
  73
  74     use Scalar::Util qw(blessed);
  75
  76     $class = blessed $obj;
  77
  78     $class = builtin::blessed $obj;  # equivalent
  79
  80 For more information, see the documentation on L<builtin>.
  81
  82 =cut
  83
  84 =head1 FUNCTIONS FOR REFERENCES
  85
  86 The following functions all perform some useful activity on reference values.
  87
  88 =head2 blessed
  89
  90     my $pkg = blessed( $ref );
  91
  92 If C<$ref> is a blessed reference, the name of the package that it is blessed
  93 into is returned. Otherwise C<undef> is returned.
  94
  95     $scalar = "foo";
  96     $class  = blessed $scalar;           # undef
  97
  98     $ref    = [];
  99     $class  = blessed $ref;              # undef
 100
 101     $obj    = bless [], "Foo";
 102     $class  = blessed $obj;              # "Foo"
 103
 104 Take care when using this function simply as a truth test (such as in
 105 C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
 106
 107 I<Since Perl version 5.35.7> an equivalent function is available as
 108 C<builtin::blessed>.
 109
 110 =head2 refaddr
 111
 112     my $addr = refaddr( $ref );
 113
 114 If C<$ref> is reference, the internal memory address of the referenced value is
 115 returned as a plain integer. Otherwise C<undef> is returned.
 116
 117     $addr = refaddr "string";           # undef
 118     $addr = refaddr \$var;              # eg 12345678
 119     $addr = refaddr [];                 # eg 23456784
 120
 121     $obj  = bless {}, "Foo";
 122     $addr = refaddr $obj;               # eg 88123488
 123
 124 I<Since Perl version 5.35.7> an equivalent function is available as
 125 C<builtin::refaddr>.
 126
 127 =head2 reftype
 128
 129     my $type = reftype( $ref );
 130
 131 If C<$ref> is a reference, the basic Perl type of the variable referenced is
 132 returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
 133 is returned.
 134
 135     $type = reftype "string";           # undef
 136     $type = reftype \$var;              # SCALAR
 137     $type = reftype [];                 # ARRAY
 138
 139     $obj  = bless {}, "Foo";
 140     $type = reftype $obj;               # HASH
 141
 142 Note that for internal reasons, all precompiled regexps (C<qr/.../>) are
 143 blessed references; thus C<ref()> returns the package name string C<"Regexp">
 144 on these but C<reftype()> will return the underlying C structure type of
 145 C<"REGEXP"> in all capitals.
 146
 147 I<Since Perl version 5.35.7> an equivalent function is available as
 148 C<builtin::reftype>.
 149
 150 =head2 weaken
 151
 152     weaken( $ref );
 153
 154 The lvalue C<$ref> will be turned into a weak reference. This means that it
 155 will not hold a reference count on the object it references. Also, when the
 156 reference count on that object reaches zero, the reference will be set to
 157 undef. This function mutates the lvalue passed as its argument and returns no
 158 value.
 159
 160 This is useful for keeping copies of references, but you don't want to prevent
 161 the object being DESTROY-ed at its usual time.
 162
 163     {
 164       my $var;
 165       $ref = \$var;
 166       weaken($ref);                     # Make $ref a weak reference
 167     }
 168     # $ref is now undef
 169
 170 Note that if you take a copy of a scalar with a weakened reference, the copy
 171 will be a strong reference.
 172
 173     my $var;
 174     my $foo = \$var;
 175     weaken($foo);                       # Make $foo a weak reference
 176     my $bar = $foo;                     # $bar is now a strong reference
 177
 178 This may be less obvious in other situations, such as C<grep()>, for instance
 179 when grepping through a list of weakened references to objects that may have
 180 been destroyed already:
 181
 182     @object = grep { defined } @object;
 183
 184 This will indeed remove all references to destroyed objects, but the remaining
 185 references to objects will be strong, causing the remaining objects to never be
 186 destroyed because there is now always a strong reference to them in the @object
 187 array.
 188
 189 I<Since Perl version 5.35.7> an equivalent function is available as
 190 C<builtin::weaken>.
 191
 192 =head2 unweaken
 193
 194     unweaken( $ref );
 195
 196 I<Since version 1.36.>
 197
 198 The lvalue C<REF> will be turned from a weak reference back into a normal
 199 (strong) reference again. This function mutates the lvalue passed as its
 200 argument and returns no value. This undoes the action performed by
 201 L</weaken>.
 202
 203 This function is slightly neater and more convenient than the
 204 otherwise-equivalent code
 205
 206     my $tmp = $REF;
 207     undef $REF;
 208     $REF = $tmp;
 209
 210 (because in particular, simply assigning a weak reference back to itself does
 211 not work to unweaken it; C<$REF = $REF> does not work).
 212
 213 I<Since Perl version 5.35.7> an equivalent function is available as
 214 C<builtin::unweaken>.
 215
 216 =head2 isweak
 217
 218     my $weak = isweak( $ref );
 219
 220 Returns true if C<$ref> is a weak reference.
 221
 222     $ref  = \$foo;
 223     $weak = isweak($ref);               # false
 224     weaken($ref);
 225     $weak = isweak($ref);               # true
 226
 227 B<NOTE>: Copying a weak reference creates a normal, strong, reference.
 228
 229     $copy = $ref;
 230     $weak = isweak($copy);              # false
 231
 232 I<Since Perl version 5.35.7> an equivalent function is available as
 233 C<builtin::is_weak>.
 234
 235 =head1 OTHER FUNCTIONS
 236
 237 =head2 dualvar
 238
 239     my $var = dualvar( $num, $string );
 240
 241 Returns a scalar that has the value C<$num> in a numeric context and the value
 242 C<$string> in a string context.
 243
 244     $foo = dualvar 10, "Hello";
 245     $num = $foo + 2;                    # 12
 246     $str = $foo . " world";             # Hello world
 247
 248 =head2 isdual
 249
 250     my $dual = isdual( $var );
 251
 252 I<Since version 1.26.>
 253
 254 If C<$var> is a scalar that has both numeric and string values, the result is
 255 true.
 256
 257     $foo = dualvar 86, "Nix";
 258     $dual = isdual($foo);               # true
 259
 260 Note that a scalar can be made to have both string and numeric content through
 261 standard operations:
 262
 263     $foo = "10";
 264     $dual = isdual($foo);               # false
 265     $bar = $foo + 0;
 266     $dual = isdual($foo);               # true
 267
 268 The C<$!> variable is commonly dual-valued, though it is also magical in other
 269 ways:
 270
 271     $! = 1;
 272     $dual = isdual($!);                 # true
 273     print("$!\n");                      # "Operation not permitted"
 274
 275 B<CAUTION>: This function is not as useful as it may seem. Dualvars are not a
 276 distinct concept in Perl, but a standard internal construct of all scalar
 277 values. Almost any value could be considered as a dualvar by this function
 278 through the course of normal operations.
 279
 280 =head2 isvstring
 281
 282     my $vstring = isvstring( $var );
 283
 284 If C<$var> is a scalar which was coded as a vstring, the result is true.
 285
 286     $vs   = v49.46.48;
 287     $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
 288     printf($fmt,$vs);
 289
 290 =head2 looks_like_number
 291
 292     my $isnum = looks_like_number( $var );
 293
 294 Returns true if perl thinks C<$var> is a number. See
 295 L<perlapi/looks_like_number>.
 296
 297 =head2 openhandle
 298
 299     my $fh = openhandle( $fh );
 300
 301 Returns C<$fh> itself, if C<$fh> may be used as a filehandle and is open, or if
 302 it is a tied handle. Otherwise C<undef> is returned.
 303
 304     $fh = openhandle(*STDIN);           # \*STDIN
 305     $fh = openhandle(\*STDIN);          # \*STDIN
 306     $fh = openhandle(*NOTOPEN);         # undef
 307     $fh = openhandle("scalar");         # undef
 308
 309 =head2 readonly
 310
 311     my $ro = readonly( $var );
 312
 313 Returns true if C<$var> is readonly.
 314
 315     sub foo { readonly($_[0]) }
 316
 317     $readonly = foo($bar);              # false
 318     $readonly = foo(0);                 # true
 319
 320 =head2 set_prototype
 321
 322     my $code = set_prototype( $code, $prototype );
 323
 324 Sets the prototype of the function given by the C<$code> reference, or deletes
 325 it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
 326
 327     set_prototype \&foo, '$$';
 328
 329 =head2 tainted
 330
 331     my $t = tainted( $var );
 332
 333 Return true if C<$var> is tainted.
 334
 335     $taint = tainted("constant");       # false
 336     $taint = tainted($ENV{PWD});        # true if running under -T
 337
 338 =head1 DIAGNOSTICS
 339
 340 Module use may give one of the following errors during import.
 341
 342 =over
 343
 344 =item Vstrings are not implemented in this version of perl
 345
 346 The version of perl that you are using does not implement Vstrings, to use
 347 L</isvstring> you will need to use a newer release of perl.
 348
 349 =back
 350
 351 =head1 KNOWN BUGS
 352
 353 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
 354 show up as tests 8 and 9 of dualvar.t failing
 355
 356 =head1 SEE ALSO
 357
 358 L<List::Util>
 359
 360 =head1 COPYRIGHT
 361
 362 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
 363 This program is free software; you can redistribute it and/or modify it
 364 under the same terms as Perl itself.
 365
 366 Additionally L</weaken> and L</isweak> which are
 367
 368 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
 369 This program is free software; you can redistribute it and/or modify it
 370 under the same terms as perl itself.
 371
 372 Copyright (C) 2004, 2008  Matthijs van Duin.  All rights reserved.
 373 Copyright (C) 2014 cPanel Inc.  All rights reserved.
 374 This program is free software; you can redistribute it and/or modify
 375 it under the same terms as Perl itself.
 376
 377 =cut