local-lib5/man/man3/Scalar::Util.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Scalar::Util 3"
 127 .TH Scalar::Util 3 "2009-11-14" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Scalar::Util \- A selection of general\-utility scalar subroutines
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&    use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
 138 \&                        weaken isvstring looks_like_number set_prototype);
 139 \&                        # and other useful utils appearing below
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 \&\f(CW\*(C`Scalar::Util\*(C'\fR contains a selection of subroutines that people have
 144 expressed would be nice to have in the perl core, but the usage would
 145 not really be high enough to warrant the use of a keyword, and the size
 146 so small such that being individual extensions would be wasteful.
 147 .PP
 148 By default \f(CW\*(C`Scalar::Util\*(C'\fR does not export any subroutines. The
 149 subroutines defined are
 150 .IP "blessed \s-1EXPR\s0" 4
 151 .IX Item "blessed EXPR"
 152 If \s-1EXPR\s0 evaluates to a blessed reference the name of the package
 153 that it is blessed into is returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
 154 .Sp
 155 .Vb 2
 156 \&   $scalar = "foo";
 157 \&   $class  = blessed $scalar;           # undef
 158 \&
 159 \&   $ref    = [];
 160 \&   $class  = blessed $ref;              # undef
 161 \&
 162 \&   $obj    = bless [], "Foo";
 163 \&   $class  = blessed $obj;              # "Foo"
 164 .Ve
 165 .IP "dualvar \s-1NUM\s0, \s-1STRING\s0" 4
 166 .IX Item "dualvar NUM, STRING"
 167 Returns a scalar that has the value \s-1NUM\s0 in a numeric context and the
 168 value \s-1STRING\s0 in a string context.
 169 .Sp
 170 .Vb 3
 171 \&    $foo = dualvar 10, "Hello";
 172 \&    $num = $foo + 2;                    # 12
 173 \&    $str = $foo . " world";             # Hello world
 174 .Ve
 175 .IP "isvstring \s-1EXPR\s0" 4
 176 .IX Item "isvstring EXPR"
 177 If \s-1EXPR\s0 is a scalar which was coded as a vstring the result is true.
 178 .Sp
 179 .Vb 3
 180 \&    $vs   = v49.46.48;
 181 \&    $fmt  = isvstring($vs) ? "%vd" : "%s"; #true
 182 \&    printf($fmt,$vs);
 183 .Ve
 184 .IP "isweak \s-1EXPR\s0" 4
 185 .IX Item "isweak EXPR"
 186 If \s-1EXPR\s0 is a scalar which is a weak reference the result is true.
 187 .Sp
 188 .Vb 4
 189 \&    $ref  = \e$foo;
 190 \&    $weak = isweak($ref);               # false
 191 \&    weaken($ref);
 192 \&    $weak = isweak($ref);               # true
 193 .Ve
 194 .Sp
 195 \&\fB\s-1NOTE\s0\fR: Copying a weak reference creates a normal, strong, reference.
 196 .Sp
 197 .Vb 2
 198 \&    $copy = $ref;
 199 \&    $weak = isweak($copy);              # false
 200 .Ve
 201 .IP "looks_like_number \s-1EXPR\s0" 4
 202 .IX Item "looks_like_number EXPR"
 203 Returns true if perl thinks \s-1EXPR\s0 is a number. See
 204 \&\*(L"looks_like_number\*(R" in perlapi.
 205 .IP "openhandle \s-1FH\s0" 4
 206 .IX Item "openhandle FH"
 207 Returns \s-1FH\s0 if \s-1FH\s0 may be used as a filehandle and is open, or \s-1FH\s0 is a tied
 208 handle. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
 209 .Sp
 210 .Vb 4
 211 \&    $fh = openhandle(*STDIN);           # \e*STDIN
 212 \&    $fh = openhandle(\e*STDIN);          # \e*STDIN
 213 \&    $fh = openhandle(*NOTOPEN);         # undef
 214 \&    $fh = openhandle("scalar");         # undef
 215 .Ve
 216 .IP "readonly \s-1SCALAR\s0" 4
 217 .IX Item "readonly SCALAR"
 218 Returns true if \s-1SCALAR\s0 is readonly.
 219 .Sp
 220 .Vb 1
 221 \&    sub foo { readonly($_[0]) }
 222 \&
 223 \&    $readonly = foo($bar);              # false
 224 \&    $readonly = foo(0);                 # true
 225 .Ve
 226 .IP "refaddr \s-1EXPR\s0" 4
 227 .IX Item "refaddr EXPR"
 228 If \s-1EXPR\s0 evaluates to a reference the internal memory address of
 229 the referenced value is returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
 230 .Sp
 231 .Vb 3
 232 \&    $addr = refaddr "string";           # undef
 233 \&    $addr = refaddr \e$var;              # eg 12345678
 234 \&    $addr = refaddr [];                 # eg 23456784
 235 \&
 236 \&    $obj  = bless {}, "Foo";
 237 \&    $addr = refaddr $obj;               # eg 88123488
 238 .Ve
 239 .IP "reftype \s-1EXPR\s0" 4
 240 .IX Item "reftype EXPR"
 241 If \s-1EXPR\s0 evaluates to a reference the type of the variable referenced
 242 is returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
 243 .Sp
 244 .Vb 3
 245 \&    $type = reftype "string";           # undef
 246 \&    $type = reftype \e$var;              # SCALAR
 247 \&    $type = reftype [];                 # ARRAY
 248 \&
 249 \&    $obj  = bless {}, "Foo";
 250 \&    $type = reftype $obj;               # HASH
 251 .Ve
 252 .IP "set_prototype \s-1CODEREF\s0, \s-1PROTOTYPE\s0" 4
 253 .IX Item "set_prototype CODEREF, PROTOTYPE"
 254 Sets the prototype of the given function, or deletes it if \s-1PROTOTYPE\s0 is
 255 undef. Returns the \s-1CODEREF\s0.
 256 .Sp
 257 .Vb 1
 258 \&    set_prototype \e&foo, \*(Aq$$\*(Aq;
 259 .Ve
 260 .IP "tainted \s-1EXPR\s0" 4
 261 .IX Item "tainted EXPR"
 262 Return true if the result of \s-1EXPR\s0 is tainted
 263 .Sp
 264 .Vb 2
 265 \&    $taint = tainted("constant");       # false
 266 \&    $taint = tainted($ENV{PWD});        # true if running under \-T
 267 .Ve
 268 .IP "weaken \s-1REF\s0" 4
 269 .IX Item "weaken REF"
 270 \&\s-1REF\s0 will be turned into a weak reference. This means that it will not
 271 hold a reference count on the object it references. Also when the reference
 272 count on that object reaches zero, \s-1REF\s0 will be set to undef.
 273 .Sp
 274 This is useful for keeping copies of references , but you don't want to
 275 prevent the object being DESTROY-ed at its usual time.
 276 .Sp
 277 .Vb 6
 278 \&    {
 279 \&      my $var;
 280 \&      $ref = \e$var;
 281 \&      weaken($ref);                     # Make $ref a weak reference
 282 \&    }
 283 \&    # $ref is now undef
 284 .Ve
 285 .Sp
 286 Note that if you take a copy of a scalar with a weakened reference,
 287 the copy will be a strong reference.
 288 .Sp
 289 .Vb 4
 290 \&    my $var;
 291 \&    my $foo = \e$var;
 292 \&    weaken($foo);                       # Make $foo a weak reference
 293 \&    my $bar = $foo;                     # $bar is now a strong reference
 294 .Ve
 295 .Sp
 296 This may be less obvious in other situations, such as \f(CW\*(C`grep()\*(C'\fR, for instance
 297 when grepping through a list of weakened references to objects that may have
 298 been destroyed already:
 299 .Sp
 300 .Vb 1
 301 \&    @object = grep { defined } @object;
 302 .Ve
 303 .Sp
 304 This will indeed remove all references to destroyed objects, but the remaining
 305 references to objects will be strong, causing the remaining objects to never
 306 be destroyed because there is now always a strong reference to them in the
 307 \&\f(CW@object\fR array.
 308 .SH "DIAGNOSTICS"
 309 .IX Header "DIAGNOSTICS"
 310 Module use may give one of the following errors during import.
 311 .IP "Weak references are not implemented in the version of perl" 4
 312 .IX Item "Weak references are not implemented in the version of perl"
 313 The version of perl that you are using does not implement weak references, to use
 314 \&\f(CW\*(C`isweak\*(C'\fR or \f(CW\*(C`weaken\*(C'\fR you will need to use a newer release of perl.
 315 .IP "Vstrings are not implemented in the version of perl" 4
 316 .IX Item "Vstrings are not implemented in the version of perl"
 317 The version of perl that you are using does not implement Vstrings, to use
 318 \&\f(CW\*(C`isvstring\*(C'\fR you will need to use a newer release of perl.
 319 .ie n .IP """NAME"" is only available with the \s-1XS\s0 version of Scalar::Util" 4
 320 .el .IP "\f(CWNAME\fR is only available with the \s-1XS\s0 version of Scalar::Util" 4
 321 .IX Item "NAME is only available with the XS version of Scalar::Util"
 322 \&\f(CW\*(C`Scalar::Util\*(C'\fR contains both perl and C implementations of many of its functions
 323 so that those without access to a C compiler may still use it. However some of the functions
 324 are only available when a C compiler was available to compile the \s-1XS\s0 version of the extension.
 325 .Sp
 326 At present that list is: weaken, isweak, dualvar, isvstring, set_prototype
 327 .SH "KNOWN BUGS"
 328 .IX Header "KNOWN BUGS"
 329 There is a bug in perl5.6.0 with \s-1UV\s0's that are >= 1<<31. This will
 330 show up as tests 8 and 9 of dualvar.t failing
 331 .SH "SEE ALSO"
 332 .IX Header "SEE ALSO"
 333 List::Util
 334 .SH "COPYRIGHT"
 335 .IX Header "COPYRIGHT"
 336 Copyright (c) 1997\-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
 337 This program is free software; you can redistribute it and/or modify it
 338 under the same terms as Perl itself.
 339 .PP
 340 Except weaken and isweak which are
 341 .PP
 342 Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
 343 This program is free software; you can redistribute it and/or modify it
 344 under the same terms as perl itself.