patch for loops over multi-dimensional matrices and cell arrays plus documentation thereof

[David Bateman]

There is a minor bug that can be seen with the example

a = [1,3;2,4]; b = cat(3,a,2*a);
for i = b
  i
end

which reshapes b like reshape (b, rows(b), prod(size(b)(2:end))) and
then loops over the columns of the matrix. This is the matlab compatible
behavior, and what I remember was the behavior we had a few years back.
The patch also documents this behavior, and adds a couple of tests.

D.

-- 
David Bateman                                address@hidden
Motorola Labs - Paris                        +33 1 69 35 48 04 (Ph) 
Parc Les Algorithmes, Commune de St Aubin    +33 6 72 01 06 33 (Mob) 
91193 Gif-Sur-Yvette FRANCE                  +33 1 69 35 77 01 (Fax) 

The information contained in this communication has been classified as: 

[x] General Business Information 
[ ] Motorola Internal Use Only 
[ ] Motorola Confidential Proprietary

*** ./doc/interpreter/stmt.txi.orig20   2007-04-26 17:13:01.647552445 +0200
--- ./doc/interpreter/stmt.txi  2007-04-26 17:07:20.377851230 +0200
***************
*** 506,511 ****
--- 506,549 ----
  loop body is executed again.  This process continues until there are no
  more elements to assign.
  
+ Within Octave is it also possible to iterate over matrices or cell arrays
+ using the @code{for} statement. For example consider
+ 
+ @example
+ @group
+ disp("Loop over a matrix")
+ for i = [1,3;2,4]
+   i
+ endfor
+ disp("Loop over a cell array")
+ for i = @{1,"two";"three",address@hidden
+   i
+ endfor
+ @end group 
+ @end example
+ 
+ @noindent
+ In this case the variable @code{i} takes on the value of the columns of
+ the matrix or cell matrix. So the first loop iterates twice, producing
+ two column vectors @code{[1;2]}, follwed by @code{[3;4]}, and likewise
+ for the loop over the cell array. This can be extended to loops over
+ multidimensional arrays. For example
+ 
+ @example
+ @group
+ a = [1,3;2,4]; b = cat(3, a, 2*a);
+ for i = c
+   i
+ endfor
+ @end group 
+ @end example
+ 
+ @noindent
+ In the above case, the mulitdimensional matrix @var{c} is reshaped to a
+ two dimensional matrix as @code{reshape (c, rows(c),
+ prod(size(c)(2:end)))} and then the same behavior as a loop over a two
+ dimensional matrix is produced.
+ 
  Although it is possible to rewrite all @code{for} loops as @code{while}
  loops, the Octave language has both statements because often a
  @code{for} loop is both less work to type and more natural to think of.
*** ./src/pt-loop.cc.orig20     2007-04-26 17:12:41.003599080 +0200
--- ./src/pt-loop.cc    2007-04-26 16:59:59.388193554 +0200
***************
*** 403,408 ****
--- 403,409 ----
        int ndims = dv.length ();
        for (int i = 2; i < ndims; i++)
          dv(1) *= dv(i);
+       dv.resize (2);
  
        if (dv(1) > 0)
          {
***************
*** 455,460 ****
--- 456,462 ----
        int ndims = dv.length ();
        for (int i = 2; i < ndims; i++)
          dv(1) *= dv(i);
+       dv.resize (2);
  
        if (dv(1) > 0)
          {
*** ./test/test_for.m.orig20    2007-04-26 17:30:47.559640564 +0200
--- ./test/test_for.m   2007-04-26 17:30:30.739491324 +0200
***************
*** 80,82 ****
--- 80,95 ----
  %! printf_assert ("\n");
  %! assert(prog_output_assert("34"));
  
+ %!test
+ %! a = [1,3;2,4];
+ %! j = 0;
+ %! for i = cat (3, a, 4 + a)
+ %!   assert (i, [1;2] + 2*j++)
+ %! endfor
+ 
+ %!test
+ %! a = {1,3;2,4};
+ %! j=0
+ %! for i = cat (3, a, cellfun(@(x) 4 + x, a, 'UniformOutput', 0))
+ %!   assert (i, {1 + 2*j; 2 + 2*j++})
+ %! endfor

2007-04-26  David Bateman  <address@hidden>

        * pt-loop.cc (tree_simple_for_command::eval (void)): Correct
        reshaping of dim_vector in for loop for multi-dimensional array.

2007-04-26  David Bateman  <address@hidden>

        * interpreter/stmt.txi: Document for loops over matrices, arrays
        and cell arrays.

2007-04-26  David Bateman  <address@hidden>

        * test_for.m: Add tests for multi-dimensional matrices and cell
        arrays.