Debian Codegraph @

upstream/fedora-44/man1/perllol.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLLOL 1"
61 .TH PERLLOL 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perllol \- Manipulating Arrays of Arrays in Perl
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 .SS "Declaration and Access of Arrays of Arrays"
71 .IX Subsection "Declaration and Access of Arrays of Arrays"
72 The simplest two\-level data structure to build in Perl is an array of
73 arrays, sometimes casually called a list of lists. It\*(Aqs reasonably easy to
74 understand, and almost everything that applies here will also be applicable
75 later on with the fancier data structures.
76 .PP
77 An array of an array is just a regular old array \f(CW@AoA\fR that you can
78 get at with two subscripts, like \f(CW\*(C`$AoA[3][2]\*(C'\fR. Here\*(Aqs a declaration
79 of the array:
80 .PP
81 .Vb 1
82 \& use v5.10; # so we can use say()
83 \&
84 \& # assign to our array, an array of array references
85 \& @AoA = (
86 \& [ "fred", "barney", "pebbles", "bambam", "dino", ],
87 \& [ "george", "jane", "elroy", "judy", ],
88 \& [ "homer", "bart", "marge", "maggie", ],
89 \& );
90 \& say $AoA[2][1];
91 \& bart
92 .Ve
93 .PP
94 Now you should be very careful that the outer bracket type
95 is a round one, that is, a parenthesis. That\*(Aqs because you\*(Aqre assigning to
96 an \f(CW@array\fR, so you need parentheses. If you wanted there \fInot\fR to be an \f(CW@AoA\fR,
97 but rather just a reference to it, you could do something more like this:
98 .PP
99 .Vb 8
100 \& # assign a reference to array of array references
101 \& $ref_to_AoA = [
102 \& [ "fred", "barney", "pebbles", "bambam", "dino", ],
103 \& [ "george", "jane", "elroy", "judy", ],
104 \& [ "homer", "bart", "marge", "maggie", ],
105 \& ];
106 \& say $ref_to_AoA\->[2][1];
107 \& bart
108 .Ve
109 .PP
110 Notice that the outer bracket type has changed, and so our access syntax
111 has also changed. That\*(Aqs because unlike C, in perl you can\*(Aqt freely
112 interchange arrays and references thereto. \f(CW$ref_to_AoA\fR is a reference to an
113 array, whereas \f(CW@AoA\fR is an array proper. Likewise, \f(CW$AoA[2]\fR is not an
114 array, but an array ref. So how come you can write these:
115 .PP
116 .Vb 2
117 \& $AoA[2][2]
118 \& $ref_to_AoA\->[2][2]
119 .Ve
120 .PP
121 instead of having to write these:
122 .PP
123 .Vb 2
124 \& $AoA[2]\->[2]
125 \& $ref_to_AoA\->[2]\->[2]
126 .Ve
127 .PP
128 Well, that\*(Aqs because the rule is that on adjacent brackets only (whether
129 square or curly), you are free to omit the pointer dereferencing arrow.
130 But you cannot do so for the very first one if it\*(Aqs a scalar containing
131 a reference, which means that \f(CW$ref_to_AoA\fR always needs it.
132 .SS "Growing Your Own"
133 .IX Subsection "Growing Your Own"
134 That\*(Aqs all well and good for declaration of a fixed data structure,
135 but what if you wanted to add new elements on the fly, or build
136 it up entirely from scratch?
137 .PP
138 First, let\*(Aqs look at reading it in from a file. This is something like
139 adding a row at a time. We\*(Aqll assume that there\*(Aqs a flat file in which
140 each line is a row and each word an element. If you\*(Aqre trying to develop an
141 \&\f(CW@AoA\fR array containing all these, here\*(Aqs the right way to do that:
142 .PP
143 .Vb 4
144 \& while (<>) {
145 \& @tmp = split;
146 \& push @AoA, [ @tmp ];
147 \& }
148 .Ve
149 .PP
150 You might also have loaded that from a function:
151 .PP
152 .Vb 3
153 \& for $i ( 1 .. 10 ) {
154 \& $AoA[$i] = [ somefunc($i) ];
155 \& }
156 .Ve
157 .PP
158 Or you might have had a temporary variable sitting around with the
159 array in it.
160 .PP
161 .Vb 4
162 \& for $i ( 1 .. 10 ) {
163 \& @tmp = somefunc($i);
164 \& $AoA[$i] = [ @tmp ];
165 \& }
166 .Ve
167 .PP
168 It\*(Aqs important you make sure to use the \f(CW\*(C`[ ]\*(C'\fR array reference
169 constructor. That\*(Aqs because this wouldn\*(Aqt work:
170 .PP
171 .Vb 1
172 \& $AoA[$i] = @tmp; # WRONG!
173 .Ve
174 .PP
175 The reason that doesn\*(Aqt do what you want is because assigning a
176 named array like that to a scalar is taking an array in scalar
177 context, which means just counts the number of elements in \f(CW@tmp\fR.
178 .PP
179 If you are running under \f(CW\*(C`use strict\*(C'\fR (and if you aren\*(Aqt, why in
180 the world aren\*(Aqt you?), you\*(Aqll have to add some declarations to
181 make it happy:
182 .PP
183 .Vb 6
184 \& use strict;
185 \& my(@AoA, @tmp);
186 \& while (<>) {
187 \& @tmp = split;
188 \& push @AoA, [ @tmp ];
189 \& }
190 .Ve
191 .PP
192 Of course, you don\*(Aqt need the temporary array to have a name at all:
193 .PP
194 .Vb 3
195 \& while (<>) {
196 \& push @AoA, [ split ];
197 \& }
198 .Ve
199 .PP
200 You also don\*(Aqt have to use \fBpush()\fR. You could just make a direct assignment
201 if you knew where you wanted to put it:
202 .PP
203 .Vb 5
204 \& my (@AoA, $i, $line);
205 \& for $i ( 0 .. 10 ) {
206 \& $line = <>;
207 \& $AoA[$i] = [ split " ", $line ];
208 \& }
209 .Ve
210 .PP
211 or even just
212 .PP
213 .Vb 4
214 \& my (@AoA, $i);
215 \& for $i ( 0 .. 10 ) {
216 \& $AoA[$i] = [ split " ", <> ];
217 \& }
218 .Ve
219 .PP
220 You should in general be leery of using functions that could
221 potentially return lists in scalar context without explicitly stating
222 such. This would be clearer to the casual reader:
223 .PP
224 .Vb 4
225 \& my (@AoA, $i);
226 \& for $i ( 0 .. 10 ) {
227 \& $AoA[$i] = [ split " ", scalar(<>) ];
228 \& }
229 .Ve
230 .PP
231 If you wanted to have a \f(CW$ref_to_AoA\fR variable as a reference to an array,
232 you\*(Aqd have to do something like this:
233 .PP
234 .Vb 3
235 \& while (<>) {
236 \& push @$ref_to_AoA, [ split ];
237 \& }
238 .Ve
239 .PP
240 Now you can add new rows. What about adding new columns? If you\*(Aqre
241 dealing with just matrices, it\*(Aqs often easiest to use simple assignment:
242 .PP
243 .Vb 5
244 \& for $x (1 .. 10) {
245 \& for $y (1 .. 10) {
246 \& $AoA[$x][$y] = func($x, $y);
247 \& }
248 \& }
249 \&
250 \& for $x ( 3, 7, 9 ) {
251 \& $AoA[$x][20] += func2($x);
252 \& }
253 .Ve
254 .PP
255 It doesn\*(Aqt matter whether those elements are already
256 there or not: it\*(Aqll gladly create them for you, setting
257 intervening elements to \f(CW\*(C`undef\*(C'\fR as need be.
258 .PP
259 If you wanted just to append to a row, you\*(Aqd have
260 to do something a bit funnier looking:
261 .PP
262 .Vb 2
263 \& # add new columns to an existing row
264 \& push $AoA[0]\->@*, "wilma", "betty"; # explicit deref
265 .Ve
266 .SS "Access and Printing"
267 .IX Subsection "Access and Printing"
268 Now it\*(Aqs time to print your data structure out. How
269 are you going to do that? Well, if you want only one
270 of the elements, it\*(Aqs trivial:
271 .PP
272 .Vb 1
273 \& print $AoA[0][0];
274 .Ve
275 .PP
276 If you want to print the whole thing, though, you can\*(Aqt
277 say
278 .PP
279 .Vb 1
280 \& print @AoA; # WRONG
281 .Ve
282 .PP
283 because you\*(Aqll get just references listed, and perl will never
284 automatically dereference things for you. Instead, you have to
285 roll yourself a loop or two. This prints the whole structure,
286 using the shell\-style \fBfor()\fR construct to loop across the outer
287 set of subscripts.
288 .PP
289 .Vb 3
290 \& for $aref ( @AoA ) {
291 \& say "\et [ @$aref ],";
292 \& }
293 .Ve
294 .PP
295 If you wanted to keep track of subscripts, you might do this:
296 .PP
297 .Vb 3
298 \& for $i ( 0 .. $#AoA ) {
299 \& say "\et elt $i is [ @{$AoA[$i]} ],";
300 \& }
301 .Ve
302 .PP
303 or maybe even this. Notice the inner loop.
304 .PP
305 .Vb 5
306 \& for $i ( 0 .. $#AoA ) {
307 \& for $j ( 0 .. $#{$AoA[$i]} ) {
308 \& say "elt $i $j is $AoA[$i][$j]";
309 \& }
310 \& }
311 .Ve
312 .PP
313 As you can see, it\*(Aqs getting a bit complicated. That\*(Aqs why
314 sometimes is easier to take a temporary on your way through:
315 .PP
316 .Vb 6
317 \& for $i ( 0 .. $#AoA ) {
318 \& $aref = $AoA[$i];
319 \& for $j ( 0 .. $#{$aref} ) {
320 \& say "elt $i $j is $AoA[$i][$j]";
321 \& }
322 \& }
323 .Ve
324 .PP
325 Hmm... that\*(Aqs still a bit ugly. How about this:
326 .PP
327 .Vb 7
328 \& for $i ( 0 .. $#AoA ) {
329 \& $aref = $AoA[$i];
330 \& $n = @$aref \- 1;
331 \& for $j ( 0 .. $n ) {
332 \& say "elt $i $j is $AoA[$i][$j]";
333 \& }
334 \& }
335 .Ve
336 .PP
337 When you get tired of writing a custom \f(CW\*(C`print\*(C'\fR for your data structures,
338 you might look at the standard Dumpvalue or Data::Dumper modules.
339 The former is what the Perl debugger uses, while the latter generates
340 parsable Perl code. For example:
341 .PP
342 .Vb 1
343 \& use v5.14; # using the + prototype, new to v5.14
344 \&
345 \& sub show(+) {
346 \& require Dumpvalue;
347 \& state $prettify = Dumpvalue\->new(
348 \& tick => q("),
349 \& compactDump => 1, # comment these two lines out
350 \& veryCompact => 1, # if you want a bigger dump
351 \& );
352 \& $prettify\->dumpValue(@_);
353 \& }
354 \&
355 \& # Assign a list of array references to an array.
356 \& my @AoA = (
357 \& [ "fred", "barney" ],
358 \& [ "george", "jane", "elroy" ],
359 \& [ "homer", "marge", "bart" ],
360 \& );
361 \& push $AoA[0]\->@*, "wilma", "betty";
362 \& show @AoA;
363 .Ve
364 .PP
365 will print out:
366 .PP
367 .Vb 3
368 \& 0 0..3 "fred" "barney" "wilma" "betty"
369 \& 1 0..2 "george" "jane" "elroy"
370 \& 2 0..2 "homer" "marge" "bart"
371 .Ve
372 .PP
373 Whereas if you comment out the two lines I said you might wish to,
374 then it shows it to you this way instead:
375 .PP
376 .Vb 10
377 \& 0 ARRAY(0x8031d0)
378 \& 0 "fred"
379 \& 1 "barney"
380 \& 2 "wilma"
381 \& 3 "betty"
382 \& 1 ARRAY(0x803d40)
383 \& 0 "george"
384 \& 1 "jane"
385 \& 2 "elroy"
386 \& 2 ARRAY(0x803e10)
387 \& 0 "homer"
388 \& 1 "marge"
389 \& 2 "bart"
390 .Ve
391 .SS Slices
392 .IX Subsection "Slices"
393 If you want to get at a slice (part of a row) in a multidimensional
394 array, you\*(Aqre going to have to do some fancy subscripting. That\*(Aqs
395 because while we have a nice synonym for single elements via the
396 pointer arrow for dereferencing, no such convenience exists for slices.
397 .PP
398 Here\*(Aqs how to do one operation using a loop. We\*(Aqll assume an \f(CW@AoA\fR
399 variable as before.
400 .PP
401 .Vb 5
402 \& @part = ();
403 \& $x = 4;
404 \& for ($y = 7; $y < 13; $y++) {
405 \& push @part, $AoA[$x][$y];
406 \& }
407 .Ve
408 .PP
409 That same loop could be replaced with a slice operation:
410 .PP
411 .Vb 1
412 \& @part = $AoA[4]\->@[ 7..12 ];
413 .Ve
414 .PP
415 Now, what if you wanted a \fItwo\-dimensional slice\fR, such as having
416 \&\f(CW$x\fR run from 4..8 and \f(CW$y\fR run from 7 to 12? Hmm... here\*(Aqs the simple way:
417 .PP
418 .Vb 6
419 \& @newAoA = ();
420 \& for ($startx = $x = 4; $x <= 8; $x++) {
421 \& for ($starty = $y = 7; $y <= 12; $y++) {
422 \& $newAoA[$x \- $startx][$y \- $starty] = $AoA[$x][$y];
423 \& }
424 \& }
425 .Ve
426 .PP
427 We can reduce some of the looping through slices
428 .PP
429 .Vb 3
430 \& for ($x = 4; $x <= 8; $x++) {
431 \& push @newAoA, [ $AoA[$x]\->@[ 7..12 ] ];
432 \& }
433 .Ve
434 .PP
435 If you were into Schwartzian Transforms, you would probably
436 have selected map for that
437 .PP
438 .Vb 1
439 \& @newAoA = map { [ $AoA[$_]\->@[ 7..12 ] ] } 4 .. 8;
440 .Ve
441 .PP
442 Although if your manager accused you of seeking job security (or rapid
443 insecurity) through inscrutable code, it would be hard to argue. :\-)
444 If I were you, I\*(Aqd put that in a function:
445 .PP
446 .Vb 5
447 \& @newAoA = splice_2D( \e@AoA, 4 => 8, 7 => 12 );
448 \& sub splice_2D {
449 \& my $lrr = shift; # ref to array of array refs!
450 \& my ($x_lo, $x_hi,
451 \& $y_lo, $y_hi) = @_;
452 \&
453 \& return map {
454 \& [ $lrr\->[$_]\->@[ $y_lo .. $y_hi ] ]
455 \& } $x_lo .. $x_hi;
456 \& }
457 .Ve
458 .SH "SEE ALSO"
459 .IX Header "SEE ALSO"
460 perldata, perlref, perldsc
461 .SH AUTHOR
462 .IX Header "AUTHOR"
463 Tom Christiansen <\[email protected]\fR>
464 .PP
465 Last update: Tue Apr 26 18:30:55 MDT 2011