octave_packages/m/general/circshift.m

   1 ## Copyright (C) 2004-2012 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} =} circshift (@var{x}, @var{n})
  21 ## Circularly shift the values of the array @var{x}.  @var{n} must be
  22 ## a vector of integers no longer than the number of dimensions in
  23 ## @var{x}.  The values of @var{n} can be either positive or negative,
  24 ## which determines the direction in which the values or @var{x} are
  25 ## shifted.  If an element of @var{n} is zero, then the corresponding
  26 ## dimension of @var{x} will not be shifted.  For example:
  27 ##
  28 ## @example
  29 ## @group
  30 ## x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
  31 ## circshift (x, 1)
  32 ## @result{}  7, 8, 9
  33 ##     1, 2, 3
  34 ##     4, 5, 6
  35 ## circshift (x, -2)
  36 ## @result{}  7, 8, 9
  37 ##     1, 2, 3
  38 ##     4, 5, 6
  39 ## circshift (x, [0,1])
  40 ## @result{}  3, 1, 2
  41 ##     6, 4, 5
  42 ##     9, 7, 8
  43 ## @end group
  44 ## @end example
  45 ## @seealso {permute, ipermute, shiftdim}
  46 ## @end deftypefn
  47
  48 function y = circshift (x, n)
  49
  50   if (nargin != 2)
  51     print_usage ();
  52   endif
  53
  54   if (isempty (x))
  55     y = x;
  56     return;
  57   endif
  58
  59   nd = ndims (x);
  60   sz = size (x);
  61
  62   if (! isvector (n) || length (n) > nd)
  63     error ("circshift: N must be a vector, no longer than the number of dimension in X");
  64   elseif (any (n != fix (n)))
  65     error ("circshift: all values of N must be integers");
  66   endif
  67
  68   idx = repmat ({':'}, 1, nd);
  69   for i = 1:length (n);
  70     b = n(i);
  71     d = sz(i);
  72     if (b > 0)
  73       b = rem (b, d);
  74       idx{i} = [d-b+1:d, 1:d-b];
  75     elseif (b < 0)
  76       b = rem (abs (b), d);
  77       idx{i} = [b+1:d, 1:b];
  78     endif
  79   endfor
  80
  81   y = x(idx{:});
  82
  83 endfunction
  84
  85
  86 %!shared x
  87 %! x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
  88
  89 %!assert (circshift (x, 1), [7, 8, 9; 1, 2, 3; 4, 5, 6])
  90 %!assert (circshift (x, -2), [7, 8, 9; 1, 2, 3; 4, 5, 6])
  91 %!assert (circshift (x, [0, 1]), [3, 1, 2; 6, 4, 5; 9, 7, 8])
  92 %!assert (circshift ([], 1), [])
  93
  94 %!assert (circshift (eye (3), 1), circshift (eye (3), 1))
  95 %!assert (circshift (eye (3), 1), [0,0,1;1,0,0;0,1,0])
  96
  97 %% Test input validation
  98 %!error circshift ()
  99 %!error circshift (1)
 100 %!error circshift (1,2,3)
 101 %!error circshift (1, ones(2,2))
 102 %!error circshift (1, [1 2 3])
 103 %!error circshift (1, 1.5)
 104