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