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