| 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 | constant::import |
| 86 | 1 | 2 | 186µs | 186µs | constant::CORE:match (opcode) |
| 1 | 1 | 1 | 84µs | 84µs | constant::BEGIN@2 |
| 86 | 1 | 2 | 67µs | 67µs | constant::CORE:regcomp (opcode) |
| 1 | 1 | 1 | 13µs | 18µs | constant::BEGIN@3 |
| 1 | 1 | 1 | 11µs | 100µs | constant::BEGIN@4 |
| 1 | 1 | 1 | 10µs | 63µs | constant::BEGIN@6 |
| 1 | 1 | 1 | 9µs | 30µs | constant::BEGIN@38 |
| 1 | 1 | 1 | 9µs | 24µs | constant::BEGIN@101 |
| 0 | 0 | 0 | 0s | 0s | constant::__ANON__[:115] |
| 0 | 0 | 0 | 0s | 0s | constant::__ANON__[:119] |
| 0 | 0 | 0 | 0s | 0s | constant::__ANON__[:121] |
| 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 | 86 | 40µs | my $class = shift; | ||
| 30 | 86 | 11µs | return unless @_; # Ignore 'use constant;' | ||
| 31 | 86 | 8µs | my $constants; | ||
| 32 | 86 | 24µs | my $multiple = ref $_[0]; | ||
| 33 | 86 | 26µs | my $pkg = caller; | ||
| 34 | 86 | 3µs | my $symtab; | ||
| 35 | 86 | 39µs | my $str_end = $] >= 5.006 ? "\\z" : "\\Z"; | ||
| 36 | |||||
| 37 | 86 | 30µs | 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 | 86 | 108µs | $symtab = \%{$pkg . '::'}; | ||
| 40 | }; | ||||
| 41 | |||||
| 42 | 86 | 13µs | 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 | 86 | 131µs | $constants->{+shift} = undef; | ||
| 50 | } | ||||
| 51 | |||||
| 52 | 86 | 468µs | foreach my $name ( keys %$constants ) { | ||
| 53 | 86 | 11µs | unless (defined $name) { | ||
| 54 | require Carp; | ||||
| 55 | Carp::croak("Can't use undef as constant name"); | ||||
| 56 | } | ||||
| 57 | |||||
| 58 | # Normal constant name | ||||
| 59 | 86 | 648µs | 172 | 253µs | 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 | 89 | 462µ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 | 86 | 50µs | my $full_name = "${pkg}::$name"; | ||
| 103 | 86 | 137µs | $declared{$full_name}++; | ||
| 104 | 86 | 60µs | if ($multiple || @_ == 1) { | ||
| 105 | 86 | 21µs | my $scalar = $multiple ? $constants->{$name} : $_[0]; | ||
| 106 | 86 | 48µs | 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 | 86 | 265µs | 86 | 82µs | Internals::SvREADONLY($scalar, 1); # spent 82µs making 86 calls to Internals::SvREADONLY, avg 958ns/call |
| 112 | 86 | 57µs | $symtab->{$name} = \$scalar; | ||
| 113 | 86 | 268µs | 86 | 117µs | 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 |