changeset 19126:995df67fc912

Flip arrays - ND support for fliplr and flipud, and replace flipdim with flip. * fliplr.m, flipud.m: add support for N-dimensional arrays by making use of flip(). Added new tests for ND arrays and defaults. * flipdim.m: deprecate in favour of new function flip() which has exactly the same syntax and is part of Matlab since R2014a. * flip.m: new function copied from flipdim. Added tests for ND arrays and defaults. * matrix.txi: replace flipdim DOCSTRINg with flip. * rot90.m, rotdim.m, del2.m: replace flipdim() with flip() * NEWS: note deprecation of flip(), new function flipdim(), and ND support for flipud() and fliplr().
author Carnë Draug <carandraug+dev@gmail.com>
date Sun, 21 Sep 2014 18:49:08 +0100
parents 62f833acf183
children df5e4024ec18
files NEWS doc/interpreter/matrix.txi scripts/deprecated/flipdim.m scripts/deprecated/module.mk scripts/general/del2.m scripts/general/flip.m scripts/general/flipdim.m scripts/general/fliplr.m scripts/general/flipud.m scripts/general/module.mk scripts/general/rot90.m scripts/general/rotdim.m
diffstat 12 files changed, 245 insertions(+), 99 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Sun Sep 21 11:17:28 2014 -0400
+++ b/NEWS	Sun Sep 21 18:49:08 2014 +0100
@@ -68,6 +68,7 @@
 
       bandwidth
       dir_in_loadpath
+      flip
       hgload
       hgsave
       ichol
@@ -102,6 +103,7 @@
       bicubic            | interp2
       find_dir_in_path   | dir_in_loadpath
       finite             | isfinite
+      flipdim            | flip
       fmod               | rem
       fnmatch            | glob or regexp
       nfields            | numfields
@@ -134,6 +136,12 @@
     been removed from Octave 4.2.  Replacement classes are
     <octave_map> (struct array) or <octave_scalar_map> for a single structure.
 
+ ** The following functions have now support for N-dimensional arrays:
+
+      fliplr
+      flipud
+
+
 Summary of important user-visible changes for version 4.0:
 ---------------------------------------------------------
 
--- a/doc/interpreter/matrix.txi	Sun Sep 21 11:17:28 2014 -0400
+++ b/doc/interpreter/matrix.txi	Sun Sep 21 18:49:08 2014 +0100
@@ -90,7 +90,7 @@
 
 @DOCSTRING(flipud)
 
-@DOCSTRING(flipdim)
+@DOCSTRING(flip)
 
 @DOCSTRING(rot90)
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/deprecated/flipdim.m	Sun Sep 21 18:49:08 2014 +0100
@@ -0,0 +1,61 @@
+## Copyright (C) 2004-2013 David Bateman
+## Copyright (C) 2009 VZLU Prague
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {Function File} {} flipdim (@var{x})
+## @deftypefnx {Function File} {} flipdim (@var{x}, @var{dim})
+## Return a copy of @var{x} flipped about the dimension @var{dim}.
+## @var{dim} defaults to the first non-singleton dimension.
+##
+## @strong{Warning:} @code{flipdim} is scheduled for removal in version 4.6.
+## Use @code{flip} which can be used as a drop-in replacement.
+##
+## @seealso{fliplr, flipud, rot90, rotdim}
+## @end deftypefn
+
+## Author: David Bateman, Jaroslav Hajek
+
+function y = flipdim (x, dim)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "flipdim is deprecated and will be removed from a future version of Octave; please use flip (x, dim) instead");
+  endif
+
+  if (nargin != 1 && nargin != 2)
+    print_usage ();
+  endif
+
+  nd = ndims (x);
+  sz = size (x);
+  if (nargin == 1)
+    ## Find the first non-singleton dimension.
+    (dim = find (sz > 1, 1)) || (dim = 1);
+  elseif (! (isscalar (dim) && isindex (dim)))
+    error ("flipdim: DIM must be a positive integer");
+  endif
+
+  idx(1:max(nd, dim)) = {':'};
+  idx{dim} = size (x, dim):-1:1;
+  y = x(idx{:});
+
+endfunction
+
--- a/scripts/deprecated/module.mk	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/deprecated/module.mk	Sun Sep 21 18:49:08 2014 +0100
@@ -4,6 +4,7 @@
   deprecated/bicubic.m \
   deprecated/find_dir_in_path.m \
   deprecated/finite.m \
+  deprecated/flipdim.m \
   deprecated/fmod.m \
   deprecated/fnmatch.m \
   deprecated/isstr.m \
