Commit | Line | Data |
---|---|---|
b82b06b8 FC |
1 | package arybase; |
2 | ||
1ed44841 | 3 | our $VERSION = "0.08"; |
b82b06b8 FC |
4 | |
5 | require XSLoader; | |
6 | XSLoader::load(); # This returns true, which makes require happy. | |
7 | ||
8 | __END__ | |
9 | ||
10 | =head1 NAME | |
11 | ||
12 | arybase - Set indexing base via $[ | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | $[ = 1; | |
f703fc96 | 17 | |
b82b06b8 FC |
18 | @a = qw(Sun Mon Tue Wed Thu Fri Sat); |
19 | print $a[3], "\n"; # prints Tue | |
20 | ||
21 | =head1 DESCRIPTION | |
22 | ||
23 | This module implements Perl's C<$[> variable. You should not use it | |
24 | directly. | |
25 | ||
26 | Assigning to C<$[> has the I<compile-time> effect of making the assigned | |
27 | value, converted to an integer, the index of the first element in an array | |
28 | and the first character in a substring, within the enclosing lexical scope. | |
29 | ||
30 | It can be written with or without C<local>: | |
31 | ||
32 | $[ = 1; | |
33 | local $[ = 1; | |
34 | ||
35 | It only works if the assignment can be detected at compile time and the | |
36 | value assigned is constant. | |
37 | ||
38 | It affects the following operations: | |
39 | ||
40 | $array[$element] | |
41 | @array[@slice] | |
42 | $#array | |
43 | (list())[$slice] | |
44 | splice @array, $index, ... | |
45 | each @array | |
46 | keys @array | |
f703fc96 | 47 | |
b82b06b8 FC |
48 | index $string, $substring # return value is affected |
49 | pos $string | |
50 | substr $string, $offset, ... | |
51 | ||
52 | As with the default base of 0, negative bases count from the end of the | |
53 | array or string, starting with -1. If C<$[> is a positive integer, indices | |
54 | from C<$[-1> to 0 also count from the end. If C<$[> is negative (why would | |
55 | you do that, though?), indices from C<$[> to 0 count from the beginning of | |
56 | the string, but indices below C<$[> count from the end of the string as | |
57 | though the base were 0. | |
58 | ||
59 | Prior to Perl 5.16, indices from 0 to C<$[-1> inclusive, for positive | |
60 | values of C<$[>, behaved differently for different operations; negative | |
61 | indices equal to or greater than a negative C<$[> likewise behaved | |
62 | inconsistently. | |
63 | ||
64 | =head1 HISTORY | |
65 | ||
66 | Before Perl 5, C<$[> was a global variable that affected all array indices | |
67 | and string offsets. | |
68 | ||
69 | Starting with Perl 5, it became a file-scoped compile-time directive, which | |
70 | could be made lexically-scoped with C<local>. "File-scoped" means that the | |
71 | C<$[> assignment could leak out of the block in which occurred: | |
72 | ||
73 | { | |
74 | $[ = 1; | |
75 | # ... array base is 1 here ... | |
76 | } | |
77 | # ... still 1, but not in other files ... | |
78 | ||
79 | In Perl 5.10, it became strictly lexical. The file-scoped behaviour was | |
80 | removed (perhaps inadvertently, but what's done is done). | |
81 | ||
82 | In Perl 5.16, the implementation was moved into this module, and out of the | |
83 | Perl core. The erratic behaviour that occurred with indices between -1 and | |
84 | C<$[> was made consistent between operations, and, for negative bases, | |
85 | indices from C<$[> to -1 inclusive were made consistent between operations. | |
86 | ||
87 | =head1 BUGS | |
88 | ||
89 | Error messages that mention array indices use the 0-based index. | |
90 | ||
91 | C<keys $arrayref> and C<each $arrayref> do not respect the current value of | |
92 | C<$[>. | |
93 | ||
94 | =head1 SEE ALSO | |
95 | ||
96 | L<perlvar/"$[">, L<Array::Base> and L<String::Base>. | |
97 | ||
98 | =cut |