mingw/html/lib/constant.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>constant - Perl pragma to declare constants</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;constant - Perl pragma to declare constants</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="#notes">NOTES</a></li>
  26         <ul>
  27
  28                 <li><a href="#list_constants">List constants</a></li>
  29                 <li><a href="#defining_multiple_constants_at_once">Defining multiple constants at once</a></li>
  30                 <li><a href="#magic_constants">Magic constants</a></li>
  31         </ul>
  32
  33         <li><a href="#technical_notes">TECHNICAL NOTES</a></li>
  34         <li><a href="#bugs">BUGS</a></li>
  35         <li><a href="#author">AUTHOR</a></li>
  36         <li><a href="#copyright">COPYRIGHT</a></li>
  37 </ul>
  38 <!-- INDEX END -->
  39
  40 <hr />
  41 <p>
  42 </p>
  43 <h1><a name="name">NAME</a></h1>
  44 <p>constant - Perl pragma to declare constants</p>
  45 <p>
  46 </p>
  47 <hr />
  48 <h1><a name="synopsis">SYNOPSIS</a></h1>
  49 <pre>
  50     use constant PI    =&gt; 4 * atan2(1, 1);
  51     use constant DEBUG =&gt; 0;</pre>
  52 <pre>
  53     print &quot;Pi equals &quot;, PI, &quot;...\n&quot; if DEBUG;</pre>
  54 <pre>
  55     use constant {
  56         SEC   =&gt; 0,
  57         MIN   =&gt; 1,
  58         HOUR  =&gt; 2,
  59         MDAY  =&gt; 3,
  60         MON   =&gt; 4,
  61         YEAR  =&gt; 5,
  62         WDAY  =&gt; 6,
  63         YDAY  =&gt; 7,
  64         ISDST =&gt; 8,
  65     };</pre>
  66 <pre>
  67     use constant WEEKDAYS =&gt; qw(
  68         Sunday Monday Tuesday Wednesday Thursday Friday Saturday
  69     );</pre>
  70 <pre>
  71     print &quot;Today is &quot;, (WEEKDAYS)[ (localtime)[WDAY] ], &quot;.\n&quot;;</pre>
  72 <p>
  73 </p>
  74 <hr />
  75 <h1><a name="description">DESCRIPTION</a></h1>
  76 <p>This will declare a symbol to be a constant with the given value.</p>
  77 <p>When you declare a constant such as <code>PI</code> using the method shown
  78 above, each machine your script runs upon can have as many digits
  79 of accuracy as it can use. Also, your program will be easier to
  80 read, more likely to be maintained (and maintained correctly), and
  81 far less likely to send a space probe to the wrong planet because
  82 nobody noticed the one equation in which you wrote <code>3.14195</code>.</p>
  83 <p>When a constant is used in an expression, perl replaces it with its
  84 value at compile time, and may then optimize the expression further.
  85 In particular, any code in an <code>if (CONSTANT)</code> block will be optimized
  86 away if the constant is false.</p>
  87 <p>
  88 </p>
  89 <hr />
  90 <h1><a name="notes">NOTES</a></h1>
  91 <p>As with all <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> directives, defining a constant happens at
  92 compile time. Thus, it's probably not correct to put a constant
  93 declaration inside of a conditional statement (like <code>if ($foo)
  94 { use constant ... }</code>).</p>
  95 <p>Constants defined using this module cannot be interpolated into
  96 strings like variables.  However, concatenation works just fine:</p>
  97 <pre>
  98     print &quot;Pi equals PI...\n&quot;;        # WRONG: does not expand &quot;PI&quot;
  99     print &quot;Pi equals &quot;.PI.&quot;...\n&quot;;    # right</pre>
 100 <p>Even though a reference may be declared as a constant, the reference may
 101 point to data which may be changed, as this code shows.</p>
 102 <pre>
 103     use constant ARRAY =&gt; [ 1,2,3,4 ];
 104     print ARRAY-&gt;[1];
 105     ARRAY-&gt;[1] = &quot; be changed&quot;;
 106     print ARRAY-&gt;[1];</pre>
 107 <p>Dereferencing constant references incorrectly (such as using an array
 108 subscript on a constant hash reference, or vice versa) will be trapped at
 109 compile time.</p>
 110 <p>Constants belong to the package they are defined in.  To refer to a
 111 constant defined in another package, specify the full package name, as
 112 in <code>Some::Package::CONSTANT</code>.  Constants may be exported by modules,
 113 and may also be called as either class or instance methods, that is,
 114 as <code>Some::Package-&gt;CONSTANT</code> or as <code>$obj-&gt;CONSTANT</code> where
 115 <code>$obj</code> is an instance of <code>Some::Package</code>.  Subclasses may define
 116 their own constants to override those in their base class.</p>
 117 <p>The use of all caps for constant names is merely a convention,
 118 although it is recommended in order to make constants stand out
 119 and to help avoid collisions with other barewords, keywords, and
 120 subroutine names. Constant names must begin with a letter or
 121 underscore. Names beginning with a double underscore are reserved. Some
 122 poor choices for names will generate warnings, if warnings are enabled at
 123 compile time.</p>
 124 <p>
 125 </p>
 126 <h2><a name="list_constants">List constants</a></h2>
 127 <p>Constants may be lists of more (or less) than one value.  A constant
 128 with no values evaluates to <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> in scalar context.  Note that
 129 constants with more than one value do <em>not</em> return their last value in
 130 scalar context as one might expect.  They currently return the number
 131 of values, but <strong>this may change in the future</strong>.  Do not use constants
 132 with multiple values in scalar context.</p>
 133 <p><strong>NOTE:</strong> This implies that the expression defining the value of a
 134 constant is evaluated in list context.  This may produce surprises:</p>
 135 <pre>
 136     use constant TIMESTAMP =&gt; localtime;                # WRONG!
 137     use constant TIMESTAMP =&gt; scalar localtime;         # right</pre>
 138 <p>The first line above defines <code>TIMESTAMP</code> as a 9-element list, as
 139 returned by <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_localtime"><code>localtime()</code></a> in list context.  To set it to the string
 140 returned by <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_localtime"><code>localtime()</code></a> in scalar context, an explicit <code>scalar</code>
 141 keyword is required.</p>
 142 <p>List constants are lists, not arrays.  To index or slice them, they
 143 must be placed in parentheses.</p>
 144 <pre>
 145     my @workdays = WEEKDAYS[1 .. 5];            # WRONG!
 146     my @workdays = (WEEKDAYS)[1 .. 5];          # right</pre>
 147 <p>
 148 </p>
 149 <h2><a name="defining_multiple_constants_at_once">Defining multiple constants at once</a></h2>
 150 <p>Instead of writing multiple <code>use constant</code> statements, you may define
 151 multiple constants in a single statement by giving, instead of the
 152 constant name, a reference to a hash where the keys are the names of
 153 the constants to be defined.  Obviously, all constants defined using
 154 this method must have a single value.</p>
 155 <pre>
 156     use constant {
 157         FOO =&gt; &quot;A single value&quot;,
 158         BAR =&gt; &quot;This&quot;, &quot;won't&quot;, &quot;work!&quot;,        # Error!
 159     };</pre>
 160 <p>This is a fundamental limitation of the way hashes are constructed in
 161 Perl.  The error messages produced when this happens will often be
 162 quite cryptic -- in the worst case there may be none at all, and
 163 you'll only later find that something is broken.</p>
 164 <p>When defining multiple constants, you cannot use the values of other
 165 constants defined in the same declaration.  This is because the
 166 calling package doesn't know about any constant within that group
 167 until <em>after</em> the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> statement is finished.</p>
 168 <pre>
 169     use constant {
 170         BITMASK =&gt; 0xAFBAEBA8,
 171         NEGMASK =&gt; ~BITMASK,                    # Error!
 172     };</pre>
 173 <p>
 174 </p>
 175 <h2><a name="magic_constants">Magic constants</a></h2>
 176 <p>Magical values and references can be made into constants at compile
 177 time, allowing for way cool stuff like this.  (These error numbers
 178 aren't totally portable, alas.)</p>
 179 <pre>
 180     use constant E2BIG =&gt; ($! = 7);
 181     print   E2BIG, &quot;\n&quot;;        # something like &quot;Arg list too long&quot;
 182     print 0+E2BIG, &quot;\n&quot;;        # &quot;7&quot;</pre>
 183 <p>You can't produce a tied constant by giving a tied scalar as the
 184 value.  References to tied variables, however, can be used as
 185 constants without any problems.</p>
 186 <p>
 187 </p>
 188 <hr />
 189 <h1><a name="technical_notes">TECHNICAL NOTES</a></h1>
 190 <p>In the current implementation, scalar constants are actually
 191 inlinable subroutines. As of version 5.004 of Perl, the appropriate
 192 scalar constant is inserted directly in place of some subroutine
 193 calls, thereby saving the overhead of a subroutine call. See
 194 <a href="file://C|\msysgit\mingw\html/pod/perlsub.html#constant_functions">Constant Functions in the perlsub manpage</a> for details about how and when this
 195 happens.</p>
 196 <p>In the rare case in which you need to discover at run time whether a
 197 particular constant has been declared via this module, you may use
 198 this function to examine the hash <code>%constant::declared</code>. If the given
 199 constant name does not include a package name, the current package is
 200 used.</p>
 201 <pre>
 202     sub declared ($) {
 203         use constant 1.01;              # don't omit this!
 204         my $name = shift;
 205         $name =~ s/^::/main::/;
 206         my $pkg = caller;
 207         my $full_name = $name =~ /::/ ? $name : &quot;${pkg}::$name&quot;;
 208         $constant::declared{$full_name};
 209     }</pre>
 210 <p>
 211 </p>
 212 <hr />
 213 <h1><a name="bugs">BUGS</a></h1>
 214 <p>In the current version of Perl, list constants are not inlined
 215 and some symbols may be redefined without generating a warning.</p>
 216 <p>It is not possible to have a subroutine or a keyword with the same
 217 name as a constant in the same package. This is probably a Good Thing.</p>
 218 <p>A constant with a name in the list <code>STDIN STDOUT STDERR ARGV ARGVOUT
 219 ENV INC SIG</code> is not allowed anywhere but in package <code>main::</code>, for
 220 technical reasons.</p>
 221 <p>Unlike constants in some languages, these cannot be overridden
 222 on the command line or via environment variables.</p>
 223 <p>You can get into trouble if you use constants in a context which
 224 automatically quotes barewords (as is true for any subroutine call).
 225 For example, you can't say <code>$hash{CONSTANT}</code> because <code>CONSTANT</code> will
 226 be interpreted as a string.  Use <code>$hash{CONSTANT()}</code> or
 227 <code>$hash{+CONSTANT}</code> to prevent the bareword quoting mechanism from
 228 kicking in.  Similarly, since the <code>=&gt;</code> operator quotes a bareword
 229 immediately to its left, you have to say <code>CONSTANT() =&gt; 'value'</code>
 230 (or simply use a comma in place of the big arrow) instead of
 231 <code>CONSTANT =&gt; 'value'</code>.</p>
 232 <p>
 233 </p>
 234 <hr />
 235 <h1><a name="author">AUTHOR</a></h1>
 236 <p>Tom Phoenix, &lt;<em><a href="mailto:rootbeer@redcat.com">rootbeer@redcat.com</a></em>&gt;, with help from
 237 many other folks.</p>
 238 <p>Multiple constant declarations at once added by Casey West,
 239 &lt;<em><a href="mailto:casey@geeknest.com">casey@geeknest.com</a></em>&gt;.</p>
 240 <p>Documentation mostly rewritten by Ilmari Karonen,
 241 &lt;<em><a href="mailto:perl@itz.pp.sci.fi">perl@itz.pp.sci.fi</a></em>&gt;.</p>
 242 <p>
 243 </p>
 244 <hr />
 245 <h1><a name="copyright">COPYRIGHT</a></h1>
 246 <p>Copyright (C) 1997, 1999 Tom Phoenix</p>
 247 <p>This module is free software; you can redistribute it or modify it
 248 under the same terms as Perl itself.</p>
 249 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 250 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 251 <big><strong><span class="block">&nbsp;constant - Perl pragma to declare constants</span></strong></big>
 252 </td></tr>
 253 </table>
 254
 255 </body>
 256
 257 </html>