Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / man / man3 / Scalar::Util.3

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
Scalar::Util \- A selection of general\-utility scalar subroutines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
\&                        weaken isvstring looks_like_number set_prototype);
.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 "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($ref);               # 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]) }
.Ve
.Sp
.Vb 2
\&    $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
.Ve
.Sp
.Vb 2
\&    $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
.Ve
.Sp
.Vb 2
\&    $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, '$$';
.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 "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\-2005 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.