pod/perllol.pod

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