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.60";
  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 =cut
  68
  69 =head1 FUNCTIONS FOR REFERENCES
  70
  71 The following functions all perform some useful activity on reference values.
  72
  73 =head2 blessed
  74
  75     my $pkg = blessed( $ref );
  76
  77 If C<$ref> is a blessed reference, the name of the package that it is blessed
  78 into is returned. Otherwise C<undef> is returned.
  79
  80     $scalar = "foo";
  81     $class  = blessed $scalar;           # undef
  82
  83     $ref    = [];
  84     $class  = blessed $ref;              # undef
  85
  86     $obj    = bless [], "Foo";
  87     $class  = blessed $obj;              # "Foo"
  88
  89 Take care when using this function simply as a truth test (such as in
  90 C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
  91
  92 =head2 refaddr
  93
  94     my $addr = refaddr( $ref );
  95
  96 If C<$ref> is reference, the internal memory address of the referenced value is
  97 returned as a plain integer. Otherwise C<undef> is returned.
  98
  99     $addr = refaddr "string";           # undef
 100     $addr = refaddr \$var;              # eg 12345678
 101     $addr = refaddr [];                 # eg 23456784
 102
 103     $obj  = bless {}, "Foo";
 104     $addr = refaddr $obj;               # eg 88123488
 105
 106 =head2 reftype
 107
 108     my $type = reftype( $ref );
 109
 110 If C<$ref> is a reference, the basic Perl type of the variable referenced is
 111 returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
 112 is returned.
 113
 114     $type = reftype "string";           # undef
 115     $type = reftype \$var;              # SCALAR
 116     $type = reftype [];                 # ARRAY
 117
 118     $obj  = bless {}, "Foo";
 119     $type = reftype $obj;               # HASH
 120
 121 Note that for internal reasons, all precompiled regexps (C<qr/.../>) are
 122 blessed references; thus C<ref()> returns the package name string C<"Regexp">
 123 on these but C<reftype()> will return the underlying C structure type of
 124 C<"REGEXP"> in all capitals.
 125
 126 =head2 weaken
 127
 128     weaken( $ref );
 129
 130 The lvalue C<$ref> will be turned into a weak reference. This means that it
 131 will not hold a reference count on the object it references. Also, when the
 132 reference count on that object reaches zero, the reference will be set to
 133 undef. This function mutates the lvalue passed as its argument and returns no
 134 value.
 135
 136 This is useful for keeping copies of references, but you don't want to prevent
 137 the object being DESTROY-ed at its usual time.
 138
 139     {
 140       my $var;
 141       $ref = \$var;
 142       weaken($ref);                     # Make $ref a weak reference
 143     }
 144     # $ref is now undef
 145
 146 Note that if you take a copy of a scalar with a weakened reference, the copy
 147 will be a strong reference.
 148
 149     my $var;
 150     my $foo = \$var;
 151     weaken($foo);                       # Make $foo a weak reference
 152     my $bar = $foo;                     # $bar is now a strong reference
 153
 154 This may be less obvious in other situations, such as C<grep()>, for instance
 155 when grepping through a list of weakened references to objects that may have
 156 been destroyed already:
 157
 158     @object = grep { defined } @object;
 159
 160 This will indeed remove all references to destroyed objects, but the remaining
 161 references to objects will be strong, causing the remaining objects to never be
 162 destroyed because there is now always a strong reference to them in the @object
 163 array.
 164
 165 =head2 unweaken
 166
 167     unweaken( $ref );
 168
 169 I<Since version 1.36.>
 170
 171 The lvalue C<REF> will be turned from a weak reference back into a normal
 172 (strong) reference again. This function mutates the lvalue passed as its
 173 argument and returns no value. This undoes the action performed by
 174 L</weaken>.
 175
 176 This function is slightly neater and more convenient than the
 177 otherwise-equivalent code
 178
 179     my $tmp = $REF;
 180     undef $REF;
 181     $REF = $tmp;
 182
 183 (because in particular, simply assigning a weak reference back to itself does
 184 not work to unweaken it; C<$REF = $REF> does not work).
 185
 186 =head2 isweak
 187
 188     my $weak = isweak( $ref );
 189
 190 Returns true if C<$ref> is a weak reference.
 191
 192     $ref  = \$foo;
 193     $weak = isweak($ref);               # false
 194     weaken($ref);
 195     $weak = isweak($ref);               # true
 196
 197 B<NOTE>: Copying a weak reference creates a normal, strong, reference.
 198
 199     $copy = $ref;
 200     $weak = isweak($copy);              # false
 201
 202 =head1 OTHER FUNCTIONS
 203
 204 =head2 dualvar
 205
 206     my $var = dualvar( $num, $string );
 207
 208 Returns a scalar that has the value C<$num> in a numeric context and the value
 209 C<$string> in a string context.
 210
 211     $foo = dualvar 10, "Hello";
 212     $num = $foo + 2;                    # 12
 213     $str = $foo . " world";             # Hello world
 214
 215 =head2 isdual
 216
 217     my $dual = isdual( $var );
 218
 219 I<Since version 1.26.>
 220
 221 If C<$var> is a scalar that has both numeric and string values, the result is
 222 true.
 223
 224     $foo = dualvar 86, "Nix";
 225     $dual = isdual($foo);               # true
 226
 227 Note that a scalar can be made to have both string and numeric content through
 228 standard operations:
 229
 230     $foo = "10";
 231     $dual = isdual($foo);               # false
 232     $bar = $foo + 0;
 233     $dual = isdual($foo);               # true
 234
 235 The C<$!> variable is commonly dual-valued, though it is also magical in other
 236 ways:
 237
 238     $! = 1;
 239     $dual = isdual($!);                 # true
 240     print("$!\n");                      # "Operation not permitted"
 241
 242 B<CAUTION>: This function is not as useful as it may seem. Dualvars are not a
 243 distinct concept in Perl, but a standard internal construct of all scalar
 244 values. Almost any value could be considered as a dualvar by this function
 245 through the course of normal operations.
 246
 247 =head2 isvstring
 248
 249     my $vstring = isvstring( $var );
 250
 251 If C<$var> is a scalar which was coded as a vstring, the result is true.
 252
 253     $vs   = v49.46.48;
 254     $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
 255     printf($fmt,$vs);
 256
 257 =head2 looks_like_number
 258
 259     my $isnum = looks_like_number( $var );
 260
 261 Returns true if perl thinks C<$var> is a number. See
 262 L<perlapi/looks_like_number>.
 263
 264 =head2 openhandle
 265
 266     my $fh = openhandle( $fh );
 267
 268 Returns C<$fh> itself, if C<$fh> may be used as a filehandle and is open, or if
 269 it is a tied handle. Otherwise C<undef> is returned.
 270
 271     $fh = openhandle(*STDIN);           # \*STDIN
 272     $fh = openhandle(\*STDIN);          # \*STDIN
 273     $fh = openhandle(*NOTOPEN);         # undef
 274     $fh = openhandle("scalar");         # undef
 275
 276 =head2 readonly
 277
 278     my $ro = readonly( $var );
 279
 280 Returns true if C<$var> is readonly.
 281
 282     sub foo { readonly($_[0]) }
 283
 284     $readonly = foo($bar);              # false
 285     $readonly = foo(0);                 # true
 286
 287 =head2 set_prototype
 288
 289     my $code = set_prototype( $code, $prototype );
 290
 291 Sets the prototype of the function given by the C<$code> reference, or deletes
 292 it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
 293
 294     set_prototype \&foo, '$$';
 295
 296 =head2 tainted
 297
 298     my $t = tainted( $var );
 299
 300 Return true if C<$var> is tainted.
 301
 302     $taint = tainted("constant");       # false
 303     $taint = tainted($ENV{PWD});        # true if running under -T
 304
 305 =head1 DIAGNOSTICS
 306
 307 Module use may give one of the following errors during import.
 308
 309 =over
 310
 311 =item Vstrings are not implemented in this version of perl
 312
 313 The version of perl that you are using does not implement Vstrings, to use
 314 L</isvstring> you will need to use a newer release of perl.
 315
 316 =back
 317
 318 =head1 KNOWN BUGS
 319
 320 There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
 321 show up as tests 8 and 9 of dualvar.t failing
 322
 323 =head1 SEE ALSO
 324
 325 L<List::Util>
 326
 327 =head1 COPYRIGHT
 328
 329 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
 330 This program is free software; you can redistribute it and/or modify it
 331 under the same terms as Perl itself.
 332
 333 Additionally L</weaken> and L</isweak> which are
 334
 335 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
 336 This program is free software; you can redistribute it and/or modify it
 337 under the same terms as perl itself.
 338
 339 Copyright (C) 2004, 2008  Matthijs van Duin.  All rights reserved.
 340 Copyright (C) 2014 cPanel Inc.  All rights reserved.
 341 This program is free software; you can redistribute it and/or modify
 342 it under the same terms as Perl itself.
 343
 344 =cut