This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Fix several differences in the parsing of $.. and ${...}
[perl5.git] / pod / perldata.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perldata - Perl data types
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
7=head2 Variable names
d74e8afc 8X<variable, name> X<variable name> X<data type> X<type>
a0d0e21e 9
d55a8828 10Perl has three built-in data types: scalars, arrays of scalars, and
692ef166
SF
11associative arrays of scalars, known as "hashes". A scalar is a
12single string (of any size, limited only by the available memory),
13number, or a reference to something (which will be discussed
14in L<perlref>). Normal arrays are ordered lists of scalars indexed
15by number, starting with 0. Hashes are unordered collections of scalar
16values indexed by their associated string key.
a0d0e21e 17
d55a8828 18Values are usually referred to by name, or through a named reference.
b88cefa9
PP
19The first character of the name tells you to what sort of data
20structure it refers. The rest of the name tells you the particular
d55a8828
TC
21value to which it refers. Usually this name is a single I<identifier>,
22that is, a string beginning with a letter or underscore, and
23containing letters, underscores, and digits. In some cases, it may
24be a chain of identifiers, separated by C<::> (or by the slightly
25archaic C<'>); all but the last are interpreted as names of packages,
26to locate the namespace in which to look up the final identifier
27(see L<perlmod/Packages> for details). It's possible to substitute
28for a simple identifier, an expression that produces a reference
29to the value at runtime. This is described in more detail below
30and in L<perlref>.
d74e8afc 31X<identifier>
d55a8828
TC
32
33Perl also has its own built-in variables whose names don't follow
34these rules. They have strange names so they don't accidentally
35collide with one of your normal variables. Strings that match
36parenthesized parts of a regular expression are saved under names
37containing only digits after the C<$> (see L<perlop> and L<perlre>).
38In addition, several special variables that provide windows into
39the inner working of Perl have names containing punctuation characters
40and control characters. These are documented in L<perlvar>.
d74e8afc 41X<variable, built-in>
d55a8828
TC
42
43Scalar values are always named with '$', even when referring to a
44scalar that is part of an array or a hash. The '$' symbol works
45semantically like the English word "the" in that it indicates a
46single value is expected.
d74e8afc 47X<scalar>
a0d0e21e
LW
48
49 $days # the simple scalar value "days"
50 $days[28] # the 29th element of array @days
51 $days{'Feb'} # the 'Feb' value from hash %days
52 $#days # the last index of array @days
53
d55a8828 54Entire arrays (and slices of arrays and hashes) are denoted by '@',
3921068c 55which works much as the word "these" or "those" does in English,
d55a8828 56in that it indicates multiple values are expected.
d74e8afc 57X<array>
a0d0e21e
LW
58
59 @days # ($days[0], $days[1],... $days[n])
d55a8828 60 @days[3,4,5] # same as ($days[3],$days[4],$days[5])
a0d0e21e
LW
61 @days{'a','c'} # same as ($days{'a'},$days{'c'})
62
d55a8828 63Entire hashes are denoted by '%':
d74e8afc 64X<hash>
a0d0e21e
LW
65
66 %days # (key1, val1, key2, val2 ...)
67
d55a8828
TC
68In addition, subroutines are named with an initial '&', though this
69is optional when unambiguous, just as the word "do" is often redundant
70in English. Symbol table entries can be named with an initial '*',
71but you don't really care about that yet (if ever :-).
72
73Every variable type has its own namespace, as do several
74non-variable identifiers. This means that you can, without fear
75of conflict, use the same name for a scalar variable, an array, or
76a hash--or, for that matter, for a filehandle, a directory handle, a
77subroutine name, a format name, or a label. This means that $foo
78and @foo are two different variables. It also means that C<$foo[1]>
79is a part of @foo, not a part of $foo. This may seem a bit weird,
80but that's okay, because it is weird.
d74e8afc 81X<namespace>
d55a8828
TC
82
83Because variable references always start with '$', '@', or '%', the
84"reserved" words aren't in fact reserved with respect to variable
85names. They I<are> reserved with respect to labels and filehandles,
86however, which don't have an initial special character. You can't
87have a filehandle named "log", for instance. Hint: you could say
88C<open(LOG,'logfile')> rather than C<open(log,'logfile')>. Using
89uppercase filehandles also improves readability and protects you
90from conflict with future reserved words. Case I<is> significant--"FOO",
91"Foo", and "foo" are all different names. Names that start with a
92letter or underscore may also contain digits and underscores.
d74e8afc
ITB
93X<identifier, case sensitivity>
94X<case>
a0d0e21e
LW
95
96It is possible to replace such an alphanumeric name with an expression
d55a8828 97that returns a reference to the appropriate type. For a description
a0d0e21e
LW
98of this, see L<perlref>.
99
5f05dabc 100Names that start with a digit may contain only more digits. Names
9539f610
RGS
101that do not start with a letter, underscore, digit or a caret (i.e.
102a control character) are limited to one character, e.g., C<$%> or
103C<$$>. (Most of these one character names have a predefined
104significance to Perl. For instance, C<$$> is the current process
105id.)
a0d0e21e
LW
106
107=head2 Context
d74e8afc 108X<context> X<scalar context> X<list context>
a0d0e21e
LW
109
110The interpretation of operations and values in Perl sometimes depends
111on the requirements of the context around the operation or value.
d55a8828 112There are two major contexts: list and scalar. Certain operations
a0d0e21e 113return list values in contexts wanting a list, and scalar values
d55a8828
TC
114otherwise. If this is true of an operation it will be mentioned in
115the documentation for that operation. In other words, Perl overloads
a0d0e21e 116certain operations based on whether the expected return value is
d55a8828
TC
117singular or plural. Some words in English work this way, like "fish"
118and "sheep".
a0d0e21e
LW
119
120In a reciprocal fashion, an operation provides either a scalar or a
121list context to each of its arguments. For example, if you say
122
123 int( <STDIN> )
124
c47ff5f1 125the integer operation provides scalar context for the <>
a0d0e21e
LW
126operator, which responds by reading one line from STDIN and passing it
127back to the integer operation, which will then find the integer value
128of that line and return that. If, on the other hand, you say
129
130 sort( <STDIN> )
131
c47ff5f1 132then the sort operation provides list context for <>, which
a0d0e21e
LW
133will proceed to read every line available up to the end of file, and
134pass that list of lines back to the sort routine, which will then
135sort those lines and return them as a list to whatever the context
136of the sort was.
137
d55a8828
TC
138Assignment is a little bit special in that it uses its left argument
139to determine the context for the right argument. Assignment to a
140scalar evaluates the right-hand side in scalar context, while
141assignment to an array or hash evaluates the righthand side in list
142context. Assignment to a list (or slice, which is just a list
3921068c 143anyway) also evaluates the right-hand side in list context.
d55a8828 144
9f1b1f2d
GS
145When you use the C<use warnings> pragma or Perl's B<-w> command-line
146option, you may see warnings
d55a8828
TC
147about useless uses of constants or functions in "void context".
148Void context just means the value has been discarded, such as a
149statement containing only C<"fred";> or C<getpwuid(0);>. It still
150counts as scalar context for functions that care whether or not
151they're being called in list context.
152
153User-defined subroutines may choose to care whether they are being
154called in a void, scalar, or list context. Most subroutines do not
155need to bother, though. That's because both scalars and lists are
156automatically interpolated into lists. See L<perlfunc/wantarray>
157for how you would dynamically discern your function's calling
158context.
a0d0e21e
LW
159
160=head2 Scalar values
d74e8afc 161X<scalar> X<number> X<string> X<reference>
a0d0e21e 162
d55a8828
TC
163All data in Perl is a scalar, an array of scalars, or a hash of
164scalars. A scalar may contain one single value in any of three
165different flavors: a number, a string, or a reference. In general,
166conversion from one form to another is transparent. Although a
167scalar may not directly hold multiple values, it may contain a
168reference to an array or hash which in turn contains multiple values.
169
170Scalars aren't necessarily one thing or another. There's no place
171to declare a scalar variable to be of type "string", type "number",
172type "reference", or anything else. Because of the automatic
173conversion of scalars, operations that return scalars don't need
174to care (and in fact, cannot care) whether their caller is looking
175for a string, a number, or a reference. Perl is a contextually
176polymorphic language whose scalars can be strings, numbers, or
177references (which includes objects). Although strings and numbers
178are considered pretty much the same thing for nearly all purposes,
179references are strongly-typed, uncastable pointers with builtin
180reference-counting and destructor invocation.
a0d0e21e 181
32860eee
FC
182A scalar value is interpreted as FALSE in the Boolean sense
183if it is undefined, the null string or the number 0 (or its
184string equivalent, "0"), and TRUE if it is anything else. The
d55a8828
TC
185Boolean context is just a special kind of scalar context where no
186conversion to a string or a number is ever performed.
d74e8afc 187X<boolean> X<bool> X<true> X<false> X<truth>
d55a8828
TC
188
189There are actually two varieties of null strings (sometimes referred
190to as "empty" strings), a defined one and an undefined one. The
191defined version is just a string of length zero, such as C<"">.
192The undefined version is the value that indicates that there is
193no real value for something, such as when there was an error, or
194at end of file, or when you refer to an uninitialized variable or
195element of an array or hash. Although in early versions of Perl,
196an undefined scalar could become defined when first used in a
197place expecting a defined value, this no longer happens except for
198rare cases of autovivification as explained in L<perlref>. You can
199use the defined() operator to determine whether a scalar value is
200defined (this has no meaning on arrays or hashes), and the undef()
201operator to produce an undefined value.
d74e8afc 202X<defined> X<undefined> X<undef> X<null> X<string, null>
d55a8828
TC
203
204To find out whether a given string is a valid non-zero number, it's
205sometimes enough to test it against both numeric 0 and also lexical
692ef166
SF
206"0" (although this will cause noises if warnings are on). That's
207because strings that aren't numbers count as 0, just as they do in B<awk>:
4633a7c4
LW
208
209 if ($str == 0 && $str ne "0") {
210 warn "That doesn't look like a number";
54310121 211 }
4633a7c4 212
d55a8828
TC
213That method may be best because otherwise you won't treat IEEE
214notations like C<NaN> or C<Infinity> properly. At other times, you
215might prefer to determine whether string data can be used numerically
216by calling the POSIX::strtod() function or by inspecting your string
217with a regular expression (as documented in L<perlre>).
cb1a09d0
AD
218
219 warn "has nondigits" if /\D/;
5a964f20
TC
220 warn "not a natural number" unless /^\d+$/; # rejects -3
221 warn "not an integer" unless /^-?\d+$/; # rejects +3
222 warn "not an integer" unless /^[+-]?\d+$/;
223 warn "not a decimal number" unless /^-?\d+\.?\d*$/; # rejects .2
224 warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
54310121 225 warn "not a C float"
cb1a09d0
AD
226 unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;
227
d55a8828 228The length of an array is a scalar value. You may find the length
fc518ee5 229of array @days by evaluating C<$#days>, as in B<csh>. However, this
230isn't the length of the array; it's the subscript of the last element,
231which is a different value since there is ordinarily a 0th element.
d55a8828
TC
232Assigning to C<$#days> actually changes the length of the array.
233Shortening an array this way destroys intervening values. Lengthening
234an array that was previously shortened does not recover values
0568eccd 235that were in those elements.
d74e8afc 236X<$#> X<array, length>
d55a8828 237
210b36aa 238You can also gain some minuscule measure of efficiency by pre-extending
d55a8828
TC
239an array that is going to get big. You can also extend an array
240by assigning to an element that is off the end of the array. You
19799a22 241can truncate an array down to nothing by assigning the null list
d55a8828 242() to it. The following are equivalent:
a0d0e21e 243
84f709e7 244 @whatever = ();
3e3baf6d 245 $#whatever = -1;
a0d0e21e 246
d55a8828
TC
247If you evaluate an array in scalar context, it returns the length
248of the array. (Note that this is not true of lists, which return
249the last value, like the C comma operator, nor of built-in functions,
250which return whatever they feel like returning.) The following is
251always true:
d74e8afc 252X<array, length>
a0d0e21e 253
a0d0e21e
LW
254 scalar(@whatever) == $#whatever + 1;
255
d55a8828
TC
256Some programmers choose to use an explicit conversion so as to
257leave nothing to doubt:
4633a7c4
LW
258
259 $element_count = scalar(@whatever);
260
d55a8828
TC
261If you evaluate a hash in scalar context, it returns false if the
262hash is empty. If there are any key/value pairs, it returns true;
263more precisely, the value returned is a string consisting of the
264number of used buckets and the number of allocated buckets, separated
265by a slash. This is pretty much useful only to find out whether
266Perl's internal hashing algorithm is performing poorly on your data
267set. For example, you stick 10,000 things in a hash, but evaluating
268%HASH in scalar context reveals C<"1/16">, which means only one out
269of sixteen buckets has been touched, and presumably contains all
126c71c8 27010,000 of your items. This isn't supposed to happen. If a tied hash
6e4c4703
DM
271is evaluated in scalar context, the C<SCALAR> method is called (with a
272fallback to C<FIRSTKEY>).
d74e8afc 273X<hash, scalar context> X<hash, bucket> X<bucket>
a0d0e21e 274
5a964f20 275You can preallocate space for a hash by assigning to the keys() function.
65841adf 276This rounds up the allocated buckets to the next power of two:
5a964f20
TC
277
278 keys(%users) = 1000; # allocate 1024 buckets
279
a0d0e21e 280=head2 Scalar value constructors
d74e8afc 281X<scalar, literal> X<scalar, constant>
a0d0e21e 282
d55a8828 283Numeric literals are specified in any of the following floating point or
a0d0e21e
LW
284integer formats:
285
a0d0e21e
LW
286 12345
287 12345.67
d55a8828 288 .23E-10 # a very small number
928753ea 289 3.14_15_92 # a very important number
1d277562 290 4_294_967_296 # underscore for legibility
d55a8828 291 0xff # hex
928753ea 292 0xdead_beef # more hex
802a55ac 293 0377 # octal (only numbers, begins with 0)
d55a8828 294 0b011011 # binary
a0d0e21e 295
d4ced10d 296You are allowed to use underscores (underbars) in numeric literals
d823de2e
KW
297between digits for legibility (but not multiple underscores in a row:
298C<23__500> is not legal; C<23_500> is).
299You could, for example, group binary
d4ced10d
JH
300digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
301or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
d74e8afc 302X<number, literal>
1d277562 303
55497cff 304String literals are usually delimited by either single or double
d55a8828
TC
305quotes. They work much like quotes in the standard Unix shells:
306double-quoted string literals are subject to backslash and variable
19799a22
GS
307substitution; single-quoted strings are not (except for C<\'> and
308C<\\>). The usual C-style backslash rules apply for making
d55a8828 309characters such as newline, tab, etc., as well as some more exotic
4a4eefd0 310forms. See L<perlop/"Quote and Quote-like Operators"> for a list.
d74e8afc 311X<string, literal>
d55a8828
TC
312
313Hexadecimal, octal, or binary, representations in string literals
314(e.g. '0xff') are not automatically converted to their integer
315representation. The hex() and oct() functions make these conversions
316for you. See L<perlfunc/hex> and L<perlfunc/oct> for more details.
68dc0745 317
5f05dabc 318You can also embed newlines directly in your strings, i.e., they can end
a0d0e21e
LW
319on a different line than they begin. This is nice, but if you forget
320your trailing quote, the error will not be reported until Perl finds
321another line containing the quote character, which may be much further
322on in the script. Variable substitution inside strings is limited to
d55a8828 323scalar variables, arrays, and array or hash slices. (In other words,
b88cefa9 324names beginning with $ or @, followed by an optional bracketed
a0d0e21e 325expression as a subscript.) The following code segment prints out "The
184e9718 326price is $Z<>100."
d74e8afc 327X<interpolation>
a0d0e21e 328
692ef166
SF
329 $Price = '$100'; # not interpolated
330 print "The price is $Price.\n"; # interpolated
331
332There is no double interpolation in Perl, so the C<$100> is left as is.
a0d0e21e 333
7e4353e9
RGS
334By default floating point numbers substituted inside strings use the
335dot (".") as the decimal separator. If C<use locale> is in effect,
336and POSIX::setlocale() has been called, the character used for the
337decimal separator is affected by the LC_NUMERIC locale.
338See L<perllocale> and L<POSIX>.
339
d55a8828 340As in some shells, you can enclose the variable name in braces to
f1cbbd6e
GS
341disambiguate it from following alphanumerics (and underscores).
342You must also do
d55a8828
TC
343this when interpolating a variable into a string to separate the
344variable name from a following double-colon or an apostrophe, since
345these would be otherwise treated as a package separator:
d74e8afc 346X<interpolation>
d55a8828 347
84f709e7 348 $who = "Larry";
d55a8828
TC
349 print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
350 print "We use ${who}speak when ${who}'s here.\n";
351
352Without the braces, Perl would have looked for a $whospeak, a
353C<$who::0>, and a C<$who's> variable. The last two would be the
354$0 and the $s variables in the (presumably) non-existent package
355C<who>.
356
34a2706e
RS
357In fact, a simple identifier within such curlies is forced to be
358a string, and likewise within a hash subscript. Neither need
d55a8828
TC
359quoting. Our earlier example, C<$days{'Feb'}> can be written as
360C<$days{Feb}> and the quotes will be assumed automatically. But
719b43e8
RGS
361anything more complicated in the subscript will be interpreted as an
362expression. This means for example that C<$version{2.0}++> is
363equivalent to C<$version{2}++>, not to C<$version{'2.0'}++>.
d55a8828 364
692ef166 365=head3 Version Strings
d74e8afc 366X<version string> X<vstring> X<v-string>
692ef166 367
191d61a7 368A literal of the form C<v1.20.300.4000> is parsed as a string composed
6b2463a0
JH
369of characters with the specified ordinals. This form, known as
370v-strings, provides an alternative, more readable way to construct
371strings, rather than use the somewhat less readable interpolation form
372C<"\x{1}\x{14}\x{12c}\x{fa0}">. This is useful for representing
373Unicode strings, and for comparing version "numbers" using the string
374comparison operators, C<cmp>, C<gt>, C<lt> etc. If there are two or
375more dots in the literal, the leading C<v> may be omitted.
b9c62f5b 376
2575c402 377 print v9786; # prints SMILEY, "\x{263a}"
b9c62f5b
GS
378 print v102.111.111; # prints "foo"
379 print 102.111.111; # same
380
381Such literals are accepted by both C<require> and C<use> for
a32521b7
JD
382doing a version check. Note that using the v-strings for IPv4
383addresses is not portable unless you also use the
384inet_aton()/inet_ntoa() routines of the Socket package.
191d61a7 385
d32a65d2 386Note that since Perl 5.8.1 the single-number v-strings (like C<v65>)
8fa72689 387are not v-strings before the C<< => >> operator (which is usually used
3921068c 388to separate a hash key from a hash value); instead they are interpreted
15ecd4ae
JH
389as literal strings ('v65'). They were v-strings from Perl 5.6.0 to
390Perl 5.8.0, but that caused more confusion and breakage than good.
391Multi-number v-strings like C<v65.66> and C<65.66.67> continue to
392be v-strings always.
d32a65d2 393
692ef166 394=head3 Special Literals
d74e8afc
ITB
395X<special literal> X<__END__> X<__DATA__> X<END> X<DATA>
396X<end> X<data> X<^D> X<^Z>
692ef166 397
d55a8828 398The special literals __FILE__, __LINE__, and __PACKAGE__
68dc0745 399represent the current filename, line number, and package name at that
84ed0108
FC
400point in your program. __SUB__ gives a reference to the current
401subroutine. They may be used only as separate tokens; they
68dc0745 402will not be interpolated into strings. If there is no current package
3e92a254 403(due to an empty C<package;> directive), __PACKAGE__ is the undefined
8fdd8881 404value. (But the empty C<package;> is no longer supported, as of version
84ed0108
FC
4055.10.) Outside of a subroutine, __SUB__ is the undefined value. __SUB__
406is only available in 5.16 or higher, and only with a C<use v5.16> or
407C<use feature "current_sub"> declaration.
408X<__FILE__> X<__LINE__> X<__PACKAGE__> X<__SUB__>
409X<line> X<file> X<package>
3e92a254
GS
410
411The two control characters ^D and ^Z, and the tokens __END__ and __DATA__
412may be used to indicate the logical end of the script before the actual
413end of file. Any following text is ignored.
414
1bab44f9 415Text after __DATA__ may be read via the filehandle C<PACKNAME::DATA>,
3e92a254
GS
416where C<PACKNAME> is the package that was current when the __DATA__
417token was encountered. The filehandle is left open pointing to the
4d383607 418line after __DATA__. The program should C<close DATA> when it is done
9c205800
FC
419reading from it. (Leaving it open leaks filehandles if the module is
420reloaded for any reason, so it's a safer practice to close it.) For
4d383607
JK
421compatibility with older scripts written before __DATA__ was
422introduced, __END__ behaves like __DATA__ in the top level script (but
423not in files loaded with C<require> or C<do>) and leaves the remaining
424contents of the file accessible via C<main::DATA>.
3e92a254
GS
425
426See L<SelfLoader> for more description of __DATA__, and
d55a8828
TC
427an example of its use. Note that you cannot read from the DATA
428filehandle in a BEGIN block: the BEGIN block is executed as soon
429as it is seen (during compilation), at which point the corresponding
a00c1fe5 430__DATA__ (or __END__) token has not yet been seen.
a0d0e21e 431
692ef166 432=head3 Barewords
d74e8afc 433X<bareword>
692ef166 434
748a9306 435A word that has no other interpretation in the grammar will
a0d0e21e
LW
436be treated as if it were a quoted string. These are known as
437"barewords". As with filehandles and labels, a bareword that consists
438entirely of lowercase letters risks conflict with future reserved
9f1b1f2d 439words, and if you use the C<use warnings> pragma or the B<-w> switch,
05b4f1ec
FW
440Perl will warn you about any such words. Perl limits barewords (like
441identifiers) to about 250 characters. Future versions of Perl are likely
442to eliminate these arbitrary limitations.
443
444Some people may wish to outlaw barewords entirely. If you
a0d0e21e
LW
445say
446
447 use strict 'subs';
448
449then any bareword that would NOT be interpreted as a subroutine call
450produces a compile-time error instead. The restriction lasts to the
54310121 451end of the enclosing block. An inner block may countermand this
a0d0e21e
LW
452by saying C<no strict 'subs'>.
453
e2b457c0 454=head3 Array Interpolation
d74e8afc 455X<array, interpolation> X<interpolation, array> X<$">
692ef166 456
d55a8828
TC
457Arrays and slices are interpolated into double-quoted strings
458by joining the elements with the delimiter specified in the C<$">
692ef166
SF
459variable (C<$LIST_SEPARATOR> if "use English;" is specified),
460space by default. The following are equivalent:
a0d0e21e 461
84f709e7 462 $temp = join($", @ARGV);
a0d0e21e
LW
463 system "echo $temp";
464
465 system "echo @ARGV";
466
467Within search patterns (which also undergo double-quotish substitution)
d55a8828 468there is an unfortunate ambiguity: Is C</$foo[bar]/> to be interpreted as
a0d0e21e
LW
469C</${foo}[bar]/> (where C<[bar]> is a character class for the regular
470expression) or as C</${foo[bar]}/> (where C<[bar]> is the subscript to array
471@foo)? If @foo doesn't otherwise exist, then it's obviously a
472character class. If @foo exists, Perl takes a good guess about C<[bar]>,
473and is almost always right. If it does guess wrong, or if you're just
474plain paranoid, you can force the correct interpretation with curly
d55a8828 475braces as above.
a0d0e21e 476
7e3b091d 477If you're looking for the information on how to use here-documents,
210b36aa
AMS
478which used to be here, that's been moved to
479L<perlop/Quote and Quote-like Operators>.
be16fac9 480
a0d0e21e 481=head2 List value constructors
d74e8afc 482X<list>
a0d0e21e
LW
483
484List values are denoted by separating individual values by commas
485(and enclosing the list in parentheses where precedence requires it):
486
487 (LIST)
488
d55a8828
TC
489In a context not requiring a list value, the value of what appears
490to be a list literal is simply the value of the final element, as
491with the C comma operator. For example,
a0d0e21e 492
84f709e7 493 @foo = ('cc', '-E', $bar);
a0d0e21e 494
d55a8828 495assigns the entire list value to array @foo, but
a0d0e21e 496
84f709e7 497 $foo = ('cc', '-E', $bar);
a0d0e21e 498
d55a8828
TC
499assigns the value of variable $bar to the scalar variable $foo.
500Note that the value of an actual array in scalar context is the
501length of the array; the following assigns the value 3 to $foo:
a0d0e21e 502
84f709e7 503 @foo = ('cc', '-E', $bar);
7e3b091d 504 $foo = @foo; # $foo gets 3
a0d0e21e 505
54310121 506You may have an optional comma before the closing parenthesis of a
a0d0e21e
LW
507list literal, so that you can say:
508
84f709e7 509 @foo = (
7e3b091d
DA
510 1,
511 2,
512 3,
a0d0e21e
LW
513 );
514
d55a8828
TC
515To use a here-document to assign an array, one line per element,
516you might use an approach like this:
517
84f709e7 518 @sauces = <<End_Lines =~ m/(\S.*\S)/g;
7e3b091d
DA
519 normal tomato
520 spicy tomato
521 green chile
522 pesto
523 white wine
d55a8828
TC
524 End_Lines
525
a0d0e21e 526LISTs do automatic interpolation of sublists. That is, when a LIST is
d55a8828 527evaluated, each element of the list is evaluated in list context, and
a0d0e21e 528the resulting list value is interpolated into LIST just as if each
5a964f20 529individual element were a member of LIST. Thus arrays and hashes lose their
a0d0e21e
LW
530identity in a LIST--the list
531
5a964f20 532 (@foo,@bar,&SomeSub,%glarch)
a0d0e21e
LW
533
534contains all the elements of @foo followed by all the elements of @bar,
5a964f20 535followed by all the elements returned by the subroutine named SomeSub
d55a8828 536called in list context, followed by the key/value pairs of %glarch.
a0d0e21e
LW
537To make a list reference that does I<NOT> interpolate, see L<perlref>.
538
19799a22 539The null list is represented by (). Interpolating it in a list
a0d0e21e
LW
540has no effect. Thus ((),(),()) is equivalent to (). Similarly,
541interpolating an array with no elements is the same as if no
542array had been interpolated at that point.
543
c2689353 544This interpolation combines with the facts that the opening
ab1f959b 545and closing parentheses are optional (except when necessary for
c2689353 546precedence) and lists may end with an optional comma to mean that
8fdd8881 547multiple commas within lists are legal syntax. The list C<1,,3> is a
c2689353
NC
548concatenation of two lists, C<1,> and C<3>, the first of which ends
549with that optional comma. C<1,,3> is C<(1,),(3)> is C<1,3> (And
550similarly for C<1,,,3> is C<(1,),(,),3> is C<1,3> and so on.) Not that
551we'd advise you to use this obfuscation.
552
a0d0e21e 553A list value may also be subscripted like a normal array. You must
54310121 554put the list in parentheses to avoid ambiguity. For example:
a0d0e21e
LW
555
556 # Stat returns list value.
84f709e7 557 $time = (stat($file))[8];
a0d0e21e 558
4633a7c4 559 # SYNTAX ERROR HERE.
84f709e7 560 $time = stat($file)[8]; # OOPS, FORGOT PARENTHESES
4633a7c4 561
a0d0e21e 562 # Find a hex digit.
84f709e7 563 $hexdigit = ('a','b','c','d','e','f')[$digit-10];
a0d0e21e
LW
564
565 # A "reverse comma operator".
566 return (pop(@foo),pop(@foo))[0];
567
d55a8828
TC
568Lists may be assigned to only when each element of the list
569is itself legal to assign to:
a0d0e21e 570
84f709e7 571 ($a, $b, $c) = (1, 2, 3);
a0d0e21e 572
84f709e7 573 ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
a0d0e21e 574
d55a8828
TC
575An exception to this is that you may assign to C<undef> in a list.
576This is useful for throwing away some of the return values of a
577function:
578
84f709e7 579 ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
d55a8828
TC
580
581List assignment in scalar context returns the number of elements
4633a7c4
LW
582produced by the expression on the right side of the assignment:
583
7e3b091d
DA
584 $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2
585 $x = (($foo,$bar) = f()); # set $x to f()'s return count
4633a7c4 586
d55a8828 587This is handy when you want to do a list assignment in a Boolean
19799a22 588context, because most list functions return a null list when finished,
4633a7c4
LW
589which when assigned produces a 0, which is interpreted as FALSE.
590
ab1f959b
PN
591It's also the source of a useful idiom for executing a function or
592performing an operation in list context and then counting the number of
593return values, by assigning to an empty list and then using that
8fdd8881 594assignment in scalar context. For example, this code:
ab1f959b 595
84f709e7 596 $count = () = $string =~ /\d+/g;
ab1f959b
PN
597
598will place into $count the number of digit groups found in $string.
599This happens because the pattern match is in list context (since it
600is being assigned to the empty list), and will therefore return a list
8fdd8881 601of all matching parts of the string. The list assignment in scalar
ab1f959b 602context will translate that into the number of elements (here, the
8fdd8881 603number of times the pattern matched) and assign that to $count. Note
ab1f959b
PN
604that simply using
605
84f709e7 606 $count = $string =~ /\d+/g;
ab1f959b
PN
607
608would not have worked, since a pattern match in scalar context will
609only return true or false, rather than a count of matches.
610
611The final element of a list assignment may be an array or a hash:
a0d0e21e 612
84f709e7 613 ($a, $b, @rest) = split;
5a964f20 614 my($a, $b, %rest) = @_;
a0d0e21e 615
4633a7c4 616You can actually put an array or hash anywhere in the list, but the first one
d55a8828
TC
617in the list will soak up all the values, and anything after it will become
618undefined. This may be useful in a my() or local().
a0d0e21e 619
d55a8828
TC
620A hash can be initialized using a literal list holding pairs of
621items to be interpreted as a key and a value:
a0d0e21e
LW
622
623 # same as map assignment above
84f709e7 624 %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
a0d0e21e 625
d55a8828 626While literal lists and named arrays are often interchangeable, that's
4633a7c4
LW
627not the case for hashes. Just because you can subscript a list value like
628a normal array does not mean that you can subscript a list value as a
629hash. Likewise, hashes included as parts of other lists (including
630parameters lists and return lists from functions) always flatten out into
631key/value pairs. That's why it's good to use references sometimes.
a0d0e21e 632
c47ff5f1
GS
633It is often more readable to use the C<< => >> operator between key/value
634pairs. The C<< => >> operator is mostly just a more visually distinctive
b88cefa9 635synonym for a comma, but it also arranges for its left-hand operand to be
ac036724 636interpreted as a string if it's a bareword that would be a legal simple
8fdd8881
FC
637identifier. C<< => >> doesn't quote compound identifiers, that contain
638double colons. This makes it nice for initializing hashes:
a0d0e21e 639
84f709e7 640 %map = (
7e3b091d
DA
641 red => 0x00f,
642 blue => 0x0f0,
643 green => 0xf00,
4633a7c4
LW
644 );
645
646or for initializing hash references to be used as records:
647
84f709e7 648 $rec = {
7e3b091d
DA
649 witch => 'Mable the Merciless',
650 cat => 'Fluffy the Ferocious',
651 date => '10/31/1776',
4633a7c4
LW
652 };
653
654or for using call-by-named-parameter to complicated functions:
655
84f709e7 656 $field = $query->radio_group(
7e3b091d 657 name => 'group_name',
4633a7c4
LW
658 values => ['eenie','meenie','minie'],
659 default => 'meenie',
660 linebreak => 'true',
84f709e7 661 labels => \%labels
4633a7c4 662 );
cb1a09d0
AD
663
664Note that just because a hash is initialized in that order doesn't
665mean that it comes out in that order. See L<perlfunc/sort> for examples
666of how to arrange for an output ordering.
667
c9e3649f
LM
668If a key appears more than once in the initializer list of a hash, the last
669occurrence wins:
670
671 %circle = (
672 center => [5, 10],
673 center => [27, 9],
674 radius => 100,
675 color => [0xDF, 0xFF, 0x00],
676 radius => 54,
677 );
678
679 # same as
680 %circle = (
681 center => [27, 9],
682 color => [0xDF, 0xFF, 0x00],
683 radius => 54,
684 );
685
686This can be used to provide overridable configuration defaults:
687
688 # values in %args take priority over %config_defaults
689 %config = (%config_defaults, %args);
690
692ef166
SF
691=head2 Subscripts
692
aa80e1dc
FC
693An array can be accessed one scalar at a
694time by specifying a dollar sign (C<$>), then the
692ef166
SF
695name of the array (without the leading C<@>), then the subscript inside
696square brackets. For example:
697
698 @myarray = (5, 50, 500, 5000);
2adc35dd 699 print "The Third Element is", $myarray[2], "\n";
692ef166 700
8fdd8881 701The array indices start with 0. A negative subscript retrieves its
692ef166
SF
702value from the end. In our example, C<$myarray[-1]> would have been
7035000, and C<$myarray[-2]> would have been 500.
704
705Hash subscripts are similar, only instead of square brackets curly brackets
8fdd8881 706are used. For example:
692ef166
SF
707
708 %scientists =
709 (
710 "Newton" => "Isaac",
711 "Einstein" => "Albert",
712 "Darwin" => "Charles",
713 "Feynman" => "Richard",
714 );
715
716 print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";
717
aa80e1dc 718You can also subscript a list to get a single element from it:
d55a8828 719
aa80e1dc 720 $dir = (getpwnam("daemon"))[7];
d55a8828 721
9ed2a148
IG
722=head2 Multi-dimensional array emulation
723
724Multidimensional arrays may be emulated by subscripting a hash with a
8fdd8881 725list. The elements of the list are joined with the subscript separator
b8db74f2 726(see L<perlvar/$;>).
9ed2a148
IG
727
728 $foo{$a,$b,$c}
729
730is equivalent to
731
732 $foo{join($;, $a, $b, $c)}
733
734The default subscript separator is "\034", the same as SUBSEP in B<awk>.
735
aa80e1dc
FC
736=head2 Slices
737X<slice> X<array, slice> X<hash, slice>
d55a8828
TC
738
739A slice accesses several elements of a list, an array, or a hash
56d7751a
GS
740simultaneously using a list of subscripts. It's more convenient
741than writing out the individual elements as a list of separate
d55a8828
TC
742scalar values.
743
7e3b091d
DA
744 ($him, $her) = @folks[0,-1]; # array slice
745 @them = @folks[0 .. 3]; # array slice
746 ($who, $home) = @ENV{"USER", "HOME"}; # hash slice
747 ($uid, $dir) = (getpwnam("daemon"))[2,7]; # list slice
d55a8828
TC
748
749Since you can assign to a list of variables, you can also assign to
750an array or hash slice.
751
84f709e7 752 @days[3..5] = qw/Wed Thu Fri/;
d55a8828 753 @colors{'red','blue','green'}
7e3b091d 754 = (0xff0000, 0x0000ff, 0x00ff00);
d55a8828
TC
755 @folks[0, -1] = @folks[-1, 0];
756
757The previous assignments are exactly equivalent to
758
84f709e7
JH
759 ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
760 ($colors{'red'}, $colors{'blue'}, $colors{'green'})
7e3b091d 761 = (0xff0000, 0x0000ff, 0x00ff00);
88fd19e3 762 ($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);
d55a8828
TC
763
764Since changing a slice changes the original array or hash that it's
56d7751a
GS
765slicing, a C<foreach> construct will alter some--or even all--of the
766values of the array or hash.
d55a8828
TC
767
768 foreach (@array[ 4 .. 10 ]) { s/peter/paul/ }
769
00cb5da1 770 foreach (@hash{qw[key1 key2]}) {
7e3b091d
DA
771 s/^\s+//; # trim leading whitespace
772 s/\s+$//; # trim trailing whitespace
773 s/(\w+)/\u\L$1/g; # "titlecase" words
d55a8828
TC
774 }
775
08cd8952
GS
776A slice of an empty list is still an empty list. Thus:
777
84f709e7
JH
778 @a = ()[1,0]; # @a has no elements
779 @b = (@a)[0,1]; # @b has no elements
56d7751a
GS
780
781But:
782
84f709e7
JH
783 @a = (1)[1,0]; # @a has two elements
784 @b = (1,undef)[1,0,2]; # @b has three elements
08cd8952 785
f51152ef
AP
786More generally, a slice yields the empty list if it indexes only
787beyond the end of a list:
788
789 @a = (1)[ 1,2]; # @a has no elements
790 @b = (1)[0,1,2]; # @b has three elements
791
19799a22
GS
792This makes it easy to write loops that terminate when a null list
793is returned:
d55a8828 794
84f709e7 795 while ( ($home, $user) = (getpwent)[7,0]) {
7e3b091d 796 printf "%-8s %s\n", $user, $home;
d55a8828
TC
797 }
798
799As noted earlier in this document, the scalar sense of list assignment
800is the number of elements on the right-hand side of the assignment.
19799a22 801The null list contains no elements, so when the password file is
d55a8828
TC
802exhausted, the result is 0, not 2.
803
ad1de9c6
ML
804Slices in scalar context return the last item of the slice.
805
806 @a = qw/first second third/;
807 %h = (first => 'A', second => 'B');
808 $t = @a[0, 1]; # $t is now 'second'
0de10106 809 $u = @h{'first', 'second'}; # $u is now 'B'
ad1de9c6 810
d55a8828
TC
811If you're confused about why you use an '@' there on a hash slice
812instead of a '%', think of it like this. The type of bracket (square
813or curly) governs whether it's an array or a hash being looked at.
814On the other hand, the leading symbol ('$' or '@') on the array or
815hash indicates whether you are getting back a singular value (a
816scalar) or a plural one (a list).
817
5f05dabc 818=head2 Typeglobs and Filehandles
d74e8afc 819X<typeglob> X<filehandle> X<*>
cb1a09d0
AD
820
821Perl uses an internal type called a I<typeglob> to hold an entire
822symbol table entry. The type prefix of a typeglob is a C<*>, because
54310121 823it represents all types. This used to be the preferred way to
cb1a09d0 824pass arrays and hashes by reference into a function, but now that
5a964f20
TC
825we have real references, this is seldom needed.
826
827The main use of typeglobs in modern Perl is create symbol table aliases.
828This assignment:
829
830 *this = *that;
831
832makes $this an alias for $that, @this an alias for @that, %this an alias
833for %that, &this an alias for &that, etc. Much safer is to use a reference.
834This:
5f05dabc 835
5a964f20
TC
836 local *Here::blue = \$There::green;
837
838temporarily makes $Here::blue an alias for $There::green, but doesn't
839make @Here::blue an alias for @There::green, or %Here::blue an alias for
840%There::green, etc. See L<perlmod/"Symbol Tables"> for more examples
841of this. Strange though this may seem, this is the basis for the whole
84f709e7 842module import/export system.
5a964f20 843
d55a8828 844Another use for typeglobs is to pass filehandles into a function or
5a964f20
TC
845to create new filehandles. If you need to use a typeglob to save away
846a filehandle, do it this way:
5f05dabc 847
84f709e7 848 $fh = *STDOUT;
5f05dabc
PP
849
850or perhaps as a real reference, like this:
851
84f709e7 852 $fh = \*STDOUT;
5f05dabc 853
5a964f20
TC
854See L<perlsub> for examples of using these as indirect filehandles
855in functions.
856
857Typeglobs are also a way to create a local filehandle using the local()
858operator. These last until their block is exited, but may be passed back.
859For example:
5f05dabc
PP
860
861 sub newopen {
7e3b091d
DA
862 my $path = shift;
863 local *FH; # not my!
864 open (FH, $path) or return undef;
865 return *FH;
5f05dabc 866 }
84f709e7 867 $fh = newopen('/etc/passwd');
5f05dabc 868
d55a8828 869Now that we have the C<*foo{THING}> notation, typeglobs aren't used as much
5a964f20 870for filehandle manipulations, although they're still needed to pass brand
8fdd8881 871new file and directory handles into or out of functions. That's because
d55a8828
TC
872C<*HANDLE{IO}> only works if HANDLE has already been used as a handle.
873In other words, C<*FH> must be used to create new symbol table entries;
874C<*foo{THING}> cannot. When in doubt, use C<*FH>.
875
36392fcf
GS
876All functions that are capable of creating filehandles (open(),
877opendir(), pipe(), socketpair(), sysopen(), socket(), and accept())
878automatically create an anonymous filehandle if the handle passed to
8fdd8881 879them is an uninitialized scalar variable. This allows the constructs
36392fcf
GS
880such as C<open(my $fh, ...)> and C<open(local $fh,...)> to be used to
881create filehandles that will conveniently be closed automatically when
8fdd8881 882the scope ends, provided there are no other references to them. This
36392fcf
GS
883largely eliminates the need for typeglobs when opening filehandles
884that must be passed around, as in the following example:
885
886 sub myopen {
84f709e7 887 open my $fh, "@_"
7e3b091d
DA
888 or die "Can't open '@_': $!";
889 return $fh;
36392fcf
GS
890 }
891
892 {
893 my $f = myopen("</etc/motd");
7e3b091d
DA
894 print <$f>;
895 # $f implicitly closed here
36392fcf
GS
896 }
897
b92795fe
AMS
898Note that if an initialized scalar variable is used instead the
899result is different: C<my $fh='zzz'; open($fh, ...)> is equivalent
900to C<open( *{'zzz'}, ...)>.
d83fe814
AT
901C<use strict 'refs'> forbids such practice.
902
d55a8828
TC
903Another way to create anonymous filehandles is with the Symbol
904module or with the IO::Handle module and its ilk. These modules
905have the advantage of not hiding different types of the same name
66b6e4ad
KW
906during the local(). See the bottom of L<perlfunc/open> for an
907example.
d55a8828
TC
908
909=head1 SEE ALSO
910
911See L<perlvar> for a description of Perl's built-in variables and
912a discussion of legal variable names. See L<perlref>, L<perlsub>,
913and L<perlmod/"Symbol Tables"> for more discussion on typeglobs and
914the C<*foo{THING}> syntax.