1 ## Copyright (C) 2004-2012 David Bateman
3 ## This file is part of Octave.
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.
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.
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/>.
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:
30 ## x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
39 ## circshift (x, [0,1])
45 ## @seealso {permute, ipermute, shiftdim}
48 function y = circshift (x, n)
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");
68 idx = repmat ({':'}, 1, nd);
74 idx{i} = [d-b+1:d, 1:d-b];
77 idx{i} = [b+1:d, 1:b];
87 %! x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
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), [])
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])
97 %% Test input validation
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)