Debian Codegraph @

upstream/debian-unstable/man1/perllol.1

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