diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Scalar/Util.pm')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Scalar/Util.pm | 288 |
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 |