.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Scalar::Util 3"
.TH Scalar::Util 3 "2013-03-04" "perl v5.16.3" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Scalar::Util \- A selection of general\-utility scalar subroutines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
\& weaken isvstring looks_like_number set_prototype);
\& # and other useful utils appearing below
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Scalar::Util\*(C'\fR 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.
.PP
By default \f(CW\*(C`Scalar::Util\*(C'\fR does not export any subroutines. The
subroutines defined are
.IP "blessed \s-1EXPR\s0" 4
.IX Item "blessed EXPR"
If \s-1EXPR\s0 evaluates to a blessed reference the name of the package
that it is blessed into is returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
.Sp
.Vb 2
\& $scalar = "foo";
\& $class = blessed $scalar; # undef
\&
\& $ref = [];
\& $class = blessed $ref; # undef
\&
\& $obj = bless [], "Foo";
\& $class = blessed $obj; # "Foo"
.Ve
.IP "dualvar \s-1NUM\s0, \s-1STRING\s0" 4
.IX Item "dualvar NUM, STRING"
Returns a scalar that has the value \s-1NUM\s0 in a numeric context and the
value \s-1STRING\s0 in a string context.
.Sp
.Vb 3
\& $foo = dualvar 10, "Hello";
\& $num = $foo + 2; # 12
\& $str = $foo . " world"; # Hello world
.Ve
.IP "isvstring \s-1EXPR\s0" 4
.IX Item "isvstring EXPR"
If \s-1EXPR\s0 is a scalar which was coded as a vstring the result is true.
.Sp
.Vb 3
\& $vs = v49.46.48;
\& $fmt = isvstring($vs) ? "%vd" : "%s"; #true
\& printf($fmt,$vs);
.Ve
.IP "isweak \s-1EXPR\s0" 4
.IX Item "isweak EXPR"
If \s-1EXPR\s0 is a scalar which is a weak reference the result is true.
.Sp
.Vb 4
\& $ref = \e$foo;
\& $weak = isweak($ref); # false
\& weaken($ref);
\& $weak = isweak($ref); # true
.Ve
.Sp
\&\fB\s-1NOTE\s0\fR: Copying a weak reference creates a normal, strong, reference.
.Sp
.Vb 2
\& $copy = $ref;
\& $weak = isweak($copy); # false
.Ve
.IP "looks_like_number \s-1EXPR\s0" 4
.IX Item "looks_like_number EXPR"
Returns true if perl thinks \s-1EXPR\s0 is a number. See
\&\*(L"looks_like_number\*(R" in perlapi.
.IP "openhandle \s-1FH\s0" 4
.IX Item "openhandle FH"
Returns \s-1FH\s0 if \s-1FH\s0 may be used as a filehandle and is open, or \s-1FH\s0 is a tied
handle. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
.Sp
.Vb 4
\& $fh = openhandle(*STDIN); # \e*STDIN
\& $fh = openhandle(\e*STDIN); # \e*STDIN
\& $fh = openhandle(*NOTOPEN); # undef
\& $fh = openhandle("scalar"); # undef
.Ve
.IP "readonly \s-1SCALAR\s0" 4
.IX Item "readonly SCALAR"
Returns true if \s-1SCALAR\s0 is readonly.
.Sp
.Vb 1
\& sub foo { readonly($_[0]) }
\&
\& $readonly = foo($bar); # false
\& $readonly = foo(0); # true
.Ve
.IP "refaddr \s-1EXPR\s0" 4
.IX Item "refaddr EXPR"
If \s-1EXPR\s0 evaluates to a reference the internal memory address of
the referenced value is returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
.Sp
.Vb 3
\& $addr = refaddr "string"; # undef
\& $addr = refaddr \e$var; # eg 12345678
\& $addr = refaddr []; # eg 23456784
\&
\& $obj = bless {}, "Foo";
\& $addr = refaddr $obj; # eg 88123488
.Ve
.IP "reftype \s-1EXPR\s0" 4
.IX Item "reftype EXPR"
If \s-1EXPR\s0 evaluates to a reference the type of the variable referenced
is returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
.Sp
.Vb 3
\& $type = reftype "string"; # undef
\& $type = reftype \e$var; # SCALAR
\& $type = reftype []; # ARRAY
\&
\& $obj = bless {}, "Foo";
\& $type = reftype $obj; # HASH
.Ve
.IP "set_prototype \s-1CODEREF\s0, \s-1PROTOTYPE\s0" 4
.IX Item "set_prototype CODEREF, PROTOTYPE"
Sets the prototype of the given function, or deletes it if \s-1PROTOTYPE\s0 is
undef. Returns the \s-1CODEREF\s0.
.Sp
.Vb 1
\& set_prototype \e&foo, \*(Aq$$\*(Aq;
.Ve
.IP "tainted \s-1EXPR\s0" 4
.IX Item "tainted EXPR"
Return true if the result of \s-1EXPR\s0 is tainted
.Sp
.Vb 2
\& $taint = tainted("constant"); # false
\& $taint = tainted($ENV{PWD}); # true if running under \-T
.Ve
.IP "weaken \s-1REF\s0" 4
.IX Item "weaken REF"
\&\s-1REF\s0 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, \s-1REF\s0 will be set to undef.
.Sp
This is useful for keeping copies of references , but you don't want to
prevent the object being DESTROY-ed at its usual time.
.Sp
.Vb 6
\& {
\& my $var;
\& $ref = \e$var;
\& weaken($ref); # Make $ref a weak reference
\& }
\& # $ref is now undef
.Ve
.Sp
Note that if you take a copy of a scalar with a weakened reference,
the copy will be a strong reference.
.Sp
.Vb 4
\& my $var;
\& my $foo = \e$var;
\& weaken($foo); # Make $foo a weak reference
\& my $bar = $foo; # $bar is now a strong reference
.Ve
.Sp
This may be less obvious in other situations, such as \f(CW\*(C`grep()\*(C'\fR, for instance
when grepping through a list of weakened references to objects that may have
been destroyed already:
.Sp
.Vb 1
\& @object = grep { defined } @object;
.Ve
.Sp
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
\&\f(CW@object\fR array.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Module use may give one of the following errors during import.
.IP "Weak references are not implemented in the version of perl" 4
.IX 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
\&\f(CW\*(C`isweak\*(C'\fR or \f(CW\*(C`weaken\*(C'\fR you will need to use a newer release of perl.
.IP "Vstrings are not implemented in the version of perl" 4
.IX Item "Vstrings are not implemented in the version of perl"
The version of perl that you are using does not implement Vstrings, to use
\&\f(CW\*(C`isvstring\*(C'\fR you will need to use a newer release of perl.
.ie n .IP """NAME"" is only available with the \s-1XS\s0 version of Scalar::Util" 4
.el .IP "\f(CWNAME\fR is only available with the \s-1XS\s0 version of Scalar::Util" 4
.IX Item "NAME is only available with the XS version of Scalar::Util"
\&\f(CW\*(C`Scalar::Util\*(C'\fR 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 \s-1XS\s0 version of the extension.
.Sp
At present that list is: weaken, isweak, dualvar, isvstring, set_prototype
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
There is a bug in perl5.6.0 with \s-1UV\s0's that are >= 1<<31. This will
show up as tests 8 and 9 of dualvar.t failing
.SH "SEE ALSO"
.IX Header "SEE ALSO"
List::Util
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
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.
.PP
Except weaken and isweak which are
.PP
Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as perl itself.
y~or5J ={Eeu磝Qk ᯘG{?+]ן?wM3X^歌>{7پK>on\jy R g/=fOroNVv~Y+ NGuÝHWyw[eQʨSb> >}Gmx[o[<{Ϯ_qF vM IENDB`
