Cwd::fastcwd in File::Find
[perl.git] / pod / perllol.pod
1 =head1 NAME
2
3 perlLoL - Manipulating Lists of Lists in Perl
4
5 =head1 DESCRIPTION
6
7 =head1 Declaration and Access of Lists of Lists
8
9 The simplest thing to build is a list of lists (sometimes called an array
10 of arrays).  It's reasonably easy to understand, and almost everything
11 that applies here will also be applicable later on with the fancier data
12 structures.
13
14 A list of lists, or an array of an array if you would, is just a regular
15 old array @LoL that you can get at with two subscripts, like $LoL[3][2].  Here's
16 a declaration of the array:
17
18     # assign to our array a list of list references
19     @LoL = ( 
20            [ "fred", "barney" ],
21            [ "george", "jane", "elroy" ],
22            [ "homer", "marge", "bart" ],
23     );
24
25     print $LoL[2][2];
26   bart
27
28 Now you should be very careful that the outer bracket type
29 is a round one, that is, parentheses.  That's because you're assigning to
30 an @list, so you need parens.  If you wanted there I<not> to be an @LoL,
31 but rather just a reference to it, you could do something more like this:
32
33     # assign a reference to list of list references
34     $ref_to_LoL = [
35         [ "fred", "barney", "pebbles", "bambam", "dino", ],
36         [ "homer", "bart", "marge", "maggie", ],
37         [ "george", "jane", "alroy", "judy", ],
38     ];
39
40     print $ref_to_LoL->[2][2];
41
42 Notice that the outer bracket type has changed, and so our access syntax 
43 has also changed.  That's because unlike C, in perl you can't freely
44 interchange arrays and references thereto.  $ref_to_LoL is a reference to an 
45 array, whereas @LoL is an array proper.  Likewise, $LoL[2] is not an 
46 array, but an array ref.  So how come you can write these:
47
48     $LoL[2][2]
49     $ref_to_LoL->[2][2]
50
51 instead of having to write these:
52
53     $LoL[2]->[2]
54     $ref_to_LoL->[2]->[2]
55
56 Well, that's because the rule is that on adjacent brackets only (whether
57 square or curly), you are free to omit the pointer dereferencing array.
58 But you cannot do so for the very first one if it's a scalar containing
59 a reference, which means that $ref_to_LoL always needs it.
60
61 =head1 Growing Your Own
62
63 That's all well and good for declaration of a fixed data structure,
64 but what if you wanted to add new elements on the fly, or build
65 it up entirely from scratch?
66
67 First, let's look at reading it in from a file.  This is something like
68 adding a row at a time.  We'll assume that there's a flat file in which
69 each line is a row and each word an element.  If you're trying to develop an
70 @LoL list containing all these, here's the right way to do that:
71
72     while (<>) {
73         @tmp = split;
74         push @LoL, [ @tmp ];
75     } 
76
77 You might also have loaded that from a function:
78
79     for $i ( 1 .. 10 ) {
80         $LoL[$i] = [ somefunc($i) ];
81     }
82
83 Or you might have had a temporary variable sitting around with the
84 list in it.  
85
86     for $i ( 1 .. 10 ) {
87         @tmp = somefunc($i);
88         $LoL[$i] = [ @tmp ];
89     }
90
91 It's very important that you make sure to use the C<[]> list reference
92 constructor.  That's because this will be very wrong:
93
94     $LoL[$i] = @tmp;
95
96 You see, assigning a named list like that to a scalar just counts the 
97 number of elements in @tmp, which probably isn't what you want.  
98
99 If you are running under C<use strict>, you'll have to add some
100 declarations to make it happy:
101
102     use strict;
103     my(@LoL, @tmp);
104     while (<>) {
105         @tmp = split;
106         push @LoL, [ @tmp ];
107     } 
108
109 Of course, you don't need the temporary array to have a name at all:
110
111     while (<>) {
112         push @LoL, [ split ];
113     } 
114
115 You also don't have to use push().  You could just make a direct assignment
116 if you knew where you wanted to put it:
117
118     my (@LoL, $i, $line);
119     for $i ( 0 .. 10 ) 
120         $line = <>;
121         $LoL[$i] = [ split ' ', $line ];
122     } 
123
124 or even just
125
126     my (@LoL, $i);
127     for $i ( 0 .. 10 ) 
128         $LoL[$i] = [ split ' ', <> ];
129     } 
130
131 You should in general be leery of using potential list functions
132 in a scalar context without explicitly stating such.  
133 This would be clearer to the casual reader:
134
135     my (@LoL, $i);
136     for $i ( 0 .. 10 ) 
137         $LoL[$i] = [ split ' ', scalar(<>) ];
138     } 
139
140 If you wanted to have a $ref_to_LoL variable as a reference to an array,
141 you'd have to do something like this:
142
143     while (<>) {
144         push @$ref_to_LoL, [ split ];
145     } 
146
147 Actually, if you were using strict, you'd not only have to declare $ref_to_LoL as
148 you had to declare @LoL, but you'd I<also> having to initialize it to a
149 reference to an empty list.  (This was a bug in 5.001m that's been fixed
150 for the 5.002 release.)
151
152     my $ref_to_LoL = [];
153     while (<>) {
154         push @$ref_to_LoL, [ split ];
155     } 
156
157 Ok, now you can add new rows.  What about adding new columns?  If you're
158 just dealing with matrices, it's often easiest to use simple assignment:
159
160     for $x (1 .. 10) {
161         for $y (1 .. 10) {
162             $LoL[$x][$y] = func($x, $y);
163         }
164     }
165
166     for $x ( 3, 7, 9 ) {
167         $LoL[$x][20] += func2($x);
168     } 
169
170 It doesn't matter whether those elements are already 
171 there or not: it'll gladly create them for you, setting
172 intervening elements to C<undef> as need be.
173
174 If you just wanted to append to a row, you'd have
175 to do something a bit funnier looking:
176
177     # add new columns to an existing row
178     push @{ $LoL[0] }, "wilma", "betty";
179
180 Notice that I I<couldn't> just say:
181
182     push $LoL[0], "wilma", "betty";  # WRONG!
183
184 In fact, that wouldn't even compile.  How come?  Because the argument
185 to push() must be a real array, not just a reference to such.
186
187 =head1 Access and Printing
188
189 Now it's time to print your data structure out.  How 
190 are you going to do that?  Well, if you only want one
191 of the elements, it's trivial:
192
193     print $LoL[0][0];
194
195 If you want to print the whole thing, though, you can't
196 just say 
197
198     print @LoL;         # WRONG
199
200 because you'll just get references listed, and perl will never
201 automatically dereference things for you.  Instead, you have to 
202 roll yourself a loop or two.  This prints the whole structure,
203 using the shell-style for() construct to loop across the outer
204 set of subscripts.  
205
206     for $aref ( @LoL ) {
207         print "\t [ @$aref ],\n";
208     }
209
210 If you wanted to keep track of subscripts, you might do this:
211
212     for $i ( 0 .. $#LoL ) {
213         print "\t elt $i is [ @{$LoL[$i]} ],\n";
214     }
215
216 or maybe even this.  Notice the inner loop.
217
218     for $i ( 0 .. $#LoL ) {
219         for $j ( 0 .. $#{$LoL[$i]} ) {
220             print "elt $i $j is $LoL[$i][$j]\n";
221         }
222     }
223
224 As you can see, it's getting a bit complicated.  That's why 
225 sometimes is easier to take a temporary on your way through:
226
227     for $i ( 0 .. $#LoL ) {
228         $aref = $LoL[$i];
229         for $j ( 0 .. $#{$aref} ) {
230             print "elt $i $j is $LoL[$i][$j]\n";
231         }
232     }
233
234 Hm... that's still a bit ugly.  How about this:
235
236     for $i ( 0 .. $#LoL ) {
237         $aref = $LoL[$i];
238         $n = @$aref - 1;
239         for $j ( 0 .. $n ) {
240             print "elt $i $j is $LoL[$i][$j]\n";
241         }
242     }
243
244 =head1 Slices
245
246 If you want to get at a slice (part of a row) in a multidimensional
247 array, you're going to have to do some fancy subscripting.  That's
248 because while we have a nice synonym for single elements via the
249 pointer arrow for dereferencing, no such convenience exists for slices.
250 (Remember, of course, that you can always write a loop to do a slice
251 operation.)
252
253 Here's how to do one operation using a loop.  We'll assume an @LoL
254 variable as before.
255
256     @part = ();
257     $x = 4;     
258     for ($y = 7; $y < 13; $y++) {
259         push @part, $LoL[$x][$y];
260     } 
261
262 That same loop could be replaced with a slice operation:
263
264     @part = @{ $LoL[4] } [ 7..12 ];
265
266 but as you might well imagine, this is pretty rough on the reader.
267
268 Ah, but what if you wanted a I<two-dimensional slice>, such as having
269 $x run from 4..8 and $y run from 7 to 12?  Hm... here's the simple way:
270
271     @newLoL = ();
272     for ($startx = $x = 4; $x <= 8; $x++) {
273         for ($starty = $y = 7; $x <= 12; $y++) {
274             $newLoL[$x - $startx][$y - $starty] = $LoL[$x][$y];
275         }
276     } 
277
278 We can reduce some of the looping through slices 
279
280     for ($x = 4; $x <= 8; $x++) {
281         push @newLoL, [ @{ $LoL[$x] } [ 7..12 ] ];
282     }
283
284 If you were into Schwartzian Transforms, you would probably
285 have selected map for that
286
287     @newLoL = map { [ @{ $LoL[$_] } [ 7..12 ] ] } 4 .. 8;
288
289 Although if your manager accused of seeking job security (or rapid
290 insecurity) through inscrutable code, it would be hard to argue. :-)
291 If I were you, I'd put that in a function:
292
293     @newLoL = splice_2D( \@LoL, 4 => 8, 7 => 12 );
294     sub splice_2D {
295         my $lrr = shift;        # ref to list of list refs!
296         my ($x_lo, $x_hi, 
297             $y_lo, $y_hi) = @_;
298
299         return map { 
300             [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ] 
301         } $x_lo .. $x_hi;
302     } 
303
304
305 =head1 SEE ALSO
306
307 perldata(1), perlref(1), perldsc(1)
308
309 =head1 AUTHOR
310
311 Tom Christiansen <tchrist@perl.com>
312
313 Last udpate: Sat Oct  7 19:35:26 MDT 1995