--- a/scripts/general/del2.m	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/general/del2.m	Sun Sep 21 18:49:08 2014 +0100
@@ -315,7 +315,7 @@
 %! assert (b(4,4,5), 0.00);
 %! assert (b(5,4,5), 1.00);
 %! assert (b(5,5,5),-6.00);
-%! assert (b, flipdim (b,1));
-%! assert (b, flipdim (b,2));
-%! assert (b, flipdim (b,3));
+%! assert (b, flip (b,1));
+%! assert (b, flip (b,2));
+%! assert (b, flip (b,3));
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/general/flip.m	Sun Sep 21 18:49:08 2014 +0100
@@ -0,0 +1,111 @@
+## Copyright (C) 2004-2013 David Bateman
+## Copyright (C) 2009 VZLU Prague
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {Function File} {} flip (@var{x})
+## @deftypefnx {Function File} {} flip (@var{x}, @var{dim})
+## Flip array across specific dimension.
+##
+## Return a copy of @var{x} flipped about the dimension @var{dim}.
+## @var{dim} defaults to the first non-singleton dimension.
+## For example:
+##
+## @example
+## @group
+## flip ([1  2  3  4])
+##       @result{}  4  3  2  1
+## @end group
+##
+## @group
+## flip ([1; 2; 3; 4])
+##       @result{}  4
+##           3
+##           2
+##           1
+## @end group
+##
+## @group
+## flip ([1 2; 3 4])
+##       @result{}  3  4
+##           1  2
+## @end group
+##
+## @group
+## flip ([1 2; 3 4], 2)
+##       @result{}  2  1
+##           4  3
+## @end group
+## @end example
+##
+## @seealso{fliplr, flipud, rot90, rotdim}
+## @end deftypefn
+
+## Author: David Bateman, Jaroslav Hajek
+
+function y = flip (x, dim)
+
+  if (nargin != 1 && nargin != 2)
+    print_usage ();
+  endif
+
+  nd = ndims (x);
+  sz = size (x);
+  if (nargin == 1)
+    ## Find the first non-singleton dimension.
+    (dim = find (sz > 1, 1)) || (dim = 1);
+  elseif (! (isscalar (dim) && isindex (dim)))
+    error ("flip: DIM must be a positive integer");
+  endif
+
+  idx(1:max(nd, dim)) = {':'};
+  idx{dim} = size (x, dim):-1:1;
+  y = x(idx{:});
+
+endfunction
+
+
+%!assert (flip ([1 2; 3 4], 2), [2 1; 4 3])
+%!assert (flip ([1 2; 3 4], 3), [1 2; 3 4])
+
+## Test defaults
+%!assert (flip ([1 2 3 4]), [4 3 2 1])
+%!assert (flip ([1 2 3 4].'), [4 3 2 1].')
+%!assert (flip ([1 2; 3 4]), flip ([1 2 ; 3 4], 1))
+
+## Test NDArrays
+%!test
+%! a(1:2,1:2,1) = [1 2; 3 4];
+%! a(1:2,1:2,2) = [5 6; 7 8];
+%! b(1:2,1:2,1) = [5 6; 7 8];
+%! b(1:2,1:2,2) = [1 2; 3 4];
+%! assert (flip (a, 3), b)
+
+%!test
+%! a = b = zeros (2, 2, 1, 2);
+%! a(1:2,1:2,:,1) = [1 2; 3 4];
+%! a(1:2,1:2,:,2) = [5 6; 7 8];
+%! b(1:2,1:2,:,1) = [5 6; 7 8];
+%! b(1:2,1:2,:,2) = [1 2; 3 4];
+%! assert (flip (a, 3), a)
+%! assert (flip (a, 4), b)
+%! assert (flip (a, 5), a)
+
+%!error flip ()
+%!error flip (1, 2, 3)
+
--- a/scripts/general/flipdim.m	Sun Sep 21 11:17:28 2014 -0400
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,69 +0,0 @@
-## Copyright (C) 2004-2013 David Bateman
-## Copyright (C) 2009 VZLU Prague
-##
-## This file is part of Octave.
-##
-## Octave is free software; you can redistribute it and/or modify it
-## under the terms of the GNU General Public License as published by
-## the Free Software Foundation; either version 3 of the License, or (at
-## your option) any later version.
-##
-## Octave is distributed in the hope that it will be useful, but
-## WITHOUT ANY WARRANTY; without even the implied warranty of
-## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-## General Public License for more details.
-##
-## You should have received a copy of the GNU General Public License
-## along with Octave; see the file COPYING.  If not, see
-## <http://www.gnu.org/licenses/>.
-
-## -*- texinfo -*-
-## @deftypefn  {Function File} {} flipdim (@var{x})
-## @deftypefnx {Function File} {} flipdim (@var{x}, @var{dim})
-## Return a copy of @var{x} flipped about the dimension @var{dim}.
-## @var{dim} defaults to the first non-singleton dimension.
-## For example:
-##
-## @example
-## @group
-## flipdim ([1, 2; 3, 4], 2)
-##       @result{}  2  1
-##           4  3
-## @end group
-## @end example
-## @seealso{fliplr, flipud, rot90, rotdim}
-## @end deftypefn
-
-## Author: David Bateman, Jaroslav Hajek
-
-function y = flipdim (x, dim)
-
-  if (nargin != 1 && nargin != 2)
-    print_usage ();
-  endif
-
-  nd = ndims (x);
-  sz = size (x);
-  if (nargin == 1)
-    ## Find the first non-singleton dimension.
-    (dim = find (sz > 1, 1)) || (dim = 1);
-  elseif (! (isscalar (dim) && isindex (dim)))
-    error ("flipdim: DIM must be a positive integer");
-  endif
-
-  idx(1:max(nd, dim)) = {':'};
-  idx{dim} = size (x, dim):-1:1;
-  y = x(idx{:});
-
-endfunction
-
-
-%!assert (flipdim ([1,2;3,4]), flipdim ([1,2 ; 3,4], 1))
-%!assert (flipdim ([1,2;3,4], 2), [2,1;4,3])
-%!assert (flipdim ([1,2;3,4], 3), [1,2;3,4])
-
-## FIXME: We need tests for multidimensional arrays.
-
-%!error flipdim ()
-%!error flipdim (1, 2, 3)
-
--- a/scripts/general/fliplr.m	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/general/fliplr.m	Sun Sep 21 18:49:08 2014 +0100
@@ -18,6 +18,8 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} fliplr (@var{x})
+## Flip array left to right.
+##
 ## Return a copy of @var{x} with the order of the columns reversed.  In
 ## other words, @var{x} is flipped left-to-right about a vertical axis.  For
 ## example:
