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