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