@@ -30,9 +32,7 @@
 ## @end group
 ## @end example
 ##
-## Note that @code{fliplr} only works with 2-D arrays.  To flip N-D arrays
-## use @code{flipdim} instead.
-## @seealso{flipud, flipdim, rot90, rotdim}
+## @seealso{flipud, rot90, rotdim}
 ## @end deftypefn
 
 ## Author: jwe
@@ -42,13 +42,7 @@
   if (nargin != 1)
     print_usage ();
   endif
-
-  if (ndims (x) > 2)
-    error ("fliplr: Only works with 2-D arrays");
-  endif
-
-  nc = columns (x);
-  y = x (:, nc:-1:1);
+  y = flip (x, 2);
 
 endfunction
 
@@ -56,6 +50,29 @@
 %!assert (fliplr ([1, 2; 3, 4]), [2, 1; 4, 3])
 %!assert (fliplr ([1, 2; 3, 4; 5, 6]), [2, 1; 4, 3; 6, 5])
 %!assert (fliplr ([1, 2, 3; 4, 5, 6]), [3, 2, 1; 6, 5, 4])
+%!assert (fliplr ([1 2 3].'), [1 2 3].')
+
+## Test NDArrays
+%!test
+%! a(:,:,1) = [ 1  2;  3  4;  5  6];
+%! a(:,:,2) = [ 7  8;  9 10; 11 12];
+%! b(:,:,1) = [ 2  1;  4  3;  6  5];
+%! b(:,:,2) = [ 8  7; 10  9; 12 11];
+%! assert (fliplr (a), b)
+
+## Test NDArray with singleton dimensions
+%!test
+%! a(:,:,:,1) = [ 1  2;  3  4;  5  6];
+%! a(:,:,:,2) = [ 7  8;  9 10; 11 12];
+%! b(:,:,:,1) = [ 2  1;  4  3;  6  5];
+%! b(:,:,:,2) = [ 8  7; 10  9; 12 11];
+%! assert (fliplr (a), b)
+
+## Test for 1 row, i.e., returns the same
+%!test
+%! a(:,1,:,1) = [ 1  2  3  4];
+%! a(:,1,:,2) = [ 5  6  7  8];
+%! assert (fliplr (a), a)
 
 %!error fliplr()
 %!error fliplr (1, 2)
--- a/scripts/general/flipud.m	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/general/flipud.m	Sun Sep 21 18:49:08 2014 +0100
@@ -18,6 +18,8 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} flipud (@var{x})
+## Flip array upside down.
+##
 ## Return a copy of @var{x} with the order of the rows reversed.  In
 ## other words, @var{x} is flipped upside-down about a horizontal axis.  For
 ## example:
