File | /usr/local/lib/perl5/5.10.1/constant.pm |
Statements Executed | 2002 |
Statement Execution Time | 3.66ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
86 | 86 | 7 | 2.13ms | 2.58ms | import | constant::
86 | 1 | 2 | 186µs | 186µs | CORE:match (opcode) | constant::
1 | 1 | 1 | 84µs | 84µs | BEGIN@2 | constant::
86 | 1 | 2 | 67µs | 67µs | CORE:regcomp (opcode) | constant::
1 | 1 | 1 | 13µs | 18µs | BEGIN@3 | constant::
1 | 1 | 1 | 11µs | 100µs | BEGIN@4 | constant::
1 | 1 | 1 | 10µs | 63µs | BEGIN@6 | constant::
1 | 1 | 1 | 9µs | 30µs | BEGIN@38 | constant::
1 | 1 | 1 | 9µs | 24µs | BEGIN@101 | constant::
0 | 0 | 0 | 0s | 0s | __ANON__[:115] | constant::
0 | 0 | 0 | 0s | 0s | __ANON__[:119] | constant::
0 | 0 | 0 | 0s | 0s | __ANON__[:121] | constant::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package constant; | ||||
2 | 3 | 106µs | 1 | 84µs | # spent 84µs within constant::BEGIN@2 which was called
# once (84µs+0s) by Class::MOP::Method::Generated::BEGIN@15 at line 2 # spent 84µs making 1 call to constant::BEGIN@2 |
3 | 3 | 34µs | 2 | 22µs | # spent 18µs (13+5) within constant::BEGIN@3 which was called
# once (13µs+5µs) by Class::MOP::Method::Generated::BEGIN@15 at line 3 # spent 18µs making 1 call to constant::BEGIN@3
# spent 5µs making 1 call to strict::import |
4 | 3 | 54µs | 2 | 189µs | # spent 100µs (11+89) within constant::BEGIN@4 which was called
# once (11µs+89µs) by Class::MOP::Method::Generated::BEGIN@15 at line 4 # spent 100µs making 1 call to constant::BEGIN@4
# spent 89µs making 1 call to warnings::register::import |
5 | |||||
6 | 3 | 156µs | 2 | 116µs | # spent 63µs (10+53) within constant::BEGIN@6 which was called
# once (10µs+53µs) by Class::MOP::Method::Generated::BEGIN@15 at line 6 # spent 63µs making 1 call to constant::BEGIN@6
# spent 53µs making 1 call to vars::import |
7 | 1 | 1µs | $VERSION = '1.17'; | ||
8 | |||||
9 | #======================================================================= | ||||
10 | |||||
11 | # Some names are evil choices. | ||||
12 | 1 | 8µs | my %keywords = map +($_, 1), qw{ BEGIN INIT CHECK END DESTROY AUTOLOAD }; | ||
13 | 1 | 2µs | $keywords{UNITCHECK}++ if $] > 5.009; | ||
14 | |||||
15 | 1 | 7µs | my %forced_into_main = map +($_, 1), | ||
16 | qw{ STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG }; | ||||
17 | |||||
18 | 1 | 7µs | my %forbidden = (%keywords, %forced_into_main); | ||
19 | |||||
20 | #======================================================================= | ||||
21 | # import() - import symbols into user's namespace | ||||
22 | # | ||||
23 | # What we actually do is define a function in the caller's namespace | ||||
24 | # which returns the value. The function we create will normally | ||||
25 | # be inlined as a constant, thereby avoiding further sub calling | ||||
26 | # overhead. | ||||
27 | #======================================================================= | ||||
28 | # spent 2.58ms (2.13+453µs) within constant::import which was called 86 times, avg 30µs/call:
# once (48µs+36µs) by Class::MOP::Method::Generated::BEGIN@15 at line 15 of Class/MOP/Method/Generated.pm
# once (57µs+11µs) by Compress::Raw::Zlib::BEGIN@86 at line 86 of Compress/Raw/Zlib.pm
# once (62µs+5µs) by IO::Compress::Base::Common::BEGIN@473 at line 473 of IO/Compress/Base/Common.pm
# once (46µs+9µs) by URI::_punycode::BEGIN@14 at line 14 of URI/_punycode.pm
# once (40µs+11µs) by IO::Compress::Gzip::Constants::BEGIN@65 at line 65 of IO/Compress/Gzip/Constants.pm
# once (40µs+10µs) by Time::Local::BEGIN@28 at line 28 of Time/Local.pm
# once (42µs+8µs) by Compress::Raw::Zlib::BEGIN@70 at line 70 of Compress/Raw/Zlib.pm
# once (39µs+11µs) by IO::Compress::Base::Common::BEGIN@41 at line 41 of IO/Compress/Base/Common.pm
# once (38µs+7µs) by IO::Compress::Gzip::Constants::BEGIN@76 at line 76 of IO/Compress/Gzip/Constants.pm
# once (36µs+6µs) by IO::Compress::Gzip::Constants::BEGIN@77 at line 77 of IO/Compress/Gzip/Constants.pm
# once (33µs+6µs) by IO::Compress::Base::Common::BEGIN@463 at line 463 of IO/Compress/Base/Common.pm
# once (32µs+5µs) by Compress::Raw::Zlib::BEGIN@110 at line 110 of Compress/Raw/Zlib.pm
# once (29µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@67 at line 67 of IO/Compress/Gzip/Constants.pm
# once (28µs+7µs) by IO::Compress::Base::Common::BEGIN@461 at line 461 of IO/Compress/Base/Common.pm
# once (28µs+4µs) by IO::Compress::Base::Common::BEGIN@464 at line 464 of IO/Compress/Base/Common.pm
# once (26µs+6µs) by IO::Compress::Base::Common::BEGIN@42 at line 42 of IO/Compress/Base/Common.pm
# once (25µs+7µs) by IO::Compress::Base::Common::BEGIN@131 at line 131 of IO/Compress/Base/Common.pm
# once (25µs+6µs) by IO::Compress::Base::Common::BEGIN@130 at line 130 of IO/Compress/Base/Common.pm
# once (26µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@115 at line 115 of IO/Compress/Gzip/Constants.pm
# once (26µs+4µs) by U64::BEGIN@820 at line 820 of IO/Compress/Base/Common.pm
# once (26µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@73 at line 73 of IO/Compress/Gzip/Constants.pm
# once (26µs+4µs) by Compress::Raw::Zlib::BEGIN@102 at line 102 of Compress/Raw/Zlib.pm
# once (24µs+5µs) by U64::BEGIN@818 at line 818 of IO/Compress/Base/Common.pm
# once (24µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@66 at line 66 of IO/Compress/Gzip/Constants.pm
# once (25µs+4µs) by Compress::Raw::Zlib::BEGIN@71 at line 71 of Compress/Raw/Zlib.pm
# once (23µs+6µs) by IO::Compress::Base::Common::BEGIN@132 at line 132 of IO/Compress/Base/Common.pm
# once (25µs+4µs) by URI::_punycode::BEGIN@16 at line 16 of URI/_punycode.pm
# once (25µs+4µs) by URI::_punycode::BEGIN@20 at line 20 of URI/_punycode.pm
# once (24µs+5µs) by IO::Compress::Base::Common::BEGIN@43 at line 43 of IO/Compress/Base/Common.pm
# once (23µs+5µs) by IO::Uncompress::Base::BEGIN@14 at line 14 of IO/Uncompress/Base.pm
# once (23µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@89 at line 89 of IO/Compress/Gzip/Constants.pm
# once (23µs+5µs) by Compress::Raw::Zlib::BEGIN@83 at line 83 of Compress/Raw/Zlib.pm
# once (23µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@78 at line 78 of IO/Compress/Gzip/Constants.pm
# once (23µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@143 at line 143 of IO/Compress/Gzip/Constants.pm
# once (23µs+4µs) by Compress::Raw::Zlib::BEGIN@106 at line 106 of Compress/Raw/Zlib.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@87 at line 87 of IO/Compress/Gzip/Constants.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@80 at line 80 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by Compress::Raw::Zlib::BEGIN@111 at line 111 of Compress/Raw/Zlib.pm
# once (22µs+4µs) by IO::Compress::Base::Common::BEGIN@134 at line 134 of IO/Compress/Base/Common.pm
# once (22µs+5µs) by IO::Compress::Base::Common::BEGIN@462 at line 462 of IO/Compress/Base/Common.pm
# once (22µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@109 at line 109 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@69 at line 69 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@90 at line 90 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by Compress::Raw::Zlib::BEGIN@108 at line 108 of Compress/Raw/Zlib.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@70 at line 70 of IO/Compress/Gzip/Constants.pm
# once (22µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@84 at line 84 of IO/Compress/Gzip/Constants.pm
# once (21µs+5µs) by IO::Compress::Gzip::Constants::BEGIN@119 at line 119 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@75 at line 75 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@82 at line 82 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@86 at line 86 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by URI::_punycode::BEGIN@15 at line 15 of URI/_punycode.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@88 at line 88 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@101 at line 101 of Compress/Raw/Zlib.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@87 at line 87 of Compress/Raw/Zlib.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@85 at line 85 of Compress/Raw/Zlib.pm
# once (21µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@74 at line 74 of IO/Compress/Gzip/Constants.pm
# once (21µs+4µs) by IO::Compress::Base::Common::BEGIN@474 at line 474 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@115 at line 115 of Compress/Raw/Zlib.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@44 at line 44 of IO/Compress/Base/Common.pm
# once (21µs+4µs) by Compress::Raw::Zlib::BEGIN@112 at line 112 of Compress/Raw/Zlib.pm
# once (20µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@113 at line 113 of IO/Compress/Gzip/Constants.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@465 at line 465 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by Compress::Raw::Zlib::BEGIN@114 at line 114 of Compress/Raw/Zlib.pm
# once (20µs+4µs) by Compress::Raw::Zlib::BEGIN@84 at line 84 of Compress/Raw/Zlib.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@476 at line 476 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@471 at line 471 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@92 at line 92 of IO/Compress/Gzip/Constants.pm
# once (20µs+4µs) by Time::Local::BEGIN@29 at line 29 of Time/Local.pm
# once (20µs+4µs) by IO::Uncompress::Base::BEGIN@15 at line 15 of IO/Uncompress/Base.pm
# once (20µs+4µs) by Compress::Raw::Zlib::BEGIN@113 at line 113 of Compress/Raw/Zlib.pm
# once (20µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@111 at line 111 of IO/Compress/Gzip/Constants.pm
# once (20µs+4µs) by URI::_punycode::BEGIN@18 at line 18 of URI/_punycode.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@466 at line 466 of IO/Compress/Base/Common.pm
# once (20µs+4µs) by IO::Compress::Base::Common::BEGIN@470 at line 470 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by Compress::Raw::Zlib::BEGIN@103 at line 103 of Compress/Raw/Zlib.pm
# once (19µs+4µs) by U64::BEGIN@819 at line 819 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by Compress::Raw::Zlib::BEGIN@105 at line 105 of Compress/Raw/Zlib.pm
# once (19µs+4µs) by IO::Compress::Gzip::Constants::BEGIN@114 at line 114 of IO/Compress/Gzip/Constants.pm
# once (19µs+4µs) by URI::_punycode::BEGIN@17 at line 17 of URI/_punycode.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@469 at line 469 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by Time::Local::BEGIN@30 at line 30 of Time/Local.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@475 at line 475 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by Compress::Raw::Zlib::BEGIN@104 at line 104 of Compress/Raw/Zlib.pm
# once (19µs+4µs) by URI::_punycode::BEGIN@19 at line 19 of URI/_punycode.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@477 at line 477 of IO/Compress/Base/Common.pm
# once (19µs+4µs) by IO::Compress::Base::Common::BEGIN@478 at line 478 of IO/Compress/Base/Common.pm | ||||
29 | 1978 | 2.55ms | my $class = shift; | ||
30 | return unless @_; # Ignore 'use constant;' | ||||
31 | my $constants; | ||||
32 | my $multiple = ref $_[0]; | ||||
33 | my $pkg = caller; | ||||
34 | my $symtab; | ||||
35 | my $str_end = $] >= 5.006 ? "\\z" : "\\Z"; | ||||
36 | |||||
37 | if ($] > 5.009002) { | ||||
38 | 3 | 327µs | 2 | 51µs | # spent 30µs (9+21) within constant::BEGIN@38 which was called
# once (9µs+21µs) by Class::MOP::Method::Generated::BEGIN@15 at line 38 # spent 30µs making 1 call to constant::BEGIN@38
# spent 21µs making 1 call to strict::unimport |
39 | $symtab = \%{$pkg . '::'}; | ||||
40 | }; | ||||
41 | |||||
42 | if ( $multiple ) { | ||||
43 | if (ref $_[0] ne 'HASH') { | ||||
44 | require Carp; | ||||
45 | Carp::croak("Invalid reference type '".ref(shift)."' not 'HASH'"); | ||||
46 | } | ||||
47 | $constants = shift; | ||||
48 | } else { | ||||
49 | $constants->{+shift} = undef; | ||||
50 | } | ||||
51 | |||||
52 | foreach my $name ( keys %$constants ) { | ||||
53 | unless (defined $name) { | ||||
54 | require Carp; | ||||
55 | Carp::croak("Can't use undef as constant name"); | ||||
56 | } | ||||
57 | |||||
58 | # Normal constant name | ||||
59 | if ($name =~ /^_?[^\W_0-9]\w*$str_end/ and !$forbidden{$name}) { # spent 186µs making 86 calls to constant::CORE:match, avg 2µs/call
# spent 67µs making 86 calls to constant::CORE:regcomp, avg 781ns/call | ||||
60 | # Everything is okay | ||||
61 | |||||
62 | # Name forced into main, but we're not in main. Fatal. | ||||
63 | } elsif ($forced_into_main{$name} and $pkg ne 'main') { | ||||
64 | require Carp; | ||||
65 | Carp::croak("Constant name '$name' is forced into main::"); | ||||
66 | |||||
67 | # Starts with double underscore. Fatal. | ||||
68 | } elsif ($name =~ /^__/) { | ||||
69 | require Carp; | ||||
70 | Carp::croak("Constant name '$name' begins with '__'"); | ||||
71 | |||||
72 | # Maybe the name is tolerable | ||||
73 | } elsif ($name =~ /^[A-Za-z_]\w*$str_end/) { | ||||
74 | # Then we'll warn only if you've asked for warnings | ||||
75 | if (warnings::enabled()) { | ||||
76 | if ($keywords{$name}) { | ||||
77 | warnings::warn("Constant name '$name' is a Perl keyword"); | ||||
78 | } elsif ($forced_into_main{$name}) { | ||||
79 | warnings::warn("Constant name '$name' is " . | ||||
80 | "forced into package main::"); | ||||
81 | } | ||||
82 | } | ||||
83 | |||||
84 | # Looks like a boolean | ||||
85 | # use constant FRED == fred; | ||||
86 | } elsif ($name =~ /^[01]?$str_end/) { | ||||
87 | require Carp; | ||||
88 | if (@_) { | ||||
89 | Carp::croak("Constant name '$name' is invalid"); | ||||
90 | } else { | ||||
91 | Carp::croak("Constant name looks like boolean value"); | ||||
92 | } | ||||
93 | |||||
94 | } else { | ||||
95 | # Must have bad characters | ||||
96 | require Carp; | ||||
97 | Carp::croak("Constant name '$name' has invalid characters"); | ||||
98 | } | ||||
99 | |||||
100 | { | ||||
101 | 3 | 381µs | 2 | 38µs | # spent 24µs (9+14) within constant::BEGIN@101 which was called
# once (9µs+14µs) by Class::MOP::Method::Generated::BEGIN@15 at line 101 # spent 24µs making 1 call to constant::BEGIN@101
# spent 14µs making 1 call to strict::unimport |
102 | my $full_name = "${pkg}::$name"; | ||||
103 | $declared{$full_name}++; | ||||
104 | if ($multiple || @_ == 1) { | ||||
105 | my $scalar = $multiple ? $constants->{$name} : $_[0]; | ||||
106 | if ($symtab && !exists $symtab->{$name}) { | ||||
107 | # No typeglob yet, so we can use a reference as space- | ||||
108 | # efficient proxy for a constant subroutine | ||||
109 | # The check in Perl_ck_rvconst knows that inlinable | ||||
110 | # constants from cv_const_sv are read only. So we have to: | ||||
111 | Internals::SvREADONLY($scalar, 1); # spent 82µs making 86 calls to Internals::SvREADONLY, avg 958ns/call | ||||
112 | $symtab->{$name} = \$scalar; | ||||
113 | mro::method_changed_in($pkg); # spent 117µs making 86 calls to mro::method_changed_in, avg 1µs/call | ||||
114 | } else { | ||||
115 | *$full_name = sub () { $scalar }; | ||||
116 | } | ||||
117 | } elsif (@_) { | ||||
118 | my @list = @_; | ||||
119 | *$full_name = sub () { @list }; | ||||
120 | } else { | ||||
121 | *$full_name = sub () { }; | ||||
122 | } | ||||
123 | } | ||||
124 | } | ||||
125 | } | ||||
126 | |||||
127 | 1 | 25µs | 1; | ||
128 | |||||
129 | __END__ | ||||
130 | |||||
131 | =head1 NAME | ||||
132 | |||||
133 | constant - Perl pragma to declare constants | ||||
134 | |||||
135 | =head1 SYNOPSIS | ||||
136 | |||||
137 | use constant PI => 4 * atan2(1, 1); | ||||
138 | use constant DEBUG => 0; | ||||
139 | |||||
140 | print "Pi equals ", PI, "...\n" if DEBUG; | ||||
141 | |||||
142 | use constant { | ||||
143 | SEC => 0, | ||||
144 | MIN => 1, | ||||
145 | HOUR => 2, | ||||
146 | MDAY => 3, | ||||
147 | MON => 4, | ||||
148 | YEAR => 5, | ||||
149 | WDAY => 6, | ||||
150 | YDAY => 7, | ||||
151 | ISDST => 8, | ||||
152 | }; | ||||
153 | |||||
154 | use constant WEEKDAYS => qw( | ||||
155 | Sunday Monday Tuesday Wednesday Thursday Friday Saturday | ||||
156 | ); | ||||
157 | |||||
158 | print "Today is ", (WEEKDAYS)[ (localtime)[WDAY] ], ".\n"; | ||||
159 | |||||
160 | =head1 DESCRIPTION | ||||
161 | |||||
162 | This pragma allows you to declare constants at compile-time. | ||||
163 | |||||
164 | When you declare a constant such as C<PI> using the method shown | ||||
165 | above, each machine your script runs upon can have as many digits | ||||
166 | of accuracy as it can use. Also, your program will be easier to | ||||
167 | read, more likely to be maintained (and maintained correctly), and | ||||
168 | far less likely to send a space probe to the wrong planet because | ||||
169 | nobody noticed the one equation in which you wrote C<3.14195>. | ||||
170 | |||||
171 | When a constant is used in an expression, Perl replaces it with its | ||||
172 | value at compile time, and may then optimize the expression further. | ||||
173 | In particular, any code in an C<if (CONSTANT)> block will be optimized | ||||
174 | away if the constant is false. | ||||
175 | |||||
176 | =head1 NOTES | ||||
177 | |||||
178 | As with all C<use> directives, defining a constant happens at | ||||
179 | compile time. Thus, it's probably not correct to put a constant | ||||
180 | declaration inside of a conditional statement (like C<if ($foo) | ||||
181 | { use constant ... }>). | ||||
182 | |||||
183 | Constants defined using this module cannot be interpolated into | ||||
184 | strings like variables. However, concatenation works just fine: | ||||
185 | |||||
186 | print "Pi equals PI...\n"; # WRONG: does not expand "PI" | ||||
187 | print "Pi equals ".PI."...\n"; # right | ||||
188 | |||||
189 | Even though a reference may be declared as a constant, the reference may | ||||
190 | point to data which may be changed, as this code shows. | ||||
191 | |||||
192 | use constant ARRAY => [ 1,2,3,4 ]; | ||||
193 | print ARRAY->[1]; | ||||
194 | ARRAY->[1] = " be changed"; | ||||
195 | print ARRAY->[1]; | ||||
196 | |||||
197 | Dereferencing constant references incorrectly (such as using an array | ||||
198 | subscript on a constant hash reference, or vice versa) will be trapped at | ||||
199 | compile time. | ||||
200 | |||||
201 | Constants belong to the package they are defined in. To refer to a | ||||
202 | constant defined in another package, specify the full package name, as | ||||
203 | in C<Some::Package::CONSTANT>. Constants may be exported by modules, | ||||
204 | and may also be called as either class or instance methods, that is, | ||||
205 | as C<< Some::Package->CONSTANT >> or as C<< $obj->CONSTANT >> where | ||||
206 | C<$obj> is an instance of C<Some::Package>. Subclasses may define | ||||
207 | their own constants to override those in their base class. | ||||
208 | |||||
209 | The use of all caps for constant names is merely a convention, | ||||
210 | although it is recommended in order to make constants stand out | ||||
211 | and to help avoid collisions with other barewords, keywords, and | ||||
212 | subroutine names. Constant names must begin with a letter or | ||||
213 | underscore. Names beginning with a double underscore are reserved. Some | ||||
214 | poor choices for names will generate warnings, if warnings are enabled at | ||||
215 | compile time. | ||||
216 | |||||
217 | =head2 List constants | ||||
218 | |||||
219 | Constants may be lists of more (or less) than one value. A constant | ||||
220 | with no values evaluates to C<undef> in scalar context. Note that | ||||
221 | constants with more than one value do I<not> return their last value in | ||||
222 | scalar context as one might expect. They currently return the number | ||||
223 | of values, but B<this may change in the future>. Do not use constants | ||||
224 | with multiple values in scalar context. | ||||
225 | |||||
226 | B<NOTE:> This implies that the expression defining the value of a | ||||
227 | constant is evaluated in list context. This may produce surprises: | ||||
228 | |||||
229 | use constant TIMESTAMP => localtime; # WRONG! | ||||
230 | use constant TIMESTAMP => scalar localtime; # right | ||||
231 | |||||
232 | The first line above defines C<TIMESTAMP> as a 9-element list, as | ||||
233 | returned by C<localtime()> in list context. To set it to the string | ||||
234 | returned by C<localtime()> in scalar context, an explicit C<scalar> | ||||
235 | keyword is required. | ||||
236 | |||||
237 | List constants are lists, not arrays. To index or slice them, they | ||||
238 | must be placed in parentheses. | ||||
239 | |||||
240 | my @workdays = WEEKDAYS[1 .. 5]; # WRONG! | ||||
241 | my @workdays = (WEEKDAYS)[1 .. 5]; # right | ||||
242 | |||||
243 | =head2 Defining multiple constants at once | ||||
244 | |||||
245 | Instead of writing multiple C<use constant> statements, you may define | ||||
246 | multiple constants in a single statement by giving, instead of the | ||||
247 | constant name, a reference to a hash where the keys are the names of | ||||
248 | the constants to be defined. Obviously, all constants defined using | ||||
249 | this method must have a single value. | ||||
250 | |||||
251 | use constant { | ||||
252 | FOO => "A single value", | ||||
253 | BAR => "This", "won't", "work!", # Error! | ||||
254 | }; | ||||
255 | |||||
256 | This is a fundamental limitation of the way hashes are constructed in | ||||
257 | Perl. The error messages produced when this happens will often be | ||||
258 | quite cryptic -- in the worst case there may be none at all, and | ||||
259 | you'll only later find that something is broken. | ||||
260 | |||||
261 | When defining multiple constants, you cannot use the values of other | ||||
262 | constants defined in the same declaration. This is because the | ||||
263 | calling package doesn't know about any constant within that group | ||||
264 | until I<after> the C<use> statement is finished. | ||||
265 | |||||
266 | use constant { | ||||
267 | BITMASK => 0xAFBAEBA8, | ||||
268 | NEGMASK => ~BITMASK, # Error! | ||||
269 | }; | ||||
270 | |||||
271 | =head2 Magic constants | ||||
272 | |||||
273 | Magical values and references can be made into constants at compile | ||||
274 | time, allowing for way cool stuff like this. (These error numbers | ||||
275 | aren't totally portable, alas.) | ||||
276 | |||||
277 | use constant E2BIG => ($! = 7); | ||||
278 | print E2BIG, "\n"; # something like "Arg list too long" | ||||
279 | print 0+E2BIG, "\n"; # "7" | ||||
280 | |||||
281 | You can't produce a tied constant by giving a tied scalar as the | ||||
282 | value. References to tied variables, however, can be used as | ||||
283 | constants without any problems. | ||||
284 | |||||
285 | =head1 TECHNICAL NOTES | ||||
286 | |||||
287 | In the current implementation, scalar constants are actually | ||||
288 | inlinable subroutines. As of version 5.004 of Perl, the appropriate | ||||
289 | scalar constant is inserted directly in place of some subroutine | ||||
290 | calls, thereby saving the overhead of a subroutine call. See | ||||
291 | L<perlsub/"Constant Functions"> for details about how and when this | ||||
292 | happens. | ||||
293 | |||||
294 | In the rare case in which you need to discover at run time whether a | ||||
295 | particular constant has been declared via this module, you may use | ||||
296 | this function to examine the hash C<%constant::declared>. If the given | ||||
297 | constant name does not include a package name, the current package is | ||||
298 | used. | ||||
299 | |||||
300 | sub declared ($) { | ||||
301 | use constant 1.01; # don't omit this! | ||||
302 | my $name = shift; | ||||
303 | $name =~ s/^::/main::/; | ||||
304 | my $pkg = caller; | ||||
305 | my $full_name = $name =~ /::/ ? $name : "${pkg}::$name"; | ||||
306 | $constant::declared{$full_name}; | ||||
307 | } | ||||
308 | |||||
309 | =head1 CAVEATS | ||||
310 | |||||
311 | In the current version of Perl, list constants are not inlined | ||||
312 | and some symbols may be redefined without generating a warning. | ||||
313 | |||||
314 | It is not possible to have a subroutine or a keyword with the same | ||||
315 | name as a constant in the same package. This is probably a Good Thing. | ||||
316 | |||||
317 | A constant with a name in the list C<STDIN STDOUT STDERR ARGV ARGVOUT | ||||
318 | ENV INC SIG> is not allowed anywhere but in package C<main::>, for | ||||
319 | technical reasons. | ||||
320 | |||||
321 | Unlike constants in some languages, these cannot be overridden | ||||
322 | on the command line or via environment variables. | ||||
323 | |||||
324 | You can get into trouble if you use constants in a context which | ||||
325 | automatically quotes barewords (as is true for any subroutine call). | ||||
326 | For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will | ||||
327 | be interpreted as a string. Use C<$hash{CONSTANT()}> or | ||||
328 | C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from | ||||
329 | kicking in. Similarly, since the C<< => >> operator quotes a bareword | ||||
330 | immediately to its left, you have to say C<< CONSTANT() => 'value' >> | ||||
331 | (or simply use a comma in place of the big arrow) instead of | ||||
332 | C<< CONSTANT => 'value' >>. | ||||
333 | |||||
334 | =head1 SEE ALSO | ||||
335 | |||||
336 | L<Readonly> - Facility for creating read-only scalars, arrays, hashes. | ||||
337 | |||||
338 | L<Const> - Facility for creating read-only variables. Similar to C<Readonly>, | ||||
339 | but uses C<SvREADONLY> instead of C<tie>. | ||||
340 | |||||
341 | L<Attribute::Constant> - Make read-only variables via attribute | ||||
342 | |||||
343 | L<Scalar::Readonly> - Perl extension to the C<SvREADONLY> scalar flag | ||||
344 | |||||
345 | L<Hash::Util> - A selection of general-utility hash subroutines (mostly | ||||
346 | to lock/unlock keys and values) | ||||
347 | |||||
348 | =head1 BUGS | ||||
349 | |||||
350 | Please report any bugs or feature requests via the perlbug(1) utility. | ||||
351 | |||||
352 | =head1 AUTHORS | ||||
353 | |||||
354 | Tom Phoenix, E<lt>F<rootbeer@redcat.com>E<gt>, with help from | ||||
355 | many other folks. | ||||
356 | |||||
357 | Multiple constant declarations at once added by Casey West, | ||||
358 | E<lt>F<casey@geeknest.com>E<gt>. | ||||
359 | |||||
360 | Documentation mostly rewritten by Ilmari Karonen, | ||||
361 | E<lt>F<perl@itz.pp.sci.fi>E<gt>. | ||||
362 | |||||
363 | This program is maintained by the Perl 5 Porters. | ||||
364 | The CPAN distribution is maintained by SE<eacute>bastien Aperghis-Tramoni | ||||
365 | E<lt>F<sebastien@aperghis.net>E<gt>. | ||||
366 | |||||
367 | =head1 COPYRIGHT & LICENSE | ||||
368 | |||||
369 | Copyright (C) 1997, 1999 Tom Phoenix | ||||
370 | |||||
371 | This module is free software; you can redistribute it or modify it | ||||
372 | under the same terms as Perl itself. | ||||
373 | |||||
374 | =cut | ||||
# spent 186µs within constant::CORE:match which was called 86 times, avg 2µs/call:
# 86 times (186µs+0s) by constant::import at line 59 of constant.pm, avg 2µs/call | |||||
# spent 67µs within constant::CORE:regcomp which was called 86 times, avg 781ns/call:
# 86 times (67µs+0s) by constant::import at line 59 of constant.pm, avg 781ns/call |