octave_packages/m/general/shiftdim.m

   1 ## Copyright (C) 2004-2012 John Eaton and David Bateman
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {@var{y} =} shiftdim (@var{x}, @var{n})
  21 ## @deftypefnx {Function File} {[@var{y}, @var{ns}] =} shiftdim (@var{x})
  22 ## Shift the dimensions of @var{x} by @var{n}, where @var{n} must be
  23 ## an integer scalar.  When @var{n} is positive, the dimensions of
  24 ## @var{x} are shifted to the left, with the leading dimensions
  25 ## circulated to the end.  If @var{n} is negative, then the dimensions
  26 ## of @var{x} are shifted to the right, with @var{n} leading singleton
  27 ## dimensions added.
  28 ##
  29 ## Called with a single argument, @code{shiftdim}, removes the leading
  30 ## singleton dimensions, returning the number of dimensions removed
  31 ## in the second output argument @var{ns}.
  32 ##
  33 ## For example:
  34 ##
  35 ## @example
  36 ## @group
  37 ## x = ones (1, 2, 3);
  38 ## size (shiftdim (x, -1))
  39 ##    @result{} [1, 1, 2, 3]
  40 ## size (shiftdim (x, 1))
  41 ##    @result{} [2, 3]
  42 ## [b, ns] = shiftdim (x)
  43 ##    @result{} b = [1, 1, 1; 1, 1, 1]
  44 ##    @result{} ns = 1
  45 ## @end group
  46 ## @end example
  47 ## @seealso {reshape, permute, ipermute, circshift, squeeze}
  48 ## @end deftypefn
  49
  50 function [y, ns]  = shiftdim (x, n)
  51
  52   if (nargin < 1 || nargin > 2)
  53     print_usage ();
  54   endif
  55
  56   nd = ndims (x);
  57   orig_dims = size (x);
  58
  59   if (nargin == 1)
  60     ## Find the first non-singleton dimension.
  61     (n = find (orig_dims != 1, 1) - 1) || (n = nd);
  62   elseif (! (isscalar (n) && n == fix (n)))
  63     error ("shiftdim: N must be a scalar integer");
  64   endif
  65
  66   if (n >= nd)
  67     n = rem (n, nd);
  68   endif
  69
  70   if (n < 0)
  71     singleton_dims = ones (1, -n);
  72     y = reshape (x, [singleton_dims, orig_dims]);
  73   elseif (n > 0)
  74     ## We need permute here instead of reshape to shift values in a
  75     ## compatible way.
  76     y = permute (x, [n+1:nd 1:n]);
  77   else
  78     y = x;
  79   endif
  80
  81   ns = n;
  82
  83 endfunction
  84
  85
  86 %!test
  87 %! x = rand (1, 1, 4, 2);
  88 %! [y, ns] = shiftdim (x);
  89 %! assert (size (y), [4 2]);
  90 %! assert (ns, 2);
  91 %! assert (shiftdim (y, -2), x);
  92 %! assert (size (shiftdim (x, 2)), [4 2]);
  93 %!assert (size (shiftdim (rand (0, 1, 2))), [0 1 2]);
  94
  95 %% Test input validation
  96 %!error(shiftdim ());
  97 %!error(shiftdim (1,2,3));
  98 %!error(shiftdim (1, ones (2)));
  99 %!error(shiftdim (1, 1.5));
 100