* Bug 7293 fixed: circshift() introduced
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixmanipulation / circshift.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2017 - Samuel GOUGEON
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19         xml:lang="en" xml:id="circshift">
20     <refnamediv>
21         <refname>circshift</refname>
22         <refpurpose>
23             circularly shifts elements or subarrays of an array (regular, of structures, cells, custom)
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             B = circshift(A, shift)
30             B = circshift(A, shift, 0)
31             B = circshift(A, shifts)
32             B = circshift(A, shifts, dims)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>A, B</term>
40                 <listitem>
41                     <para>
42                         row, column, matrix or 2D array, hypermatrix or ND-array of any number of
43                         dimensions and of any sizes. <varname>B</varname> has the shape, sizes and
44                         type of <varname>A</varname>. Custom types are accepted provided that
45                         <literal>size()</literal>, insertion, and extraction operators are
46                         defined for <varname>A</varname>'s type.
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>shift</term>
52                 <listitem>
53                     <para>
54                         unique positive or negative integer: the shift to apply to indices along
55                         the first non-singleton dimension, or to linear indices of
56                         <varname>A</varname> components if <literal>0</literal> is used as third
57                         input argument.
58                     </para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>shifts</term>
63                 <listitem>
64                     <para>
65                         vector of positive or negative integers: shifts to apply on ranges along
66                         directions specified in <varname>dims</varname>
67                         (or <literal>1:length(shifts)</literal> by default).
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>dims</term>
73                 <listitem>
74                     <para>
75                         Vector of integers in <literal>[1, ndims(A)]</literal>: indices of
76                         <varname>A</varname> dimensions along which the respective
77                         <literal>shifts</literal> must be performed.
78                     </para>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82     </refsection>
83     <refsection>
84         <title>Description</title>
85         <para>
86             <literal>circshift(A, shift)</literal> shifts along the first dimension of
87             <literal>A</literal> of size > 1.
88         </para>
89         <para>
90             <literal>circshift(A, shift, 0)</literal> circularly shifts <literal>A</literal>
91             components by <varname>shift</varname> positions.
92         </para>
93         <para>
94             <literal>circshift(A, shifts)</literal> circularly shifts
95             indices of <literal>A</literal> rows by <literal>shifts(1)</literal>,
96             indices of <literal>A</literal> columns by <literal>shifts(2)</literal>,
97             indices of <literal>A</literal> layers by <literal>shifts(3)</literal>, etc.
98         </para>
99         <para>
100             <literal>circshift(A, shifts, dims)</literal> circularly shifts <literal>A</literal>
101             by <literal>shifts(1)</literal> along its dimension #<literal>dims(1)</literal>,
102             by <literal>shifts(2)</literal> along its dimension #<literal>dims(2)</literal>, etc.
103         </para>
104     </refsection>
105     <refsection>
106         <title>Examples</title>
107         <programlisting role="example"><![CDATA[
108 circshift(1:7, 2)
109 circshift(1:7, -1)
110       ]]></programlisting>
111       <screen><![CDATA[
112 --> circshift(1:7, 2)
113  ans  =
114    6.   7.   1.   2.   3.   4.   5.
115
116 --> circshift(1:7, -1)
117  ans  =
118    2.   3.   4.   5.   6.   7.   1.
119 ]]></screen>
120         <para/>
121         <programlisting role="example"><![CDATA[
122 M = matrix(1:12, 3, 4)
123 circshift(M, 1)
124 circshift(M, 1, 2)
125 circshift(M, [-1 1])
126 circshift(M, [-2 1], [2 1])
127       ]]></programlisting>
128       <screen><![CDATA[
129 --> M = matrix(1:12, 3, 4)
130  M  =
131    1.   4.   7.   10.
132    2.   5.   8.   11.
133    3.   6.   9.   12.
134
135 --> circshift(M, 1)
136  ans  =
137    3.   6.   9.   12.
138    1.   4.   7.   10.
139    2.   5.   8.   11.
140
141 --> circshift(M, 1, 2)
142  ans  =
143    10.   1.   4.   7.
144    11.   2.   5.   8.
145    12.   3.   6.   9.
146
147 --> circshift(M, [-1 1])
148  ans  =
149    11.   2.   5.   8.
150    12.   3.   6.   9.
151    10.   1.   4.   7.
152
153 --> circshift(M, [-2 1], [2 1])
154  ans  =
155    9.   12.   3.   6.
156    7.   10.   1.   4.
157    8.   11.   2.   5.
158 ]]></screen>
159         <para/>
160         <programlisting role="example"><![CDATA[
161 M = matrix(1:12, 3, 4)
162 circshift(M, 5, 0)
163       ]]></programlisting>
164       <screen><![CDATA[
165 --> circshift(M, 5, 0)
166  ans  =
167    8.    11.   2.   5.
168    9.    12.   3.   6.
169    10.   1.    4.   7.
170 ]]></screen>
171     <para>
172     <emphasis role="bold">With an hypermatrix of texts:</emphasis>
173     </para>
174         <programlisting role="example"><![CDATA[
175 t = matrix([string(1:12) strsplit("a":"l")' strsplit("A":"L")'],3,4,3)
176 circshift(t, 1, 0)
177 circshift(t, 1)
178 circshift(t, 1, 3)
179 circshift(t, [1 -1], [2 3])
180       ]]></programlisting>
181       <screen><![CDATA[
182 --> t = matrix([string(1:12) strsplit("a":"l")' strsplit("A":"L")'],3,4,3)
183  t  =
184 (:,:,1)
185 !1  4  7  10  !
186 !2  5  8  11  !
187 !3  6  9  12  !
188
189 (:,:,2)
190 !a  d  g  j  !
191 !b  e  h  k  !
192 !c  f  i  l  !
193
194 (:,:,3)
195 !A  D  G  J  !
196 !B  E  H  K  !
197 !C  F  I  L  !
198
199 --> circshift(t, 1, 0)
200  ans  =
201 (:,:,1)
202 !L  3  6  9   !
203 !1  4  7  10  !
204 !2  5  8  11  !
205
206 (:,:,2)
207 !12  c  f  i  !
208 !a   d  g  j  !
209 !b   e  h  k  !
210
211 (:,:,3)
212 !l  C  F  I  !
213 !A  D  G  J  !
214 !B  E  H  K  !
215
216 --> circshift(t, 1)
217  ans  =
218 (:,:,1)
219 !3  6  9  12  !
220 !1  4  7  10  !
221 !2  5  8  11  !
222
223 (:,:,2)
224 !c  f  i  l  !
225 !a  d  g  j  !
226 !b  e  h  k  !
227
228 (:,:,3)
229 !C  F  I  L  !
230 !A  D  G  J  !
231 !B  E  H  K  !
232
233 --> circshift(t, 1, 3)
234  ans  =
235 (:,:,1)
236 !A  D  G  J  !
237 !B  E  H  K  !
238 !C  F  I  L  !
239
240 (:,:,2)
241 !1  4  7  10  !
242 !2  5  8  11  !
243 !3  6  9  12  !
244
245 (:,:,3)
246 !a  d  g  j  !
247 !b  e  h  k  !
248 !c  f  i  l  !
249
250 --> circshift(t, [1 -1], [2 3])
251  ans  =
252 (:,:,1)
253 !j  a  d  g  !
254 !k  b  e  h  !
255 !l  c  f  i  !
256
257 (:,:,2)
258 !J  A  D  G  !
259 !K  B  E  H  !
260 !L  C  F  I  !
261
262 (:,:,3)
263 !10  1  4  7  !
264 !11  2  5  8  !
265 !12  3  6  9  !
266 ]]></screen>
267     <para>
268     <emphasis role="bold">With an array of cells:</emphasis>
269     </para>
270         <programlisting role="example"><![CDATA[
271 L = list(1,%t);
272 C = {%f "a" %i  %z
273      %t "b" %e  %s
274       0 "c" %pi L }
275 circshift(C, 1, 0)
276 circshift(C, 1)
277 circshift(C, 1, 2)
278 circshift(C, [1 -1])
279       ]]></programlisting>
280     </refsection>
281     <refsection role="see also">
282         <title>See also</title>
283         <simplelist type="inline">
284             <member>
285                 <link linkend="flipdim">flipdim</link>
286             </member>
287             <member>
288                 <link linkend="fftshift">fftshift</link>
289             </member>
290         </simplelist>
291     </refsection>
292     <refsection>
293         <title>History</title>
294         <revhistory>
295             <revision>
296                 <revnumber>6.1</revnumber>
297                 <revremark>
298                     <literal>circshift()</literal> introduced.
299                 </revremark>
300             </revision>
301         </revhistory>
302     </refsection>
303 </refentry>