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