summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Scalar/Util.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Scalar/Util.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/Scalar/Util.pm288
1 files changed, 153 insertions, 135 deletions
diff --git a/Master/tlpkg/tlperl/lib/Scalar/Util.pm b/Master/tlpkg/tlperl/lib/Scalar/Util.pm
index da229893495..4ab67f9aa07 100644
--- a/Master/tlpkg/tlperl/lib/Scalar/Util.pm
+++ b/Master/tlpkg/tlperl/lib/Scalar/Util.pm
@@ -1,8 +1,8 @@
-# Scalar::Util.pm
-#
# Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
# This program is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
+#
+# Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
package Scalar::Util;
@@ -12,21 +12,11 @@ require List::Util; # List::Util loads the XS
our @ISA = qw(Exporter);
our @EXPORT_OK = qw(
- blessed
- dualvar
- isdual
- isvstring
- isweak
- looks_like_number
- openhandle
- readonly
- refaddr
- reftype
- set_prototype
- tainted
- weaken
+ blessed refaddr reftype weaken unweaken isweak
+
+ dualvar isdual isvstring looks_like_number openhandle readonly set_prototype tainted
);
-our $VERSION = "1.27";
+our $VERSION = "1.38";
$VERSION = eval $VERSION;
our @EXPORT_FAIL;
@@ -72,56 +62,158 @@ Scalar::Util - A selection of general-utility scalar subroutines
=head1 DESCRIPTION
-C<Scalar::Util> contains a selection of subroutines that people have
-expressed would be nice to have in the perl core, but the usage would
-not really be high enough to warrant the use of a keyword, and the size
-so small such that being individual extensions would be wasteful.
+C<Scalar::Util> contains a selection of subroutines that people have expressed
+would be nice to have in the perl core, but the usage would not really be high
+enough to warrant the use of a keyword, and the size so small such that being
+individual extensions would be wasteful.
+
+By default C<Scalar::Util> does not export any subroutines.
+
+=cut
+
+=head1 FUNCTIONS FOR REFERENCES
+
+The following functions all perform some useful activity on reference values.
+
+=head2 $pkg = blessed( $ref )
+
+If C<$ref> is a blessed reference the name of the package that it is blessed
+into is returned. Otherwise C<undef> is returned.
+
+ $scalar = "foo";
+ $class = blessed $scalar; # undef
+
+ $ref = [];
+ $class = blessed $ref; # undef
+
+ $obj = bless [], "Foo";
+ $class = blessed $obj; # "Foo"
+
+Take care when using this function simply as a truth test (such as in
+C<if(blessed $ref)...>) because the package name C<"0"> is defined yet false.
+
+=head2 $addr = refaddr( $ref )
+
+If C<$ref> is reference the internal memory address of the referenced value is
+returned as a plain integer. Otherwise C<undef> is returned.
+
+ $addr = refaddr "string"; # undef
+ $addr = refaddr \$var; # eg 12345678
+ $addr = refaddr []; # eg 23456784
+
+ $obj = bless {}, "Foo";
+ $addr = refaddr $obj; # eg 88123488
+
+=head2 $type = reftype( $ref )
+
+If C<$ref> is a reference the basic Perl type of the variable referenced is
+returned as a plain string (such as C<ARRAY> or C<HASH>). Otherwise C<undef>
+is returned.
+
+ $type = reftype "string"; # undef
+ $type = reftype \$var; # SCALAR
+ $type = reftype []; # ARRAY
+
+ $obj = bless {}, "Foo";
+ $type = reftype $obj; # HASH
+
+=head2 weaken( REF )
-By default C<Scalar::Util> does not export any subroutines. The
-subroutines defined are
+The lvalue C<REF> will be turned into a weak reference. This means that it
+will not hold a reference count on the object it references. Also when the
+reference count on that object reaches zero, the reference will be set to
+undef. This function mutates the lvalue passed as its argument and returns no
+value.
-=over 4
+This is useful for keeping copies of references, but you don't want to prevent
+the object being DESTROY-ed at its usual time.
-=item blessed EXPR
+ {
+ my $var;
+ $ref = \$var;
+ weaken($ref); # Make $ref a weak reference
+ }
+ # $ref is now undef
-If EXPR evaluates to a blessed reference the name of the package
-that it is blessed into is returned. Otherwise C<undef> is returned.
+Note that if you take a copy of a scalar with a weakened reference, the copy
+will be a strong reference.
- $scalar = "foo";
- $class = blessed $scalar; # undef
+ my $var;
+ my $foo = \$var;
+ weaken($foo); # Make $foo a weak reference
+ my $bar = $foo; # $bar is now a strong reference
- $ref = [];
- $class = blessed $ref; # undef
+This may be less obvious in other situations, such as C<grep()>, for instance
+when grepping through a list of weakened references to objects that may have
+been destroyed already:
- $obj = bless [], "Foo";
- $class = blessed $obj; # "Foo"
+ @object = grep { defined } @object;
-=item dualvar NUM, STRING
+This will indeed remove all references to destroyed objects, but the remaining
+references to objects will be strong, causing the remaining objects to never be
+destroyed because there is now always a strong reference to them in the @object
+array.
+
+=head2 unweaken( REF )
+
+The lvalue C<REF> will be turned from a weak reference back into a normal
+(strong) reference again. This function mutates the lvalue passed as its
+argument and returns no value. This undoes the action performed by
+C<weaken()>.
+
+This function is slightly neater and more convenient than the
+otherwise-equivalent code
-Returns a scalar that has the value NUM in a numeric context and the
-value STRING in a string context.
+ my $tmp = $REF;
+ undef $REF;
+ $REF = $tmp;
+
+(because in particular, simply assigning a weak reference back to itself does
+not work to unweaken it; C<$REF = $REF> does not work).
+
+=head2 $weak = isweak( $ref )
+
+Returns true if C<$ref> is a weak reference.
+
+ $ref = \$foo;
+ $weak = isweak($ref); # false
+ weaken($ref);
+ $weak = isweak($ref); # true
+
+B<NOTE>: Copying a weak reference creates a normal, strong, reference.
+
+ $copy = $ref;
+ $weak = isweak($copy); # false
+
+=head1 OTHER FUNCTIONS
+
+=head2 $var = dualvar( $num, $string )
+
+Returns a scalar that has the value C<$num> in a numeric context and the value
+C<$string> in a string context.
$foo = dualvar 10, "Hello";
$num = $foo + 2; # 12
$str = $foo . " world"; # Hello world
-=item isdual EXPR
+=head2 $dual = isdual( $var )
-If EXPR is a scalar that is a dualvar, the result is true.
+If C<$var> is a scalar that has both numeric and string values, the result is
+true.
$foo = dualvar 86, "Nix";
$dual = isdual($foo); # true
-Note that a scalar can be made to have both string and numeric content
-through numeric operations:
+Note that a scalar can be made to have both string and numeric content through
+numeric operations:
$foo = "10";
$dual = isdual($foo); # false
$bar = $foo + 0;
$dual = isdual($foo); # true
-Note that although C<$!> appears to be dual-valued variable, it is
-actually implemented using a tied scalar:
+Note that although C<$!> appears to be dual-valued variable, it is actually
+implemented using a tied scalar:
$! = 1;
print("$!\n"); # "Operation not permitted"
@@ -132,127 +224,52 @@ You can capture its numeric and string content using:
$err = dualvar $!, $!;
$dual = isdual($err); # true
-=item isvstring EXPR
+=head2 $vstring = isvstring( $var )
-If EXPR is a scalar which was coded as a vstring the result is true.
+If C<$var> is a scalar which was coded as a vstring the result is true.
$vs = v49.46.48;
$fmt = isvstring($vs) ? "%vd" : "%s"; #true
printf($fmt,$vs);
-=item looks_like_number EXPR
+=head2 $isnum = looks_like_number( $var )
-Returns true if perl thinks EXPR is a number. See
+Returns true if perl thinks C<$var> is a number. See
L<perlapi/looks_like_number>.
-=item openhandle FH
+=head2 $fh = openhandle( $fh )
-Returns FH if FH may be used as a filehandle and is open, or FH is a tied
-handle. Otherwise C<undef> is returned.
+Returns C<$fh> itself if C<$fh> may be used as a filehandle and is open, or is
+is a tied handle. Otherwise C<undef> is returned.
$fh = openhandle(*STDIN); # \*STDIN
$fh = openhandle(\*STDIN); # \*STDIN
$fh = openhandle(*NOTOPEN); # undef
$fh = openhandle("scalar"); # undef
-=item readonly SCALAR
+=head2 $ro = readonly( $var )
-Returns true if SCALAR is readonly.
+Returns true if C<$var> is readonly.
sub foo { readonly($_[0]) }
$readonly = foo($bar); # false
$readonly = foo(0); # true
-=item refaddr EXPR
-
-If EXPR evaluates to a reference the internal memory address of
-the referenced value is returned. Otherwise C<undef> is returned.
-
- $addr = refaddr "string"; # undef
- $addr = refaddr \$var; # eg 12345678
- $addr = refaddr []; # eg 23456784
-
- $obj = bless {}, "Foo";
- $addr = refaddr $obj; # eg 88123488
-
-=item reftype EXPR
+=head2 $code = set_prototype( $code, $prototype )
-If EXPR evaluates to a reference the type of the variable referenced
-is returned. Otherwise C<undef> is returned.
-
- $type = reftype "string"; # undef
- $type = reftype \$var; # SCALAR
- $type = reftype []; # ARRAY
-
- $obj = bless {}, "Foo";
- $type = reftype $obj; # HASH
-
-=item set_prototype CODEREF, PROTOTYPE
-
-Sets the prototype of the given function, or deletes it if PROTOTYPE is
-undef. Returns the CODEREF.
+Sets the prototype of the function given by the C<$code> reference, or deletes
+it if C<$prototype> is C<undef>. Returns the C<$code> reference itself.
set_prototype \&foo, '$$';
-=item tainted EXPR
+=head2 $t = tainted( $var )
-Return true if the result of EXPR is tainted
+Return true if C<$var> is tainted.
$taint = tainted("constant"); # false
$taint = tainted($ENV{PWD}); # true if running under -T
-=item weaken REF
-
-REF will be turned into a weak reference. This means that it will not
-hold a reference count on the object it references. Also when the reference
-count on that object reaches zero, REF will be set to undef.
-
-This is useful for keeping copies of references , but you don't want to
-prevent the object being DESTROY-ed at its usual time.
-
- {
- my $var;
- $ref = \$var;
- weaken($ref); # Make $ref a weak reference
- }
- # $ref is now undef
-
-Note that if you take a copy of a scalar with a weakened reference,
-the copy will be a strong reference.
-
- my $var;
- my $foo = \$var;
- weaken($foo); # Make $foo a weak reference
- my $bar = $foo; # $bar is now a strong reference
-
-This may be less obvious in other situations, such as C<grep()>, for instance
-when grepping through a list of weakened references to objects that may have
-been destroyed already:
-
- @object = grep { defined } @object;
-
-This will indeed remove all references to destroyed objects, but the remaining
-references to objects will be strong, causing the remaining objects to never
-be destroyed because there is now always a strong reference to them in the
-@object array.
-
-=item isweak EXPR
-
-If EXPR is a scalar which is a weak reference the result is true.
-
- $ref = \$foo;
- $weak = isweak($ref); # false
- weaken($ref);
- $weak = isweak($ref); # true
-
-B<NOTE>: Copying a weak reference creates a normal, strong, reference.
-
- $copy = $ref;
- $weak = isweak($copy); # false
-
-=back
-
=head1 DIAGNOSTICS
Module use may give one of the following errors during import.
@@ -261,8 +278,8 @@ Module use may give one of the following errors during import.
=item Weak references are not implemented in the version of perl
-The version of perl that you are using does not implement weak references, to use
-C<isweak> or C<weaken> you will need to use a newer release of perl.
+The version of perl that you are using does not implement weak references, to
+use C<isweak> or C<weaken> you will need to use a newer release of perl.
=item Vstrings are not implemented in the version of perl
@@ -271,9 +288,10 @@ C<isvstring> you will need to use a newer release of perl.
=item C<NAME> is only available with the XS version of Scalar::Util
-C<Scalar::Util> contains both perl and C implementations of many of its functions
-so that those without access to a C compiler may still use it. However some of the functions
-are only available when a C compiler was available to compile the XS version of the extension.
+C<Scalar::Util> contains both perl and C implementations of many of its
+functions so that those without access to a C compiler may still use it.
+However some of the functions are only available when a C compiler was
+available to compile the XS version of the extension.
At present that list is: weaken, isweak, dualvar, isvstring, set_prototype