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

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