.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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. | will give a
.\" real vertical bar. \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "2002-11-24" "perl v5.8.0" "Perl Programmers Reference Guide"
.SH "NAME"
Scalar::Util \- A selection of general\-utility scalar subroutines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Scalar::Util qw(blessed dualvar isweak readonly reftype tainted weaken);
.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
.Ve
.Sp
.Vb 2
\& $ref = [];
\& $class = blessed $ref; # undef
.Ve
.Sp
.Vb 2
\& $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 "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
.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]) }
.Ve
.Sp
.Vb 2
\& $readonly = foo($bar); # false
\& $readonly = foo(0); # true
.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
.Ve
.Sp
.Vb 2
\& $obj = bless {}, "Foo";
\& $type = reftype $obj; # HASH
.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
.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 "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1997\-2001 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.
.SH "BLATANT PLUG"
.IX Header "BLATANT PLUG"
The weaken and isweak subroutines in this module and the patch to the core Perl
were written in connection with the APress book `Tuomas J. Lukka's Definitive
Guide to Object-Oriented Programming in Perl', to avoid explaining why certain
things would have to be done in cumbersome ways.
|
