[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Scalar::Util.3

.\" 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-06-01" "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.
Commit	Line	Data
86530b38 AT	1	.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
	2	.\"
	3	.\" Standard preamble:
	4	.\" ========================================================================
	5	.de Sh \" Subsection heading
	6	.br
	7	.if t .Sp
	8	.ne 5
	9	.PP
	10	\fB\\$1\fR
	11	.PP
	12	..
	13	.de Sp \" Vertical space (when we can't use .PP)
	14	.if t .sp .5v
	15	.if n .sp
	16	..
	17	.de Vb \" Begin verbatim text
	18	.ft CW
	19	.nf
	20	.ne \\$1
	21	..
	22	.de Ve \" End verbatim text
	23	.ft R
	24	.fi
	25	..
	26	.\" Set up some character translations and predefined strings. \*(-- will
	27	.\" give an unbreakable dash, \(PI will give pi, \(L" will give a left
	28	.\" double quote, and \*(R" will give a right double quote. \| will give a
	29	.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
	30	.\" do unbreakable dashes and therefore won't be available. \(C` and \(C'
	31	.\" expand to `' in nroff, nothing in troff, for use with C<>.
	32	.tr \(W-\|\(bv\(Tr
	33	.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
	34	.ie n \{\
	35	. ds -- \(*W-
	36	. ds PI pi
	37	. if (\n(.H=4u)&(1m=24u) .ds -- \(W\h'-12u'\(W\h'-12u'-\" diablo 10 pitch
	38	. if (\n(.H=4u)&(1m=20u) .ds -- \(W\h'-12u'\(W\h'-8u'-\" diablo 12 pitch
	39	. ds L" ""
	40	. ds R" ""
	41	. ds C` ""
	42	. ds C' ""
	43	'br\}
	44	.el\{\
	45	. ds -- \\|\(em\\|
	46	. ds PI \(*p
	47	. ds L" ``
	48	. ds R" ''
	49	'br\}
	50	.\"
	51	.\" If the F register is turned on, we'll generate index entries on stderr for
	52	.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
	53	.\" entries marked with X<> in POD. Of course, you'll have to process the
	54	.\" output yourself in some meaningful fashion.
	55	.if \nF \{\
	56	. de IX
	57	. tm Index:\\$1\t\\n%\t"\\$2"
	58	..
	59	. nr % 0
	60	. rr F
	61	.\}
	62	.\"
	63	.\" For nroff, turn off justification. Always turn off hyphenation; it makes
	64	.\" way too many mistakes in technical documents.
65	.hy 0
66	.if n .na
67	.\"
68	.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69	.\" Fear. Run. Save yourself. No user-serviceable parts.
70	. \" fudge factors for nroff and troff
71	.if n \{\
72	. ds #H 0
73	. ds #V .8m
74	. ds #F .3m
75	. ds #[ \f1
76	. ds #] \fP
77	.\}
78	.if t \{\
79	. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80	. ds #V .6m
81	. ds #F 0
82	. ds #[ \&
83	. ds #] \&
84	.\}
85	. \" simple accents for nroff and troff
86	.if n \{\
87	. ds ' \&
88	. ds ` \&
89	. ds ^ \&
90	. ds , \&
91	. ds ~ ~
92	. ds /
93	.\}
94	.if t \{\
95	. ds ' \\k:\h'-(\\n(.wu8/10-\(#H)'\'\h"\|\\n:u"
96	. ds ` \\k:\h'-(\\n(.wu8/10-\(#H)'\`\h'\|\\n:u'
97	. ds ^ \\k:\h'-(\\n(.wu10/11-\(#H)'^\h'\|\\n:u'
98	. ds , \\k:\h'-(\\n(.wu*8/10)',\h'\|\\n:u'
99	. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'\|\\n:u'
100	. ds / \\k:\h'-(\\n(.wu8/10-\(#H)'\z\(sl\h'\|\\n:u'
101	.\}
102	. \" troff and (daisy-wheel) nroff accents
103	.ds : \\k:\h'-(\\n(.wu8/10-\(#H+.1m+\(#F)'\v'-\(#V'\z.\h'.2m+\(#F'.\h'\|\\n:u'\v'\(#V'
104	.ds 8 \h'\(#H'\(b\h'-\*(#H'
105	.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\(#H)/2u'\v'-.3n'\(#[\z\(de\v'.3n'\h'\|\\n:u'\*(#]
106	.ds d- \h'\(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\(#H'
107	.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'\|\\n:u'
108	.ds th \(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u2/3)'\s-1o\s+1\*(#]
109	.ds Th \(#[\s+2I\s-2\h'-\w'I'u3/5'\v'-.3m'o\v'.3m'\*(#]
110	.ds ae a\h'-(\w'a'u*4/10)'e
111	.ds Ae A\h'-(\w'A'u*4/10)'E
112	. \" corrections for vroff
113	.if v .ds ~ \\k:\h'-(\\n(.wu9/10-\(#H)'\s-2\u~\d\s+2\h'\|\\n:u'
114	.if v .ds ^ \\k:\h'-(\\n(.wu10/11-\(#H)'\v'-.4m'^\v'.4m'\h'\|\\n:u'
115	. \" for low resolution devices (crt and lpr)
116	.if \n(.H>23 .if \n(.V>19 \
117	\{\
118	. ds : e
119	. ds 8 ss
120	. ds o a
121	. ds d- d\h'-1'\(ga
122	. ds D- D\h'-1'\(hy
123	. ds th \o'bp'
124	. ds Th \o'LP'
125	. ds ae ae
126	. ds Ae AE
127	.\}
128	.rm #[ #] #H #V #F C
129	.\" ========================================================================
130	.\"
131	.IX Title "Scalar::Util 3"
132	.TH Scalar::Util 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide"
133	.SH "NAME"
134	Scalar::Util \- A selection of general\-utility scalar subroutines
135	.SH "SYNOPSIS"
136	.IX Header "SYNOPSIS"
137	.Vb 1
138	\& use Scalar::Util qw(blessed dualvar isweak readonly reftype tainted weaken);
139	.Ve
140	.SH "DESCRIPTION"
141	.IX Header "DESCRIPTION"
142	\&\f(CW\(C`Scalar::Util\(C'\fR contains a selection of subroutines that people have
143	expressed would be nice to have in the perl core, but the usage would
144	not really be high enough to warrant the use of a keyword, and the size
145	so small such that being individual extensions would be wasteful.
146	.PP
147	By default \f(CW\(C`Scalar::Util\(C'\fR does not export any subroutines. The
148	subroutines defined are
149	.IP "blessed \s-1EXPR\s0" 4
150	.IX Item "blessed EXPR"
151	If \s-1EXPR\s0 evaluates to a blessed reference the name of the package
152	that it is blessed into is returned. Otherwise \f(CW\(C`undef\(C'\fR is returned.
153	.Sp
154	.Vb 2
155	\& $scalar = "foo";
156	\& $class = blessed $scalar; # undef
157	.Ve
158	.Sp
159	.Vb 2
160	\& $ref = [];
161	\& $class = blessed $ref; # undef
162	.Ve
163	.Sp
164	.Vb 2
165	\& $obj = bless [], "Foo";
166	\& $class = blessed $obj; # "Foo"
167	.Ve
168	.IP "dualvar \s-1NUM\s0, \s-1STRING\s0" 4
169	.IX Item "dualvar NUM, STRING"
170	Returns a scalar that has the value \s-1NUM\s0 in a numeric context and the
171	value \s-1STRING\s0 in a string context.
172	.Sp
173	.Vb 3
174	\& $foo = dualvar 10, "Hello";
175	\& $num = $foo + 2; # 12
176	\& $str = $foo . " world"; # Hello world
177	.Ve
178	.IP "isweak \s-1EXPR\s0" 4
179	.IX Item "isweak EXPR"
180	If \s-1EXPR\s0 is a scalar which is a weak reference the result is true.
181	.Sp
182	.Vb 4
183	\& $ref = \e$foo;
184	\& $weak = isweak($ref); # false
185	\& weaken($ref);
186	\& $weak = isweak($ref); # true
187	.Ve
188	.IP "openhandle \s-1FH\s0" 4
189	.IX Item "openhandle FH"
190	Returns \s-1FH\s0 if \s-1FH\s0 may be used as a filehandle and is open, or \s-1FH\s0 is a tied
191	handle. Otherwise \f(CW\(C`undef\(C'\fR is returned.
192	.Sp
193	.Vb 4
194	\& $fh = openhandle(STDIN); # \eSTDIN
195	\& $fh = openhandle(\eSTDIN); # \eSTDIN
196	\& $fh = openhandle(*NOTOPEN); # undef
197	\& $fh = openhandle("scalar"); # undef
198	.Ve
199	.IP "readonly \s-1SCALAR\s0" 4
200	.IX Item "readonly SCALAR"
201	Returns true if \s-1SCALAR\s0 is readonly.
202	.Sp
203	.Vb 1
204	\& sub foo { readonly($_[0]) }
205	.Ve
206	.Sp
207	.Vb 2
208	\& $readonly = foo($bar); # false
209	\& $readonly = foo(0); # true
210	.Ve
211	.IP "reftype \s-1EXPR\s0" 4
212	.IX Item "reftype EXPR"
213	If \s-1EXPR\s0 evaluates to a reference the type of the variable referenced
214	is returned. Otherwise \f(CW\(C`undef\(C'\fR is returned.
215	.Sp
216	.Vb 3
217	\& $type = reftype "string"; # undef
218	\& $type = reftype \e$var; # SCALAR
219	\& $type = reftype []; # ARRAY
220	.Ve
221	.Sp
222	.Vb 2
223	\& $obj = bless {}, "Foo";
224	\& $type = reftype $obj; # HASH
225	.Ve
226	.IP "tainted \s-1EXPR\s0" 4
227	.IX Item "tainted EXPR"
228	Return true if the result of \s-1EXPR\s0 is tainted
229	.Sp
230	.Vb 2
231	\& $taint = tainted("constant"); # false
232	\& $taint = tainted($ENV{PWD}); # true if running under -T
233	.Ve
234	.IP "weaken \s-1REF\s0" 4
235	.IX Item "weaken REF"
236	\&\s-1REF\s0 will be turned into a weak reference. This means that it will not
237	hold a reference count on the object it references. Also when the reference
238	count on that object reaches zero, \s-1REF\s0 will be set to undef.
239	.Sp
240	This is useful for keeping copies of references , but you don't want to
241	prevent the object being DESTROY-ed at its usual time.
242	.Sp
243	.Vb 6
244	\& {
245	\& my $var;
246	\& $ref = \e$var;
247	\& weaken($ref); # Make $ref a weak reference
248	\& }
249	\& # $ref is now undef
250	.Ve
251	.SH "KNOWN BUGS"
252	.IX Header "KNOWN BUGS"
253	There is a bug in perl5.6.0 with \s-1UV\s0's that are >= 1<<31. This will
254	show up as tests 8 and 9 of dualvar.t failing
255	.SH "COPYRIGHT"
256	.IX Header "COPYRIGHT"
257	Copyright (c) 1997\-2001 Graham Barr <gbarr@pobox.com>. All rights reserved.
258	This program is free software; you can redistribute it and/or modify it
259	under the same terms as Perl itself.
260	.PP
261	Except weaken and isweak which are
262	.PP
263	Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
264	This program is free software; you can redistribute it and/or modify it
265	under the same terms as perl itself.
266	.SH "BLATANT PLUG"
267	.IX Header "BLATANT PLUG"
268	The weaken and isweak subroutines in this module and the patch to the core Perl
269	were written in connection with the APress book `Tuomas J. Lukka's Definitive
270	Guide to Object-Oriented Programming in Perl', to avoid explaining why certain
271	things would have to be done in cumbersome ways.