* Bug 7293 fixed: circshift() introduced
[scilab.git] / scilab / modules / elementary_functions / help / en_US / matrixmanipulation / flipdim.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) 2008 - INRIA - Farid BELAHCENE
5  * Copyright (C) 2013, 2016 - Samuel GOUGEON : 5.5.0 extensions, page overhauled
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18     xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19     xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20     xmlns:scilab="http://www.scilab.org" xml:id="flipdim" xml:lang="en">
21     <refnamediv>
22         <refname>flipdim</refname>
23         <refpurpose>reverses the order of (blocks of) rows, columns, pages.. of an array</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             y = flipdim(x, dim)
29             y = flipdim(x, dim, blockSize)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection role="parameters">
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>x, y</term>
37                 <listitem>
38                     <para>
39                         vectors, matrices, or hypermatrices of any regular data type, or cells array.
40                         <varname>y</varname> gets the sizes of <varname>x</varname>.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>dim</term>
46                 <listitem>
47                         <para>
48                             positive integer : index of the dimension / direction of <literal>x</literal>
49                             along which the order of <varname>x</varname> components must be inverted.
50                         </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>blockSize</term>
55                 <listitem>
56                     <para>
57                         a positive integer, sub-multiple of <literal>size(x,dim)</literal>:
58                         number of rows, of columns, of pages etc in each block. Default value = 1
59                     </para>
60                 </listitem>
61             </varlistentry>
62         </variablelist>
63     </refsection>
64     <refsection role="description">
65         <title>Description</title>
66         <para>
67             <literal>flipdim(x, 1)</literal> inverts the order of
68             <emphasis role="italic">rows</emphasis> of <varname>x</varname>.
69         </para>
70         <para>
71             <literal>flipdim(x, 2)</literal> inverts the order of
72             <emphasis role="italic">columns</emphasis> of <varname>x</varname>.
73         </para>
74         <para>
75             <literal>flipdim(x, 3)</literal> inverts the order of
76             <emphasis role="italic">pages</emphasis> of <varname>x</varname>. Etc.
77         </para>
78         <para>
79             The optional parameter <literal>blockSize</literal> allows splitting
80             <varname>x</varname> in <literal>size(x,1)/blockSize</literal> blocks
81             of <varname>blockSize</varname> rows (<literal>dim=1</literal>),
82             or in <literal>size(x,2)/blockSize</literal> blocks of <varname>blockSize</varname>
83             columns (<literal>dim=2</literal>), etc (<literal>dim>2</literal>)
84             and to invert their order.
85             In each block, the order of components (rows, columns, pages etc)
86             is unchanged.
87         </para>
88     </refsection>
89     <refsection role="examples">
90         <title>Examples</title>
91         <programlisting role="example"><![CDATA[
92 // Example 1: flip x rows (= components along the first dimension)
93 x = [1 2 3 4; 5 6 7 8]
94 y = flipdim(x, 1)
95
96 // Example 2: flip x columns (= components along the second dimension)
97 y = flipdim(x, 2)
98
99 // Example 3: flip x pages (= components along the third dimension)
100 x = matrix(1:24, [3 2 4])
101 y = flipdim(x, 3)
102
103 // Example 4: the first example with complex
104 x = [1+%i 2*%i 3 4; 5 6-%i 7 8*%pi*%i]
105 y = flipdim(x, 1)
106
107 // Integer-encoded numbers:
108 x = int16(grand(4, 3, 2, "uin", -9, 9))
109 y = flipdim(x, 1)
110
111 // Booleans:
112 x = (grand(3, 4, "uin", -9, 9) > 0)
113 y = flipdim(x, 2)
114
115 // Texts:
116 x = matrix(strsplit("a":"x", 1:23), 4, 6);
117 x = x+x
118 flipdim(x, 2)
119
120 // Polynomials:
121 x = inv_coeff(grand(3, 9, "uin", 0, 3), 2)
122 flipdim(x, 1)
123
124 // Rationals:
125 n = inv_coeff(grand(3, 9, "uin", 0, 3), 2);
126 d = inv_coeff(grand(3, 9, "uin", 0, 3), 2);
127 r = n./d
128 flipdim(r, 2)
129  ]]></programlisting>
130         <para>
131             Examples using <literal>blockSize</literal> :
132         </para>
133         <programlisting role="example"><![CDATA[
134 X = [0 1 2 3 4 5 6 7 8 9 10 11];
135 flipdim(X, 2, 2) // => [10 11   8 9   6 7   4 5   2 3   0 1] // Block size = 2.
136 flipdim(X, 2, 3) // => [9 10 11   6 7 8   3 4 5   0 1 2]
137 flipdim(X, 2, 4) // => [8 9 10 11   4 5 6 7   0 1 2 3]
138 flipdim(X, 2, 6) // => [6 7 8 9 10 11   0 1 2 3 4 5]
139
140 // Error if blockSize does not divide the targeted dimension of x.
141 y = flipdim(x, 2, 5); // size(X) = [1 12] and blockSize=5 does not divide 12.
142  ]]></programlisting>
143     <para>Example of results:</para>
144     <screen><![CDATA[
145 --> x
146  x  =
147  -5 -2  0  9
148   0 -7 -6  9
149  -1 -8 -7  8
150
151 --> flipdim(x, 1)
152  ans  =
153  -1 -8 -7  8
154   0 -7 -6  9
155  -5 -2  0  9
156
157 --> flipdim(x, 2)
158  ans  =
159   9  0 -2 -5
160   9 -6 -7  0
161   8 -7 -8 -1
162 ]]></screen>
163     <para></para>
164     <screen><![CDATA[
165 --> x
166  x  =
167 (:,:,1)
168   9  4 -3
169  -4 -8 -3
170
171 (:,:,2)
172   5  8  9
173   4  4  9
174
175 --> flipdim(x, 3)
176  ans  =
177 (:,:,1)
178   5  8  9
179   4  4  9
180
181 (:,:,2)
182   9  4 -3
183  -4 -8 -3
184 ]]></screen>
185     <para></para>
186     <screen><![CDATA[
187 --> x
188  x  =
189  -2  3 -5  9 -4 -8
190   2  8  4 -9  6 -6
191  -9  8  3  4 -3  4
192
193 --> flipdim(x, 2, 2)
194  ans  =
195  -4 -8 -5  9 -2  3
196   6 -6  4 -9  2  8
197  -3  4  3  4 -9  8
198
199 --> flipdim(x, 2, 3)
200  ans  =
201   9 -4 -8 -2  3 -5
202  -9  6 -6  2  8  4
203   4 -3  4 -9  8  3
204 ]]></screen>
205     </refsection>
206     <refsection role="see also">
207         <title>See also</title>
208         <simplelist type="inline">
209             <member>
210                 <link linkend="circshift">circshift</link>
211             </member>
212             <member>
213                 <link linkend="fftshift">fftshift</link>
214             </member>
215             <member>
216                 <link linkend="ifftshift">ifftshift</link>
217             </member>
218             <member>
219                 <link linkend="colon">colon</link>
220             </member>
221         </simplelist>
222     </refsection>
223     <refsection role="history">
224         <title>History</title>
225         <revhistory>
226             <revision>
227                 <revnumber>5.5.0</revnumber>
228                 <revremark>
229                     <itemizedlist>
230                         <listitem>
231                             Extension to all regular data types: booleans, integers,
232                             strings, polynomials, rationals, graphic handles, etc.
233                         </listitem>
234                         <listitem>
235                             New input argument <literal>blockSize</literal> to flip
236                             <literal>x</literal> blockwise.
237                         </listitem>
238                     </itemizedlist>
239                 </revremark>
240             </revision>
241         </revhistory>
242     </refsection>
243 </refentry>