@@ -30,9 +32,7 @@
 ## @end group
 ## @end example
 ##
-## Note that @code{flipud} only works with 2-D arrays.  To flip N-D arrays
-## use @code{flipdim} instead.
-## @seealso{fliplr, flipdim, rot90, rotdim}
+## @seealso{fliplr, rot90, rotdim}
 ## @end deftypefn
 
 ## Author: jwe
@@ -42,13 +42,7 @@
   if (nargin != 1)
     print_usage ();
   endif
-
-  if (ndims (x) > 2)
-    error ("flipud: Only works with 2-d arrays");
-  endif
-
-  nr = rows (x);
-  y = x (nr:-1:1, :);
+  y = flip (x, 1);
 
 endfunction
 
@@ -56,6 +50,29 @@
 %!assert (flipud ([1, 2; 3, 4]), [3, 4; 1, 2])
 %!assert (flipud ([1, 2; 3, 4; 5, 6]), [5, 6; 3, 4; 1, 2])
 %!assert (flipud ([1, 2, 3; 4, 5, 6]), [4, 5, 6; 1, 2, 3])
+%!assert (flipud ([1 2 3]), [1 2 3])
+
+## Test NDArrays
+%!test
+%! a(:,:,1) = [ 1  2  3;  4  5  6];
+%! a(:,:,2) = [ 7  8  9; 10 11 12];
+%! b(:,:,1) = [ 4  5  6;  1  2  3];
+%! b(:,:,2) = [10 11 12;  7  8  9];
+%! assert (flipud (a), b)
+
+## Test NDArray with singleton dimensions
+%!test
+%! a(:,:,:,1) = [ 1  2  3;  4  5  6];
+%! a(:,:,:,2) = [ 7  8  9; 10 11 12];
+%! b(:,:,:,1) = [ 4  5  6;  1  2  3];
+%! b(:,:,:,2) = [10 11 12;  7  8  9];
+%! assert (flipud (a), b)
+
+## Test for 1 row, i.e., returns the same
+%!test
+%! a(1,:,:,1) = [ 1  2  3  4];
+%! a(1,:,:,2) = [ 5  6  7  8];
+%! assert (flipud (a), a)
 
 %!error flipud ()
 %!error flipud (1, 2)
--- a/scripts/general/module.mk	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/general/module.mk	Sun Sep 21 18:49:08 2014 +0100
@@ -28,7 +28,7 @@
   general/display.m \
   general/divergence.m \
   general/fieldnames.m \
-  general/flipdim.m \
+  general/flip.m \
   general/fliplr.m \
   general/flipud.m \
   general/gradient.m \
--- a/scripts/general/rot90.m	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/general/rot90.m	Sun Sep 21 18:49:08 2014 +0100
@@ -47,7 +47,7 @@
 ##
 ## Note that @code{rot90} only works with 2-D arrays.  To rotate N-D arrays
 ## use @code{rotdim} instead.
-## @seealso{rotdim, flipud, fliplr, flipdim}
+## @seealso{rotdim, flipud, fliplr, flip}
 ## @end deftypefn
 
 ## Author: jwe
--- a/scripts/general/rotdim.m	Sun Sep 21 11:17:28 2014 -0400
+++ b/scripts/general/rotdim.m	Sun Sep 21 18:49:08 2014 +0100
@@ -51,7 +51,7 @@
 ## rotdim ([1, 2; 3, 4], 7, [1, 2])
 ## @end group
 ## @end example
-## @seealso{rot90, flipud, fliplr, flipdim}
+## @seealso{rot90, flipud, fliplr, flip}
 ## @end deftypefn
 
 function y = rotdim (x, n, plane)
@@ -107,16 +107,16 @@
   if (n == 0)
     y = x;
   elseif (n == 2)
-    y = flipdim (flipdim (x, plane(1)), plane(2));
+    y = flip (flip (x, plane(1)), plane(2));
   elseif (n == 1 || n == 3)
     perm = 1:nd;
     perm(plane(1)) = plane(2);
     perm(plane(2)) = plane(1);
     y = permute (x, perm);
     if (n == 1)
-      y = flipdim (y, min (plane));
+      y = flip (y, min (plane));
     else
-      y = flipdim (y, max (plane));
+      y = flip (y, max (plane));
     endif
   else
     error ("rotdim: internal error!");