mingw/html/lib/Scalar/Util.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Scalar::Util - A selection of general-utility scalar subroutines</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Scalar::Util - A selection of general-utility scalar subroutines</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#known_bugs">KNOWN BUGS</a></li>
  26         <li><a href="#copyright">COPYRIGHT</a></li>
  27         <li><a href="#blatant_plug">BLATANT PLUG</a></li>
  28 </ul>
  29 <!-- INDEX END -->
  30
  31 <hr />
  32 <p>
  33 </p>
  34 <h1><a name="name">NAME</a></h1>
  35 <p>Scalar::Util - A selection of general-utility scalar subroutines</p>
  36 <p>
  37 </p>
  38 <hr />
  39 <h1><a name="synopsis">SYNOPSIS</a></h1>
  40 <pre>
  41     use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
  42                         weaken isvstring looks_like_number set_prototype);</pre>
  43 <p>
  44 </p>
  45 <hr />
  46 <h1><a name="description">DESCRIPTION</a></h1>
  47 <p><code>Scalar::Util</code> contains a selection of subroutines that people have
  48 expressed would be nice to have in the perl core, but the usage would
  49 not really be high enough to warrant the use of a keyword, and the size
  50 so small such that being individual extensions would be wasteful.</p>
  51 <p>By default <code>Scalar::Util</code> does not export any subroutines. The
  52 subroutines defined are</p>
  53 <dl>
  54 <dt><strong><a name="item_blessed">blessed EXPR</a></strong>
  55
  56 <dd>
  57 <p>If EXPR evaluates to a blessed reference the name of the package
  58 that it is blessed into is returned. Otherwise <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
  59 </dd>
  60 <dd>
  61 <pre>
  62    $scalar = &quot;foo&quot;;
  63    $class  = blessed $scalar;           # undef</pre>
  64 </dd>
  65 <dd>
  66 <pre>
  67    $ref    = [];
  68    $class  = blessed $ref;              # undef</pre>
  69 </dd>
  70 <dd>
  71 <pre>
  72    $obj    = bless [], &quot;Foo&quot;;
  73    $class  = blessed $obj;              # &quot;Foo&quot;</pre>
  74 </dd>
  75 </li>
  76 <dt><strong><a name="item_dualvar">dualvar NUM, STRING</a></strong>
  77
  78 <dd>
  79 <p>Returns a scalar that has the value NUM in a numeric context and the
  80 value STRING in a string context.</p>
  81 </dd>
  82 <dd>
  83 <pre>
  84     $foo = dualvar 10, &quot;Hello&quot;;
  85     $num = $foo + 2;                    # 12
  86     $str = $foo . &quot; world&quot;;             # Hello world</pre>
  87 </dd>
  88 </li>
  89 <dt><strong><a name="item_isvstring">isvstring EXPR</a></strong>
  90
  91 <dd>
  92 <p>If EXPR is a scalar which was coded as a vstring the result is true.</p>
  93 </dd>
  94 <dd>
  95 <pre>
  96     $vs   = v49.46.48;
  97     $fmt  = isvstring($vs) ? &quot;%vd&quot; : &quot;%s&quot;; #true
  98     printf($fmt,$vs);</pre>
  99 </dd>
 100 </li>
 101 <dt><strong><a name="item_isweak">isweak EXPR</a></strong>
 102
 103 <dd>
 104 <p>If EXPR is a scalar which is a weak reference the result is true.</p>
 105 </dd>
 106 <dd>
 107 <pre>
 108     $ref  = \$foo;
 109     $weak = isweak($ref);               # false
 110     weaken($ref);
 111     $weak = isweak($ref);               # true</pre>
 112 </dd>
 113 <dd>
 114 <p><strong>NOTE</strong>: Copying a weak reference creates a normal, strong, reference.</p>
 115 </dd>
 116 <dd>
 117 <pre>
 118     $copy = $ref;
 119     $weak = isweak($ref);               # false</pre>
 120 </dd>
 121 </li>
 122 <dt><strong><a name="item_looks_like_number">looks_like_number EXPR</a></strong>
 123
 124 <dd>
 125 <p>Returns true if perl thinks EXPR is a number. See
 126 <a href="file://C|\msysgit\mingw\html/pod/perlapi.html#looks_like_number">looks_like_number in the perlapi manpage</a>.</p>
 127 </dd>
 128 </li>
 129 <dt><strong><a name="item_openhandle">openhandle FH</a></strong>
 130
 131 <dd>
 132 <p>Returns FH if FH may be used as a filehandle and is open, or FH is a tied
 133 handle. Otherwise <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 134 </dd>
 135 <dd>
 136 <pre>
 137     $fh = openhandle(*STDIN);           # \*STDIN
 138     $fh = openhandle(\*STDIN);          # \*STDIN
 139     $fh = openhandle(*NOTOPEN);         # undef
 140     $fh = openhandle(&quot;scalar&quot;);         # undef
 141
 142 =item readonly SCALAR</pre>
 143 </dd>
 144 <dd>
 145 <p>Returns true if SCALAR is readonly.</p>
 146 </dd>
 147 <dd>
 148 <pre>
 149     sub foo { readonly($_[0]) }</pre>
 150 </dd>
 151 <dd>
 152 <pre>
 153     $readonly = foo($bar);              # false
 154     $readonly = foo(0);                 # true</pre>
 155 </dd>
 156 </li>
 157 <dt><strong><a name="item_refaddr">refaddr EXPR</a></strong>
 158
 159 <dd>
 160 <p>If EXPR evaluates to a reference the internal memory address of
 161 the referenced value is returned. Otherwise <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 162 </dd>
 163 <dd>
 164 <pre>
 165     $addr = refaddr &quot;string&quot;;           # undef
 166     $addr = refaddr \$var;              # eg 12345678
 167     $addr = refaddr [];                 # eg 23456784</pre>
 168 </dd>
 169 <dd>
 170 <pre>
 171     $obj  = bless {}, &quot;Foo&quot;;
 172     $addr = refaddr $obj;               # eg 88123488</pre>
 173 </dd>
 174 </li>
 175 <dt><strong><a name="item_reftype">reftype EXPR</a></strong>
 176
 177 <dd>
 178 <p>If EXPR evaluates to a reference the type of the variable referenced
 179 is returned. Otherwise <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 180 </dd>
 181 <dd>
 182 <pre>
 183     $type = reftype &quot;string&quot;;           # undef
 184     $type = reftype \$var;              # SCALAR
 185     $type = reftype [];                 # ARRAY</pre>
 186 </dd>
 187 <dd>
 188 <pre>
 189     $obj  = bless {}, &quot;Foo&quot;;
 190     $type = reftype $obj;               # HASH</pre>
 191 </dd>
 192 </li>
 193 <dt><strong><a name="item_set_prototype">set_prototype CODEREF, PROTOTYPE</a></strong>
 194
 195 <dd>
 196 <p>Sets the prototype of the given function, or deletes it if PROTOTYPE is
 197 undef. Returns the CODEREF.</p>
 198 </dd>
 199 <dd>
 200 <pre>
 201     set_prototype \&amp;foo, '$$';</pre>
 202 </dd>
 203 </li>
 204 <dt><strong><a name="item_tainted">tainted EXPR</a></strong>
 205
 206 <dd>
 207 <p>Return true if the result of EXPR is tainted</p>
 208 </dd>
 209 <dd>
 210 <pre>
 211     $taint = tainted(&quot;constant&quot;);       # false
 212     $taint = tainted($ENV{PWD});        # true if running under -T</pre>
 213 </dd>
 214 </li>
 215 <dt><strong><a name="item_weaken">weaken REF</a></strong>
 216
 217 <dd>
 218 <p>REF will be turned into a weak reference. This means that it will not
 219 hold a reference count on the object it references. Also when the reference
 220 count on that object reaches zero, REF will be set to undef.</p>
 221 </dd>
 222 <dd>
 223 <p>This is useful for keeping copies of references , but you don't want to
 224 prevent the object being DESTROY-ed at its usual time.</p>
 225 </dd>
 226 <dd>
 227 <pre>
 228     {
 229       my $var;
 230       $ref = \$var;
 231       weaken($ref);                     # Make $ref a weak reference
 232     }
 233     # $ref is now undef</pre>
 234 </dd>
 235 <dd>
 236 <p>Note that if you take a copy of a scalar with a weakened reference,
 237 the copy will be a strong reference.</p>
 238 </dd>
 239 <dd>
 240 <pre>
 241     my $var;
 242     my $foo = \$var;
 243     weaken($foo);                       # Make $foo a weak reference
 244     my $bar = $foo;                     # $bar is now a strong reference</pre>
 245 </dd>
 246 <dd>
 247 <p>This may be less obvious in other situations, such as <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_grep"><code>grep()</code></a>, for instance
 248 when grepping through a list of weakened references to objects that may have
 249 been destroyed already:</p>
 250 </dd>
 251 <dd>
 252 <pre>
 253     @object = grep { defined } @object;</pre>
 254 </dd>
 255 <dd>
 256 <p>This will indeed remove all references to destroyed objects, but the remaining
 257 references to objects will be strong, causing the remaining objects to never
 258 be destroyed because there is now always a strong reference to them in the
 259 @object array.</p>
 260 </dd>
 261 </li>
 262 </dl>
 263 <p>
 264 </p>
 265 <hr />
 266 <h1><a name="known_bugs">KNOWN BUGS</a></h1>
 267 <p>There is a bug in perl5.6.0 with UV's that are &gt;= 1&lt;&lt;31. This will
 268 show up as tests 8 and 9 of dualvar.t failing</p>
 269 <p>
 270 </p>
 271 <hr />
 272 <h1><a name="copyright">COPYRIGHT</a></h1>
 273 <p>Copyright (c) 1997-2005 Graham Barr &lt;<a href="mailto:gbarr@pobox.com">gbarr@pobox.com</a>&gt;. All rights reserved.
 274 This program is free software; you can redistribute it and/or modify it
 275 under the same terms as Perl itself.</p>
 276 <p>Except weaken and isweak which are</p>
 277 <p>Copyright (c) 1999 Tuomas J. Lukka &lt;<a href="mailto:lukka@iki.fi">lukka@iki.fi</a>&gt;. All rights reserved.
 278 This program is free software; you can redistribute it and/or modify it
 279 under the same terms as perl itself.</p>
 280 <p>
 281 </p>
 282 <hr />
 283 <h1><a name="blatant_plug">BLATANT PLUG</a></h1>
 284 <p>The weaken and isweak subroutines in this module and the patch to the core Perl
 285 were written in connection  with the APress book `Tuomas J. Lukka's Definitive
 286 Guide to Object-Oriented Programming in Perl', to avoid explaining why certain
 287 things would have to be done in cumbersome ways.</p>
 288 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 289 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 290 <big><strong><span class="block">&nbsp;Scalar::Util - A selection of general-utility scalar subroutines</span></strong></big>
 291 </td></tr>
 292 </table>
 293
 294 </body>
 295
 296 </html>