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