From 14856225739aa48b6c9cf4c17925362b2d95cea3 Mon Sep 17 00:00:00 2001 From: Jason Downs Date: Mon, 19 Aug 1996 10:13:38 +0000 Subject: Import of Perl 5.003 into the tree. Makefile.bsd-wrapper and config.sh.OpenBSD are the only local changes. --- gnu/usr.bin/perl/pod/perllol.pod | 313 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 gnu/usr.bin/perl/pod/perllol.pod (limited to 'gnu/usr.bin/perl/pod/perllol.pod') diff --git a/gnu/usr.bin/perl/pod/perllol.pod b/gnu/usr.bin/perl/pod/perllol.pod new file mode 100644 index 00000000000..11632e0c978 --- /dev/null +++ b/gnu/usr.bin/perl/pod/perllol.pod @@ -0,0 +1,313 @@ +=head1 NAME + +perlLoL - Manipulating Lists of Lists in Perl + +=head1 DESCRIPTION + +=head1 Declaration and Access of Lists of Lists + +The simplest thing to build is a list of lists (sometimes called an array +of arrays). It's reasonably easy to understand, and almost everything +that applies here will also be applicable later on with the fancier data +structures. + +A list of lists, or an array of an array if you would, is just a regular +old array @LoL that you can get at with two subscripts, like $LoL[3][2]. Here's +a declaration of the array: + + # assign to our array a list of list references + @LoL = ( + [ "fred", "barney" ], + [ "george", "jane", "elroy" ], + [ "homer", "marge", "bart" ], + ); + + print $LoL[2][2]; + bart + +Now you should be very careful that the outer bracket type +is a round one, that is, parentheses. That's because you're assigning to +an @list, so you need parens. If you wanted there I to be an @LoL, +but rather just a reference to it, you could do something more like this: + + # assign a reference to list of list references + $ref_to_LoL = [ + [ "fred", "barney", "pebbles", "bambam", "dino", ], + [ "homer", "bart", "marge", "maggie", ], + [ "george", "jane", "alroy", "judy", ], + ]; + + print $ref_to_LoL->[2][2]; + +Notice that the outer bracket type has changed, and so our access syntax +has also changed. That's because unlike C, in perl you can't freely +interchange arrays and references thereto. $ref_to_LoL is a reference to an +array, whereas @LoL is an array proper. Likewise, $LoL[2] is not an +array, but an array ref. So how come you can write these: + + $LoL[2][2] + $ref_to_LoL->[2][2] + +instead of having to write these: + + $LoL[2]->[2] + $ref_to_LoL->[2]->[2] + +Well, that's because the rule is that on adjacent brackets only (whether +square or curly), you are free to omit the pointer dereferencing array. +But you need not do so for the very first one if it's a scalar containing +a reference, which means that $ref_to_LoL always needs it. + +=head1 Growing Your Own + +That's all well and good for declaration of a fixed data structure, +but what if you wanted to add new elements on the fly, or build +it up entirely from scratch? + +First, let's look at reading it in from a file. This is something like +adding a row at a time. We'll assume that there's a flat file in which +each line is a row and each word an element. If you're trying to develop an +@LoL list containing all these, here's the right way to do that: + + while (<>) { + @tmp = split; + push @LoL, [ @tmp ]; + } + +You might also have loaded that from a function: + + for $i ( 1 .. 10 ) { + $LoL[$i] = [ somefunc($i) ]; + } + +Or you might have had a temporary variable sitting around with the +list in it. + + for $i ( 1 .. 10 ) { + @tmp = somefunc($i); + $LoL[$i] = [ @tmp ]; + } + +It's very important that you make sure to use the C<[]> list reference +constructor. That's because this will be very wrong: + + $LoL[$i] = @tmp; + +You see, assigning a named list like that to a scalar just counts the +number of elements in @tmp, which probably isn't what you want. + +If you are running under C, you'll have to add some +declarations to make it happy: + + use strict; + my(@LoL, @tmp); + while (<>) { + @tmp = split; + push @LoL, [ @tmp ]; + } + +Of course, you don't need the temporary array to have a name at all: + + while (<>) { + push @LoL, [ split ]; + } + +You also don't have to use push(). You could just make a direct assignment +if you knew where you wanted to put it: + + my (@LoL, $i, $line); + for $i ( 0 .. 10 ) + $line = <>; + $LoL[$i] = [ split ' ', $line ]; + } + +or even just + + my (@LoL, $i); + for $i ( 0 .. 10 ) + $LoL[$i] = [ split ' ', <> ]; + } + +You should in general be leary of using potential list functions +in a scalar context without explicitly stating such. +This would be clearer to the casual reader: + + my (@LoL, $i); + for $i ( 0 .. 10 ) + $LoL[$i] = [ split ' ', scalar(<>) ]; + } + +If you wanted to have a $ref_to_LoL variable as a reference to an array, +you'd have to do something like this: + + while (<>) { + push @$ref_to_LoL, [ split ]; + } + +Actually, if you were using strict, you'd not only have to declare $ref_to_LoL as +you had to declare @LoL, but you'd I having to initialize it to a +reference to an empty list. (This was a bug in 5.001m that's been fixed +for the 5.002 release.) + + my $ref_to_LoL = []; + while (<>) { + push @$ref_to_LoL, [ split ]; + } + +Ok, now you can add new rows. What about adding new columns? If you're +just dealing with matrices, it's often easiest to use simple assignment: + + for $x (1 .. 10) { + for $y (1 .. 10) { + $LoL[$x][$y] = func($x, $y); + } + } + + for $x ( 3, 7, 9 ) { + $LoL[$x][20] += func2($x); + } + +It doesn't matter whether those elements are already +there or not: it'll gladly create them for you, setting +intervening elements to C as need be. + +If you just wanted to append to a row, you'd have +to do something a bit funnier looking: + + # add new columns to an existing row + push @{ $LoL[0] }, "wilma", "betty"; + +Notice that I I just say: + + push $LoL[0], "wilma", "betty"; # WRONG! + +In fact, that wouldn't even compile. How come? Because the argument +to push() must be a real array, not just a reference to such. + +=head1 Access and Printing + +Now it's time to print your data structure out. How +are you going to do that? Well, if you only want one +of the elements, it's trivial: + + print $LoL[0][0]; + +If you want to print the whole thing, though, you can't +just say + + print @LoL; # WRONG + +because you'll just get references listed, and perl will never +automatically dereference things for you. Instead, you have to +roll yourself a loop or two. This prints the whole structure, +using the shell-style for() construct to loop across the outer +set of subscripts. + + for $aref ( @LoL ) { + print "\t [ @$aref ],\n"; + } + +If you wanted to keep track of subscripts, you might do this: + + for $i ( 0 .. $#LoL ) { + print "\t elt $i is [ @{$LoL[$i]} ],\n"; + } + +or maybe even this. Notice the inner loop. + + for $i ( 0 .. $#LoL ) { + for $j ( 0 .. $#{$LoL[$i]} ) { + print "elt $i $j is $LoL[$i][$j]\n"; + } + } + +As you can see, it's getting a bit complicated. That's why +sometimes is easier to take a temporary on your way through: + + for $i ( 0 .. $#LoL ) { + $aref = $LoL[$i]; + for $j ( 0 .. $#{$aref} ) { + print "elt $i $j is $LoL[$i][$j]\n"; + } + } + +Hm... that's still a bit ugly. How about this: + + for $i ( 0 .. $#LoL ) { + $aref = $LoL[$i]; + $n = @$aref - 1; + for $j ( 0 .. $n ) { + print "elt $i $j is $LoL[$i][$j]\n"; + } + } + +=head1 Slices + +If you want to get at a slide (part of a row) in a multidimensional +array, you're going to have to do some fancy subscripting. That's +because while we have a nice synonym for single elements via the +pointer arrow for dereferencing, no such convenience exists for slices. +(Remember, of course, that you can always write a loop to do a slice +operation.) + +Here's how to do one operation using a loop. We'll assume an @LoL +variable as before. + + @part = (); + $x = 4; + for ($y = 7; $y < 13; $y++) { + push @part, $LoL[$x][$y]; + } + +That same loop could be replaced with a slice operation: + + @part = @{ $LoL[4] } [ 7..12 ]; + +but as you might well imagine, this is pretty rough on the reader. + +Ah, but what if you wanted a I, such as having +$x run from 4..8 and $y run from 7 to 12? Hm... here's the simple way: + + @newLoL = (); + for ($startx = $x = 4; $x <= 8; $x++) { + for ($starty = $y = 7; $x <= 12; $y++) { + $newLoL[$x - $startx][$y - $starty] = $LoL[$x][$y]; + } + } + +We can reduce some of the looping through slices + + for ($x = 4; $x <= 8; $x++) { + push @newLoL, [ @{ $LoL[$x] } [ 7..12 ] ]; + } + +If you were into Schwartzian Transforms, you would probably +have selected map for that + + @newLoL = map { [ @{ $LoL[$_] } [ 7..12 ] ] } 4 .. 8; + +Although if your manager accused of seeking job security (or rapid +insecurity) through inscrutable code, it would be hard to argue. :-) +If I were you, I'd put that in a function: + + @newLoL = splice_2D( \@LoL, 4 => 8, 7 => 12 ); + sub splice_2D { + my $lrr = shift; # ref to list of list refs! + my ($x_lo, $x_hi, + $y_lo, $y_hi) = @_; + + return map { + [ @{ $lrr->[$_] } [ $y_lo .. $y_hi ] ] + } $x_lo .. $x_hi; + } + + +=head1 SEE ALSO + +perldata(1), perlref(1), perldsc(1) + +=head1 AUTHOR + +Tom Christiansen + +Last udpate: Sat Oct 7 19:35:26 MDT 1995 -- cgit v1.2.3