summaryrefslogtreecommitdiffstats
path: root/scilab/modules/elementary_functions
diff options
context:
space:
mode:
Diffstat (limited to 'scilab/modules/elementary_functions')
-rw-r--r--scilab/modules/elementary_functions/Makefile.in2
-rw-r--r--scilab/modules/elementary_functions/help/en_US/bitwise/bitcmp.xml338
-rw-r--r--scilab/modules/elementary_functions/help/en_US/elementarymatrices/random/rand.xml15
-rw-r--r--scilab/modules/elementary_functions/help/en_US/exponential/power.xml281
-rw-r--r--scilab/modules/elementary_functions/help/en_US/extraction.xml656
-rw-r--r--scilab/modules/elementary_functions/help/en_US/insertion.xml687
-rw-r--r--scilab/modules/elementary_functions/help/en_US/matrixoperations/cumsum.xml120
-rw-r--r--scilab/modules/elementary_functions/help/en_US/matrixoperations/kron.xml14
-rw-r--r--scilab/modules/elementary_functions/help/en_US/matrixoperations/unwrap.xml306
-rw-r--r--scilab/modules/elementary_functions/help/en_US/searchandsort/gsort.xml15
-rw-r--r--scilab/modules/elementary_functions/help/en_US/setoperations/intersect.xml73
-rw-r--r--scilab/modules/elementary_functions/help/en_US/setoperations/setdiff.xml70
-rw-r--r--scilab/modules/elementary_functions/help/en_US/setoperations/union.xml157
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/exponential/power.xml241
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/extraction.xml631
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/insertion.xml657
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/matrixoperations/cumsum.xml135
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/matrixoperations/kron.xml14
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/setoperations/intersect.xml68
-rw-r--r--scilab/modules/elementary_functions/help/fr_FR/setoperations/union.xml178
-rw-r--r--scilab/modules/elementary_functions/help/images/unwrap_2D.pngbin108181 -> 0 bytes
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/bitwise/bitcmp.xml119
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/exponential/power.xml291
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/extraction.xml950
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/insertion.xml1062
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/matrixoperations/cumsum.xml89
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/matrixoperations/kron.xml14
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/matrixoperations/unwrap.xml389
-rw-r--r--scilab/modules/elementary_functions/help/ja_JP/setoperations/union.xml261
-rw-r--r--scilab/modules/elementary_functions/help/pt_BR/exponential/power.xml106
-rw-r--r--scilab/modules/elementary_functions/help/pt_BR/extraction.xml605
-rw-r--r--scilab/modules/elementary_functions/help/pt_BR/insertion.xml698
-rw-r--r--scilab/modules/elementary_functions/help/pt_BR/matrixoperations/cumsum.xml213
-rw-r--r--scilab/modules/elementary_functions/help/pt_BR/matrixoperations/kron.xml14
-rw-r--r--scilab/modules/elementary_functions/help/pt_BR/setoperations/union.xml152
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/bitwise/bitcmp.xml339
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/elementarymatrices/random/rand.xml12
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/exponential/power.xml254
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/extraction.xml611
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/insertion.xml665
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/matrixoperations/cumsum.xml96
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/matrixoperations/kron.xml24
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/searchandsort/gsort.xml13
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/setoperations/intersect.xml357
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/setoperations/setdiff.xml69
-rw-r--r--scilab/modules/elementary_functions/help/ru_RU/setoperations/union.xml167
-rw-r--r--scilab/modules/elementary_functions/includes/elem_func_gw.hxx1
-rw-r--r--scilab/modules/elementary_functions/includes/gw_elementary_functions.h2
-rw-r--r--scilab/modules/elementary_functions/macros/%_unwrap.sci158
-rw-r--r--scilab/modules/elementary_functions/macros/%sp_diag.sci8
-rw-r--r--scilab/modules/elementary_functions/macros/bitcmp.sci164
-rw-r--r--scilab/modules/elementary_functions/macros/intersect.sci16
-rw-r--r--scilab/modules/elementary_functions/macros/nchoosek.sci2
-rw-r--r--scilab/modules/elementary_functions/macros/setdiff.sci157
-rw-r--r--scilab/modules/elementary_functions/macros/union.sci59
-rw-r--r--scilab/modules/elementary_functions/macros/unwrap.sci195
-rw-r--r--scilab/modules/elementary_functions/sci_gateway/cpp/sci_issquare.cpp83
-rw-r--r--scilab/modules/elementary_functions/sci_gateway/cpp/sci_rand.cpp61
-rw-r--r--scilab/modules/elementary_functions/tests/nonreg_tests/bug_11600.tst29
-rw-r--r--scilab/modules/elementary_functions/tests/nonreg_tests/bug_16340.tst22
-rw-r--r--scilab/modules/elementary_functions/tests/nonreg_tests/bug_16476.tst23
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/bitcmp.dia.ref34
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/bitcmp.tst161
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/diag.tst43
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/intersect.tst79
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/intersect_sparse.tst139
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/setdiff.tst122
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/setdiff_boolean.tst185
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/setdiff_sparse.tst83
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/union.tst136
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/unwrap.dia.ref77
-rw-r--r--scilab/modules/elementary_functions/tests/unit_tests/unwrap.tst84
72 files changed, 7552 insertions, 6799 deletions
diff --git a/scilab/modules/elementary_functions/Makefile.in b/scilab/modules/elementary_functions/Makefile.in
index 99ea2e0..5739620 100644
--- a/scilab/modules/elementary_functions/Makefile.in
+++ b/scilab/modules/elementary_functions/Makefile.in
@@ -785,9 +785,11 @@ NMEDIT = @NMEDIT@
785OBJDUMP = @OBJDUMP@ 785OBJDUMP = @OBJDUMP@
786OBJEXT = @OBJEXT@ 786OBJEXT = @OBJEXT@
787OCAMLC = @OCAMLC@ 787OCAMLC = @OCAMLC@
788OCAMLCFLAGS = @OCAMLCFLAGS@
788OCAMLDEP = @OCAMLDEP@ 789OCAMLDEP = @OCAMLDEP@
789OCAMLLEX = @OCAMLLEX@ 790OCAMLLEX = @OCAMLLEX@
790OCAMLOPT = @OCAMLOPT@ 791OCAMLOPT = @OCAMLOPT@
792OCAMLOPTFLAGS = @OCAMLOPTFLAGS@
791OCAMLYACC = @OCAMLYACC@ 793OCAMLYACC = @OCAMLYACC@
792OPENMPI_CC = @OPENMPI_CC@ 794OPENMPI_CC = @OPENMPI_CC@
793OPENMPI_CFLAGS = @OPENMPI_CFLAGS@ 795OPENMPI_CFLAGS = @OPENMPI_CFLAGS@
diff --git a/scilab/modules/elementary_functions/help/en_US/bitwise/bitcmp.xml b/scilab/modules/elementary_functions/help/en_US/bitwise/bitcmp.xml
index 8cf44d3..b947df7 100644
--- a/scilab/modules/elementary_functions/help/en_US/bitwise/bitcmp.xml
+++ b/scilab/modules/elementary_functions/help/en_US/bitwise/bitcmp.xml
@@ -1,10 +1,7 @@
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!-- 2<!--
3 *
4 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab 3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5 * Copyright (C) 2011 - DIGITEO - Michael Baudin 4 * Copyright (C) 2020 - Samuel GOUGEON
6 *
7 * Copyright (C) 2012 - 2016 - Scilab Enterprises
8 * 5 *
9 * This file is hereby licensed under the terms of the GNU GPL v2.0, 6 * 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. 7 * pursuant to article 5.3.4 of the CeCILL v.2.1.
@@ -14,10 +11,13 @@
14 * along with this program. 11 * along with this program.
15 * 12 *
16 --> 13 -->
17<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="bitcmp" xml:lang="en"> 14<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
15 xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
16 xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
17 xmlns:scilab="http://www.scilab.org" xml:id="bitcmp" xml:lang="en">
18 <refnamediv> 18 <refnamediv>
19 <refname>bitcmp</refname> 19 <refname>bitcmp</refname>
20 <refpurpose>bitwise complement</refpurpose> 20 <refpurpose>bitwise complement of integers</refpurpose>
21 </refnamediv> 21 </refnamediv>
22 <refsynopsisdiv> 22 <refsynopsisdiv>
23 <title>Syntax</title> 23 <title>Syntax</title>
@@ -27,40 +27,66 @@
27 </synopsis> 27 </synopsis>
28 </refsynopsisdiv> 28 </refsynopsisdiv>
29 <refsection> 29 <refsection>
30 <title>Parameters</title> 30 <title>Arguments</title>
31 <variablelist> 31 <variablelist>
32 <varlistentry> 32 <varlistentry>
33 <term>x :</term> 33 <term>x, y</term>
34 <listitem>
35 <para>
36 a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
37 or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
38 or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
39 Must contain positive integer values.
40 </para>
41 </listitem>
42 </varlistentry>
43 <varlistentry>
44 <term>bitnum :</term>
45 <listitem> 34 <listitem>
46 <para> 35 arrays of signed or unsigned integers (int8, .., uint64), or of positive decimal
47 a <literal>m</literal>-by-<literal>n</literal> matrix of doubles 36 integers. Hypermatrix supported. <varname>x</varname> and <varname>y</varname>
48 or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles 37 have the same integer type and the same size.
49 or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>). 38 <para/>
50 The input <literal>n</literal> must be in the range 1, 2, ..., <literal>bitmax</literal>
51 where <literal>bitmax</literal> is the maximum number of bits in <varname>x</varname>.
52 <varname>bitnum</varname> must contain positive integer values. The default value for <varname>bitnum</varname> is <literal>bitmax</literal>.
53 </para>
54 </listitem> 39 </listitem>
55 </varlistentry> 40 </varlistentry>
56 <varlistentry> 41 <varlistentry>
57 <term>y :</term> 42 <term>bitnum</term>
58 <listitem> 43 <listitem>
59 <para> 44 positive encoded or decimal integer, or array of positive encoded or decimal
60 a <literal>m</literal>-by-<literal>n</literal> matrix of doubles 45 integers of size equal to size(x): bits #1 to #bitnum of <varname>x</varname>
61 or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles 46 are considered and inversed. According to the integer type of
62 or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers. 47 <varname>x</varname>, <varname>bitnum</varname> must be in the interval
63 </para> 48 <literal>[1, bitmax]</literal> with bitmax as follows:
49 <table>
50 <tr><th>inttype :</th>
51 <td>int8</td>
52 <td>uint8</td>
53 <td>int16</td>
54 <td>uint16</td>
55 <td>int32</td>
56 <td>uint32</td>
57 <td>int64</td>
58 <td>uint64</td>
59 <td>decimal</td>
60 </tr>
61 <tr><th>bitmax :</th>
62 <td>8</td>
63 <td>8</td>
64 <td>16</td>
65 <td>16</td>
66 <td>32</td>
67 <td>32</td>
68 <td>64</td>
69 <td>64</td>
70 <td>1024</td>
71 </tr>
72 </table>
73 <para/>
74 The default <varname>bitnum</varname> value depends on the input integer
75 type:
76 <itemizedlist>
77 <listitem>
78 <literal>bitnum = bitmax</literal> for encoded integers
79 </listitem>
80 <listitem>
81 <literal>bitnum = 53</literal> for decimal integers
82 <literal>x ≤ 1/%eps</literal>
83 </listitem>
84 <listitem>
85 <literal>bitnum = int(log2(x))+1</literal> for decimal integers
86 <literal>x > 1/%eps</literal>.
87 </listitem>
88 </itemizedlist>
89 <para/>
64 </listitem> 90 </listitem>
65 </varlistentry> 91 </varlistentry>
66 </variablelist> 92 </variablelist>
@@ -68,37 +94,243 @@
68 <refsection> 94 <refsection>
69 <title>Description</title> 95 <title>Description</title>
70 <para> 96 <para>
71 Given an unsigned integer <varname>x</varname>, this function returns the unsigned integer <varname>y</varname> 97 <literal>bitcmp(x)</literal> computes the binary complement of each element of
72 which is the integer corresponding to the complementary of the binary 98 <varname>x</varname>, and provides it in the corresponding element of <varname>y</varname>.
73 form of <varname>x</varname>.
74 </para> 99 </para>
75 <para> 100 <para>
76 The integer <varname>bitnum</varname> sets the maximum number of bits. 101 In the following description, 2^0 corresponds to the bit #1. An integer whose highest
102 bit on is #n, is in <literal>[2^(n-1), 2^n-1]</literal>.
77 </para> 103 </para>
78 <para> 104 <para>
79 If the bits number of the <varname>x</varname> binary representation is less than the 105 For <varname>x</varname> such that <literal>abs(x) ≥ 2^bitnum</literal>,
80 <literal>bitmax</literal> number (8,16 or 32) then the bits <literal>'1'</literal> are added to the 106 its bits <literal>#(bitnum+1)</literal> to <literal>#(int(log2(x))+1)</literal>
81 complementary in order to have <literal>bitmax</literal> number (8, 16 or 32) for the 107 are ignored. Only its bits <literal>#1</literal> to <literal>#bitnum</literal>
82 complementary. 108 are considered and inversed.
83 </para> 109 </para>
84 <para> 110 <para>
85 If only one input argument is given, <varname>x</varname> must be a matrix of unsigned integers. 111 Example:
112 <screen>
113--> bitget(180, 1:8)
114 ans =
115 0. 0. 1. 0. 1. 1. 0. 1.
116--> bitcmp(180, 4)
117 ans =
118 11.
119--> bitget(11, 1:8)
120 ans =
121 1. 1. 0. 1. 0. 0. 0. 0.
122</screen>
123 </para>
124 <para>
125 For <varname>x</varname> such that <literal>abs(x) &lt; 2^bitnum</literal>,
126 bits <literal>#(int(log2(x))+2)</literal> to <literal>#bitnum</literal> are padded
127 with 0. Then all bits <literal>#1</literal> to <literal>#bitnum</literal> are considered
128 and inversed.
129 </para>
130 <para>
131 Example:
132 <screen>
133--> x = 30; int(log2(30))+2
134 ans =
135 6.
136--> bitget(30, 1:10)
137 ans =
138 0. 1. 1. 1. 1. 0. 0. 0. 0. 0.
139--> bitcmp(30, 7)
140 ans =
141 97.
142--> bitget(97, 1:10)
143 ans =
144 1. 0. 0. 0. 0. 1. 1. 0. 0. 0.
145</screen>
86 </para> 146 </para>
87 </refsection> 147 </refsection>
88 <refsection> 148 <refsection>
89 <title>Examples</title> 149 <title>Examples</title>
90 <programlisting role="example"><![CDATA[ 150 <programlisting role="example"><![CDATA[
91// 13 is (1101)_2 151x = uint8(13);
92// We insert zeros in the beginning to get a 8-bit number: 152b = bitget(x, 1:8)
93// (00001101)_2 153c = bitcmp(x, 8)
94// The 8-bits complement is then (11110010)_2 154bitget(c, 1:8)
95// which is 242 1551 - b
96bitcmp(13,8)
97expected = 242
98
99// The input argument can be an unsigned int
100bitcmp(uint8(99),8)
101expected = 156
102 ]]></programlisting> 156 ]]></programlisting>
157 <screen><![CDATA[
158--> b = bitget(x, 1:8)
159 b =
160 1 0 1 1 0 0 0 0
161
162--> c = bitcmp(x, 8)
163 c =
164 242
165
166--> bitget(c, 1:8)
167 ans =
168 0 1 0 0 1 1 1 1
169
170--> 1 - b
171 ans =
172 0 1 0 0 1 1 1 1
173]]></screen>
174 <para/>
175 <para>
176 Negative encoded integers are accepted:
177 </para>
178 <programlisting role="example"><![CDATA[
179bitcmp(int8([-71 -34 -1 0 33 70]))
180bitcmp(int8([-71 -34 -1 0 33 70]), 8)
181bitcmp(int8([-71 -34 -1 0 33 70]), 7)
182bitcmp(int8([-71 -34 -1 0 33 70]), 6)
183bitcmp(int8([-71 -34 -1 0 33 70]), 5)
184bitcmp(int8([-71 -34 -1 0 33 70]), 4)
185 ]]></programlisting>
186 <screen><![CDATA[
187--> bitcmp(int8([-71 -34 -1 0 33 70]))
188 ans =
189 70 33 0 -1 -34 -71
190
191--> bitcmp(int8([-71 -34 -1 0 33 70]), 8)
192 ans =
193 70 33 0 -1 -34 -71
194
195--> bitcmp(int8([-71 -34 -1 0 33 70]), 7)
196 ans =
197 70 33 0 127 94 57
198
199--> bitcmp(int8([-71 -34 -1 0 33 70]), 6)
200 ans =
201 6 33 0 63 30 57
202
203--> bitcmp(int8([-71 -34 -1 0 33 70]), 5)
204 ans =
205 6 1 0 31 30 25
206
207--> bitcmp(int8([-71 -34 -1 0 33 70]), 4)
208 ans =
209 6 1 0 15 14 9
210]]></screen>
211 <para/>
212 <para>
213 We can work with 64-bit big integers:
214 </para>
215 <programlisting role="example"><![CDATA[
216b = (rand(1,62)<0.5)*1;
217x = sum(b .* (uint64(2).^(0:61)))
218r = bitcmp(x)
219bg = bitget(r, 1:62);
220[msprintf("%d ",b(:)) ; msprintf("%d ",bg(:))]
221 ]]></programlisting>
222 <screen><![CDATA[
223--> x = sum(b .* (uint64(2).^(0:61)))
224 x =
225 4154509482123930814
226
227--> r = bitcmp(x)
228 r =
229 14292234591585620801
230
231--> bg = bitget(r, 1:62);
232--> [msprintf("%d ",b(:)) ; msprintf("%d ",bg(:))]
233 ans =
234 "0 1 1 1 1 1 0 1 0 0 1 1 0 1 0 0 ... 1 0 0 0 0 1 0 0 1 1 1 1 1 0 0 1 0 1 1 0 0 1 1 1 "
235 "1 0 0 0 0 0 1 0 1 1 0 0 1 0 1 1 ... 0 1 1 1 1 0 1 1 0 0 0 0 0 1 1 0 1 0 0 1 1 0 0 0 "
236]]></screen>
237 <para/>
238 <para>
239 bitnum can be an array:
240 </para>
241 <programlisting role="example"><![CDATA[
242bitcmp([0 0 0 0 0], 3:7)
243 ]]></programlisting>
244 <screen><![CDATA[
245--> bitcmp([0 0 0 0 0], 3:7)
246 ans =
247 7. 15. 31. 63. 127.
248]]></screen>
249 <para/>
250 <para>
251 bitnum can be > 52:
252 </para>
253 <programlisting role="example"><![CDATA[
254format(22)
255bitcmp(2^70, 65)
256sum(2.^(13:64)) // 52 highest bits
257 ]]></programlisting>
258 <screen><![CDATA[
259--> bitcmp(2^70, 65)
260 ans =
261 36893488147419095040.
262
263--> sum(2.^(13:64))
264 ans =
265 36893488147419095040.
266]]></screen>
267 <para/>
268 <para>
269 Huge decimal numbers can be processed:
270 </para>
271 <programlisting role="example"><![CDATA[
272format(22)
273log2(1e100)
274r = bitcmp(1e100, 333)
275bitcmp(1e100) // bitnum = int(log2(x)) + 1 is used by default
276bitcmp(r, 333)
277 ]]></programlisting>
278 <screen><![CDATA[
279--> log2(1e100)
280 ans =
281 332.19280948873625903
282
283--> r = bitcmp(1e100, 333)
284 r =
285 7.498005798264093D+99
286
287--> bitcmp(1e100) // bitnum = int(log2(x)) + 1 is used by default
288 ans =
289 7.498005798264093D+99
290
291--> bitcmp(r, 333)
292 ans =
293 1.00000000000000D+100
294]]></screen>
295 </refsection>
296 <refsection role="see also">
297 <title>See Also</title>
298 <simplelist type="inline">
299 <member>
300 <link linkend="bitxor">bitxor</link>
301 </member>
302 <member>
303 <link linkend="bitget">bitget</link>
304 </member>
305 <member>
306 <link linkend="minus">minus</link>
307 </member>
308 </simplelist>
309 </refsection>
310 <refsection role="history">
311 <title>History</title>
312 <revhistory>
313 <revision>
314 <revnumber>6.1.1</revnumber>
315 <revdescription>
316 <itemizedlist>
317 <listitem>
318 Extension to 64 bit integers.
319 </listitem>
320 <listitem>
321 Extension to all signed integers.
322 </listitem>
323 <listitem>
324 Decimal positive integers > 2^52 up to 2^1024 = number_properties("huge")
325 can now be processed, with bitnum up to 1024 instead of 52.
326 </listitem>
327 <listitem>
328 bitnum is now optional as well for input decimal integers.
329 It can actually be an array.
330 </listitem>
331 </itemizedlist>
332 </revdescription>
333 </revision>
334 </revhistory>
103 </refsection> 335 </refsection>
104</refentry> 336</refentry>
diff --git a/scilab/modules/elementary_functions/help/en_US/elementarymatrices/random/rand.xml b/scilab/modules/elementary_functions/help/en_US/elementarymatrices/random/rand.xml
index 9834aad..25e0851 100644
--- a/scilab/modules/elementary_functions/help/en_US/elementarymatrices/random/rand.xml
+++ b/scilab/modules/elementary_functions/help/en_US/elementarymatrices/random/rand.xml
@@ -54,8 +54,15 @@
54 <listitem> 54 <listitem>
55 <para> 55 <para>
56 a string, the distribution of random numbers (default <literal>key="uniform" </literal>). 56 a string, the distribution of random numbers (default <literal>key="uniform" </literal>).
57 The available values are <literal>"uniform"</literal> and 57 The possible values are:
58 <literal>"normal"</literal>. 58 <itemizedlist>
59 <listitem>
60 <literal>"uniform"</literal> or <literal>"u"</literal>
61 </listitem>
62 <listitem>
63 <literal>"normal"</literal> or <literal>"n"</literal>
64 </listitem>
65 </itemizedlist>
59 </para> 66 </para>
60 </listitem> 67 </listitem>
61 </varlistentry> 68 </varlistentry>
@@ -144,7 +151,7 @@
144 </para> 151 </para>
145 <variablelist> 152 <variablelist>
146 <varlistentry> 153 <varlistentry>
147 <term>rand("uniform")</term> 154 <term>rand("uniform") or rand("u")</term>
148 <listitem> 155 <listitem>
149 <para> 156 <para>
150 sets the generator to a uniform random number 157 sets the generator to a uniform random number
@@ -154,7 +161,7 @@
154 </listitem> 161 </listitem>
155 </varlistentry> 162 </varlistentry>
156 <varlistentry> 163 <varlistentry>
157 <term>rand("normal")</term> 164 <term>rand("normal") or rand("n")</term>
158 <listitem> 165 <listitem>
159 <para> 166 <para>
160 sets the generator to a normal (Gauss-Laplace) random number generator, 167 sets the generator to a normal (Gauss-Laplace) random number generator,
diff --git a/scilab/modules/elementary_functions/help/en_US/exponential/power.xml b/scilab/modules/elementary_functions/help/en_US/exponential/power.xml
index 2384b7a..4c74ea6 100644
--- a/scilab/modules/elementary_functions/help/en_US/exponential/power.xml
+++ b/scilab/modules/elementary_functions/help/en_US/exponential/power.xml
@@ -1,138 +1,196 @@
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="power"> 2<!--
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 2012 - 2016 - Scilab Enterprises
5 * Copyright (C) 2020 - Samuel GOUGEON
6 *
7 * This file is hereby licensed under the terms of the GNU GPL v2.0,
8 * pursuant to article 5.3.4 of the CeCILL v.2.1.
9 * This file was originally licensed under the terms of the CeCILL v2.1,
10 * and continues to be available under such terms.
11 * For more information, see the COPYING file which you should have received
12 * along with this program.
13 *
14-->
15<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
16 xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
17 xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
18 xml:lang="en" xml:id="power">
3 <refnamediv> 19 <refnamediv>
4 <refname>power</refname> 20 <refname>power</refname>
5 <refpurpose>(^,.^) power operation</refpurpose> 21 <refpurpose>(^,.^) power operation</refpurpose>
6 </refnamediv> 22 </refnamediv>
7 <refsynopsisdiv> 23 <refsynopsisdiv>
8 <title>Syntax</title> 24 <title>Syntax</title>
9 <synopsis>t=A^b 25 <synopsis>
10 t=A**b 26 t = A ^ b
11 t=A.^b 27 t = A ** b
28 t = A .^ b
12 </synopsis> 29 </synopsis>
13 </refsynopsisdiv> 30 </refsynopsisdiv>
14 <refsection> 31 <refsection>
15 <title>Arguments</title> 32 <title>Arguments</title>
16 <variablelist> 33 <variablelist>
17 <varlistentry> 34 <varlistentry>
18 <term>A,t</term> 35 <term>A, t</term>
19 <listitem> 36 <listitem>
20 <para>scalar, polynomial or rational matrix.</para> 37 a scalar, vector, or matrix of encoded integers, decimal or complex numbers,
38 polynomials, or rationals.
39 <para/>
21 </listitem> 40 </listitem>
22 </varlistentry> 41 </varlistentry>
23 <varlistentry> 42 <varlistentry>
24 <term>b</term> 43 <term>b</term>
25 <listitem> 44 <listitem>
26 <para>a scalar, a vector or a scalar matrix.</para> 45 a scalar, vector, or matrix of encoded integers, decimal or complex numbers.
46 <para/>
27 </listitem> 47 </listitem>
28 </varlistentry> 48 </varlistentry>
29 </variablelist> 49 </variablelist>
30 </refsection>
31 <refsection>
32 <title>Description</title>
33 <itemizedlist>
34 <listitem>
35 <para>
36 If <literal>A</literal> is a square matrix and <literal>b</literal> is a scalar then <literal>A^b</literal> is the matrix <literal>A</literal> to the power <literal>b</literal>.
37 </para>
38 </listitem>
39 <listitem>
40 <para>
41 If <literal>b</literal> is a scalar and <literal>A</literal> a matrix then
42 <literal>A.^b</literal> is the matrix formed by the element of
43 <literal>A</literal> to the power <literal>b</literal> (element-wise power). If
44 <literal>A</literal> is a vector and <literal>b</literal> is a scalar then
45 <literal>A^b</literal> and <literal>A.^b</literal> performs the same operation
46 (i.e. element-wise power).
47 </para>
48 </listitem>
49 <listitem>
50 <para>
51 If <literal>A</literal> is a scalar and <literal>b</literal> is a square matrix <literal>A^b</literal> is the matrix <literal> expm(log(A) * b)</literal>.
52 </para>
53 <para>
54 If <literal>A</literal> is a scalar and <literal>b</literal> is a vector <literal>A^b</literal> and <literal>A.^b</literal> are the vector formed by <literal> a^(b(i,j))</literal>.
55 </para>
56 <para>
57 If <literal>A</literal> is a scalar and <literal>b</literal> is a matrix <literal>A.^b</literal> is the matrix formed by <literal> a^(b(i,j))</literal>.
58 </para>
59 </listitem>
60 <listitem>
61 <para>
62 If <literal>A</literal> and <literal>b</literal> are vectors (matrices) of the same size <literal>A.^b</literal> is the <literal>A(i)^b(i)</literal> vector (<literal>A(i,j)^b(i,j)</literal> matrix).
63 </para>
64 </listitem>
65 </itemizedlist>
66 </refsection>
67 <refsection>
68 <title>Additional Remarks</title>
69 <para>
70 <note> Notes: </note>
71 </para>
72 <para>
73 1. For square matrices <literal>A^p</literal> is computed through successive matrices
74 multiplications if <literal>p</literal> is a positive integer, and by <emphasis>diagonalization</emphasis> if not (see "note 2 and 3" below for details).
75 </para>
76 <para>
77 2. If <varname>A</varname> is a square and Hermitian matrix and <varname>p</varname> is a non-integer scalar,
78 <literal>A^p</literal> is computed as:
79 </para>
80 <para>
81 <code>A^p = u*diag(diag(s).^p)*u'</code> (For real matrix <varname>A</varname>, only the real part of the answer is taken into account).
82 </para>
83 <para>
84 <varname>u</varname> and <varname>s</varname> are determined by <code>[u,s] = schur(A)</code> .
85 </para>
86 <para>
87 3. If <varname>A</varname> is not a Hermitian matrix and <varname>p</varname> is a non-integer scalar,
88 <literal>A^p</literal> is computed as:
89 </para>
90 <para>
91 <code>A^p = v*diag(diag(d).^p)*inv(v)</code> (For real matrix <varname>A</varname>, only the real part of the answer is taken into account).
92 </para>
93 <para>
94 <varname>d</varname> and <varname>v</varname> are determined by <code>[d,v] = bdiag(A+0*%i)</code> .
95 </para>
96 <para>
97 4. If <varname>A</varname> and <varname>p</varname> are real or complex numbers,
98 <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by:
99 </para>
100 <para>
101 <code>A^p = exp(p*log(A))</code> (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ).
102 </para>
103 <para> 50 <para>
104 5. If <varname>A</varname> is a square matrix and <varname>p</varname> is a real or complex number, 51 If an operand are encoded integers, the other one can be only encoded integers or real
105 <literal>A.^p</literal> is the <emphasis>principal value</emphasis> computed as: 52 numbers.
106 </para> 53 </para>
107 <para> 54 <para>
108 <code>A.^p = exp(p*log(A))</code> (same as case 4 above). 55 If <varname>A</varname> are polynomials or rationals, <varname>b</varname> can only be
109 </para> 56 a single decimal (positive or negative) integer.
110 <para>
111 6. <literal>**</literal> and <literal>^</literal> operators are synonyms.
112 </para>
113 <para>
114 <warning>
115 Exponentiation is right-associative in Scilab contrarily to Matlab® and Octave.
116 For example 2^3^4 is equal to 2^(3^4) in Scilab but is equal to (2^3)^4 in Matlab®
117 and Octave.
118 </warning>
119 </para> 57 </para>
120 </refsection> 58 </refsection>
121 <refsection> 59 <refsection>
60 <title>Description</title>
61 <refsect3>
62 <title>.^ by-element power</title>
63 <para>
64 If <varname>A</varname> or <varname>b</varname> is scalar, it is first
65 replicated to the size of the other, with A*ones(b) or b*ones(A).
66 Otherwise, <varname>A</varname> and <varname>b</varname> must have the same size.
67 </para>
68 <para>
69 Then, for each element of index i, <literal>t(i) = A(i)^b(i)</literal>
70 is computed.
71 </para>
72 </refsect3>
73 <refsect3>
74 <title>^ matricial power</title>
75 <para>
76 The ^ operator is equivalent to the .^ by-element power in the following cases:
77 <itemizedlist>
78 <listitem>
79 <varname>A</varname> is scalar and <varname>b</varname> is a vector.
80 </listitem>
81 <listitem>
82 <varname>A</varname> is a vector and <varname>b</varname> is scalar.
83 </listitem>
84 </itemizedlist>
85 Otherwise, <varname>A</varname> or <varname>b</varname> must be a scalar,
86 and the other one must be a square matrix:
87 <itemizedlist>
88 <listitem>
89 <para>
90 If <varname>A</varname> is scalar and <varname>b</varname> is
91 a square matrix, then <literal>A^b</literal> is the matrix
92 <literal>expm(log(A) * b)</literal>
93 </para>
94 </listitem>
95 <listitem>
96 <para>
97 If <varname>A</varname> is a square matrix and <varname>b</varname>
98 is scalar, then <literal>A^b</literal> is the matrix
99 <varname>A</varname> to the power <varname>b</varname>.
100 </para>
101 </listitem>
102 </itemizedlist>
103 </para>
104 </refsect3>
105 <refsect3>
106 <title>Remarks</title>
107 <orderedlist>
108 <listitem>
109 <para>
110 For square matrices <literal>A^p</literal> is computed through successive
111 matrices multiplications if <literal>p</literal> is a positive integer, and by
112 <emphasis>diagonalization</emphasis> if not (see "note 2 and 3" below for details).
113 </para>
114 </listitem>
115 <listitem>
116 <para>
117 If <varname>A</varname> is a square and Hermitian matrix and <literal>p</literal>
118 is a non-integer scalar, <literal>A^p</literal> is computed as:
119 </para>
120 <para>
121 <code>A^p = u*diag(diag(s).^p)*u'</code> (For real matrix <varname>A</varname>,
122 only the real part of the answer is taken into account).
123 </para>
124 <para>
125 <literal>u</literal> and <literal>s</literal> are determined by
126 <code>[u,s] = schur(A)</code> .
127 </para>
128 </listitem>
129 <listitem>
130 <para>
131 If <varname>A</varname> is not a Hermitian matrix and <literal>p</literal> is a
132 non-integer scalar, <literal>A^p</literal> is computed as:
133 </para>
134 <para>
135 <code>A^p = v*diag(diag(d).^p)*inv(v)</code> (For real matrix <varname>A</varname>,
136 only the real part of the answer is taken into account).
137 </para>
138 <para>
139 <literal>d</literal> and <literal>v</literal> are determined by
140 <code>[d,v] = bdiag(A+0*%i)</code>.
141 </para>
142 </listitem>
143 <listitem>
144 <para>
145 If <varname>A</varname> and <literal>p</literal> are real or complex numbers,
146 <literal>A^p</literal> is the <emphasis>principal value</emphasis> determined by
147 </para>
148 <para>
149 <code>A^p = exp(p*log(A))</code>
150 </para>
151 <para>
152 (or <code>A^p = exp(p*(log(abs(A))+ %i*atan(imag(A)/real(A))))</code> ).
153 </para>
154 </listitem>
155 <listitem>
156 <para>
157 If <varname>A</varname> is a square matrix and <literal>p</literal> is a real or
158 complex number, <literal>A.^p</literal> is the <emphasis>principal value</emphasis>
159 computed as:
160 </para>
161 <para>
162 <code>A.^p = exp(p*log(A))</code> (same as case 4 above).
163 </para>
164 </listitem>
165 <listitem>
166 <para>
167 <literal>**</literal> and <literal>^</literal> operators are synonyms.
168 </para>
169 </listitem>
170 </orderedlist>
171 <para>
172 <warning>
173 Exponentiation is right-associative in Scilab, contrarily to Matlab® and Octave.
174 For example 2^3^4 is equal to 2^(3^4) in Scilab, but to (2^3)^4 in Matlab® and Octave.
175 </warning>
176 </para>
177 </refsect3>
178 </refsection>
179 <refsection>
122 <title>Examples</title> 180 <title>Examples</title>
123 <programlisting role="example"><![CDATA[ 181 <programlisting role="example"><![CDATA[
124A=[1 2;3 4]; 182A = [1 2 ; 3 4];
125A^2.5, 183A ^ 2.5,
126A.^2.5 184A .^ 2.5
127(1:10)^2 185(1:10) ^ 2
128(1:10).^2 186(1:10) .^ 2
129 187
130A^%i 188A ^ %i
131A.^%i 189A .^ %i
132exp(%i*log(A)) 190exp(%i*log(A))
133 191
134s=poly(0,'s') 192s = poly(0,'s')
135s^(1:10) 193s ^ (1:10)
136 ]]></programlisting> 194 ]]></programlisting>
137 </refsection> 195 </refsection>
138 <refsection role="see also"> 196 <refsection role="see also">
@@ -142,8 +200,27 @@ s^(1:10)
142 <link linkend="exp">exp</link> 200 <link linkend="exp">exp</link>
143 </member> 201 </member>
144 <member> 202 <member>
203 <link linkend="expm">expm</link>
204 </member>
205 <member>
145 <link linkend="hat">hat</link> 206 <link linkend="hat">hat</link>
146 </member> 207 </member>
208 <member>
209 <link linkend="inv">inv</link>
210 </member>
147 </simplelist> 211 </simplelist>
148 </refsection> 212 </refsection>
213 <refsection role="history">
214 <title>History</title>
215 <revhistory>
216 <revision>
217 <revnumber>6.0.0</revnumber>
218 <revdescription>
219 With decimal or complex numbers, <literal>scalar ^ squareMat</literal> now
220 yields <literal>expm(log(scalar)*squareMat)</literal> instead of
221 <literal>scalar .^ squareMat</literal>
222 </revdescription>
223 </revision>
224 </revhistory>
225 </refsection>
149</refentry> 226</refentry>
diff --git a/scilab/modules/elementary_functions/help/en_US/extraction.xml b/scilab/modules/elementary_functions/help/en_US/extraction.xml
index f7d4515..51a5896 100644
--- a/scilab/modules/elementary_functions/help/en_US/extraction.xml
+++ b/scilab/modules/elementary_functions/help/en_US/extraction.xml
@@ -1,5 +1,8 @@
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="en"> 2<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
4 xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
5 xmlns:scilab="http://www.scilab.org" xml:id="extraction" xml:lang="en">
3 <refnamediv> 6 <refnamediv>
4 <refname>extraction</refname> 7 <refname>extraction</refname>
5 <refpurpose>matrix and list entry extraction</refpurpose> 8 <refpurpose>matrix and list entry extraction</refpurpose>
@@ -10,8 +13,8 @@
10 x(i) 13 x(i)
11 x(i,j) 14 x(i,j)
12 x(i,j,k,..) 15 x(i,j,k,..)
13 [...]=l(i) 16 [...] = l(i)
14 [...]=l(k1)...(kn)(i) or [...]=l(list(k1,...,kn,i)) 17 [...] = l(k1)...(kn)(i) or [...] = l(list(k1,...,kn,i))
15 l(k1)...(kn)(i,j) or l(list(k1,...,kn,list(i,j)) 18 l(k1)...(kn)(i,j) or l(list(k1,...,kn,list(i,j))
16 </synopsis> 19 </synopsis>
17 </refsynopsisdiv> 20 </refsynopsisdiv>
@@ -46,354 +49,360 @@
46 </refsection> 49 </refsection>
47 <refsection> 50 <refsection>
48 <title>Description</title> 51 <title>Description</title>
49 <variablelist> 52 <refsect3>
50 <varlistentry> 53 <title>Matrix case</title>
51 <term>MATRIX CASE</term> 54 <para>
55 <literal>i</literal>, <literal>j</literal>,
56 <literal>k</literal>,.. can be:
57 </para>
58 <variablelist>
59 <varlistentry>
60 <term>a real scalar or a vector or a matrix with positive
61 elements.
62 </term>
52 <listitem> 63 <listitem>
53 <para> 64 <itemizedlist>
54 <literal>i</literal>, <literal>j</literal>, 65 <listitem>
55 <literal>k</literal>,.. can be: 66 <para>
56 </para> 67 <literal>r=x(i,j)</literal> builds the matrix
57 <variablelist> 68 <literal>r</literal> such as
58 <varlistentry> 69 <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal> for
59 <term>a real scalar or a vector or a matrix with positive 70 <literal>l</literal> from 1 to
60 elements. 71 <literal>size(i,'*')</literal> and <literal>k</literal>
61 </term> 72 from 1 to <literal>size(j,'*')</literal>.
62 <listitem> 73 </para>
63 <itemizedlist> 74 <para>
64 <listitem> 75 <literal>i</literal> (<literal>j</literal>) Maximum
65 <para> 76 value must be less or equal to
66 <literal>r=x(i,j)</literal> builds the matrix 77 <literal>size(x,1)</literal>
67 <literal>r</literal> such as 78 (<literal>size(x,2)</literal>).
68 <literal>r(l,k)=x(int(i(l)),int(j(k)))</literal> for 79 </para>
69 <literal>l</literal> from 1 to 80 </listitem>
70 <literal>size(i,'*')</literal> and <literal>k</literal> 81 <listitem>
71 from 1 to <literal>size(j,'*')</literal>. 82 <para>
72 </para> 83 <literal>r=x(i)</literal> with <literal>x</literal>
73 <para> 84 a 1x1 matrix builds the matrix <literal>r</literal> such
74 <literal>i</literal> (<literal>j</literal>) Maximum 85 as <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> for
75 value must be less or equal to 86 <literal>l</literal> from 1 to
76 <literal>size(x,1)</literal> 87 <literal>size(i,1)</literal> and <literal>k</literal> from
77 (<literal>size(x,2)</literal>). 88 1 to <literal>size(i,2)</literal>.
78 </para> 89 </para>
79 </listitem> 90 <para>
80 <listitem> 91 Note that in this case index <literal>i</literal> is
81 <para> 92 valid only if all its entries are equal to one.
82 <literal>r=x(i)</literal> with <literal>x</literal> 93 </para>
83 a 1x1 matrix builds the matrix <literal>r</literal> such 94 </listitem>
84 as <literal>r(l,k)=x(int(i(l)),int(i(k)))</literal> for 95 <listitem>
85 <literal>l</literal> from 1 to 96 <para>
86 <literal>size(i,1)</literal> and <literal>k</literal> from 97 <literal>r=x(i)</literal> with <literal>x</literal>
87 1 to <literal>size(i,2)</literal>. 98 a row vector builds the row vector <literal>r</literal>
88 </para> 99 such as <literal>r(l)=x(int(i(l)))</literal> for
89 <para> 100 <literal>l</literal> from 1 to
90 Note that in this case index <literal>i</literal> is 101 <literal>size(i,'*')</literal><literal>i</literal> Maximum
91 valid only if all its entries are equal to one. 102 value must be less or equal to
92 </para> 103 <literal>size(x,'*')</literal>.
93 </listitem> 104 </para>
94 <listitem> 105 </listitem>
95 <para> 106 <listitem>
96 <literal>r=x(i)</literal> with <literal>x</literal> 107 <para>
97 a row vector builds the row vector <literal>r</literal> 108 <literal>r=x(i)</literal> with <literal>x</literal>
98 such as <literal>r(l)=x(int(i(l)))</literal> for 109 a matrix with one or more columns builds the column vector
99 <literal>l</literal> from 1 to 110 <literal>r</literal> such as <literal>r(l)</literal>
100 <literal>size(i,'*')</literal><literal>i</literal> Maximum 111 (<literal>l</literal> from 1 to
101 value must be less or equal to 112 <literal>size(i,'*')</literal>) contains the
102 <literal>size(x,'*')</literal>. 113 <literal>int(i(l))</literal> entry of the column vector
103 </para> 114 formed by the concatenation of the <literal>x</literal>'s
104 </listitem> 115 columns.
105 <listitem> 116 </para>
106 <para> 117 <para>
107 <literal>r=x(i)</literal> with <literal>x</literal> 118 <literal>i</literal> Maximum value must be less or
108 a matrix with one or more columns builds the column vector 119 equal to <literal>size(x,'*')</literal>.
109 <literal>r</literal> such as <literal>r(l)</literal> 120 </para>
110 (<literal>l</literal> from 1 to 121 </listitem>
111 <literal>size(i,'*')</literal>) contains the 122 </itemizedlist>
112 <literal>int(i(l))</literal> entry of the column vector
113 formed by the concatenation of the <literal>x</literal>'s
114 columns.
115 </para>
116 <para>
117 <literal>i</literal> Maximum value must be less or
118 equal to <literal>size(x,'*')</literal>.
119 </para>
120 </listitem>
121 </itemizedlist>
122 </listitem>
123 </varlistentry>
124 <varlistentry>
125 <term>
126 the symbol <literal>: </literal>
127 </term>
128 <listitem>
129 <para><literal/>
130 which stands for "all elements".
131 </para>
132 <itemizedlist>
133 <listitem>
134 <para>
135 <literal>r=x(i,:)</literal> builds the matrix
136 <literal>r</literal> such as
137 <literal>r(l,k)=x(int(i(l)),k))</literal> for
138 <literal>l</literal> from 1 to
139 <literal>size(i,'*')</literal> and <literal>k</literal>
140 from 1 to <literal>size(x,2)</literal>
141 </para>
142 </listitem>
143 <listitem>
144 <para>
145 <literal>r=x(:,j)</literal> builds the matrix
146 <literal>r</literal> such as
147 <literal>r(l,k)=x(l,int(j(k)))</literal> for
148 <literal>l</literal> from 1 to
149 <literal>size(r,1)</literal> and <literal>k</literal> from
150 1 to <literal>size(j,'*')</literal>.
151 </para>
152 </listitem>
153 <listitem>
154 <para>
155 <literal>r=x(:)</literal> builds the column vector
156 <literal>r</literal> formed by the column concatenations
157 of <literal>x</literal> columns. It is equivalent to
158 <literal>matrix(x,size(x,'*'),1)</literal>.
159 </para>
160 </listitem>
161 </itemizedlist>
162 </listitem>
163 </varlistentry>
164 <varlistentry>
165 <term>a vector of boolean</term>
166 <listitem>
167 <para>
168 If an index (<literal>i</literal> or
169 <literal>j</literal>) is a vector of booleans it is
170 interpreted as <literal>find(i)</literal> or respectively
171 <literal>find(j)</literal>
172 </para>
173 </listitem>
174 </varlistentry>
175 <varlistentry>
176 <term>a polynomial</term>
177 <listitem>
178 <para>
179 If an index (<literal>i</literal> or
180 <literal>j</literal>) is a vector of polynomials or implicit
181 polynomial vector it is interpreted as
182 <literal>horner(i,m)</literal> or respectively
183 <literal>horner(j,n)</literal> where <literal>m</literal> and
184 <literal>n</literal> are associated <literal>x</literal>
185 dimensions. Even if this feature works for all polynomials, it
186 is recommended to use polynomials in <literal>$</literal> for
187 readability.
188 </para>
189 </listitem>
190 </varlistentry>
191 </variablelist>
192 <para>
193 For matrices with more than 2 dimensions (see:<link linkend="hypermatrices">hypermatrices</link>) the dimensionality
194 is automatically reduced when right-most dimensions are equal to
195 1.
196 </para>
197 </listitem> 123 </listitem>
198 </varlistentry> 124 </varlistentry>
199 <varlistentry> 125 <varlistentry>
200 <term>LIST OR TLIST CASE</term> 126 <term>
127 the symbol <literal>: </literal>
128 </term>
201 <listitem> 129 <listitem>
202 <para> 130 <para><literal/>
203 If they are present the <literal>ki</literal> give the path to 131 which stands for "all elements".
204 a sub-list entry of <literal>l</literal> data structure. They allow 132 </para>
205 a recursive extraction without intermediate copies. The 133 <itemizedlist>
206 instructions 134 <listitem>
207 </para> 135 <para>
208 <para> 136 <literal>r=x(i,:)</literal> builds the matrix
209 <literal>[...]=l(k1)...(kn)(i)</literal> 137 <literal>r</literal> such as
210 </para> 138 <literal>r(l,k)=x(int(i(l)),k))</literal> for
211 <para>and</para> 139 <literal>l</literal> from 1 to
212 <para> 140 <literal>size(i,'*')</literal> and <literal>k</literal>
213 <literal>[...]=l(list(k1,...,kn,i))</literal> 141 from 1 to <literal>size(x,2)</literal>
214 </para> 142 </para>
215 <para>are interpreted as:</para> 143 </listitem>
216 <para> 144 <listitem>
217 <literal>lk1 = l(k1)</literal> 145 <para>
218 </para> 146 <literal>r=x(:,j)</literal> builds the matrix
219 <para> 147 <literal>r</literal> such as
220 <literal>.. = .. </literal> 148 <literal>r(l,k)=x(l,int(j(k)))</literal> for
221 </para> 149 <literal>l</literal> from 1 to
222 <para> 150 <literal>size(r,1)</literal> and <literal>k</literal> from
223 <literal>lkn = lkn-1(kn)</literal> 151 1 to <literal>size(j,'*')</literal>.
224 </para> 152 </para>
225 <para> 153 </listitem>
226 <literal>[...] = lkn(i)</literal>. 154 <listitem>
227 </para> 155 <para>
228 <para> 156 <literal>r=x(:)</literal> builds the column vector
229 And the <literal>l(k1)...(kn)(i,j)</literal> and 157 <literal>r</literal> formed by the column concatenations
230 </para> 158 of <literal>x</literal> columns. It is equivalent to
231 <para> 159 <literal>matrix(x,size(x,'*'),1)</literal>.
232 <literal>l(list(k1,...,kn,list(i,j))</literal> instructions 160 </para>
233 are interpreted as: 161 </listitem>
234 </para> 162 </itemizedlist>
235 <para>
236 <literal>lk1 = l(k1)</literal>
237 </para>
238 <para>
239 <literal>.. = .. </literal>
240 </para>
241 <para>
242 <literal>lkn = lkn-1(kn)</literal>
243 </para>
244 <para>
245 <literal>
246 lkn(i,j)
247 </literal>
248 </para>
249 <para>
250 When path points to more than one list component, the
251 instruction must have as many left-hand side arguments as selected
252 components. But if the extraction syntax is used as function
253 parameters, each returned list component is added to the
254 function parameters.
255 </para>
256 <para>
257 Note that <literal>l(list())</literal> is the same as
258 <literal>l</literal>.
259 </para>
260 <variablelist>
261 <varlistentry>
262 <term>i and j may be:</term>
263 <listitem>
264 <variablelist>
265 <varlistentry>
266 <term>real scalar or vector or matrix with positive
267 elements.
268 </term>
269 <listitem>
270 <para>
271 <literal>[r1,...rn]=l(i)</literal> extracts the
272 <literal>i(k)</literal> elements from the list <literal>l</literal> and store
273 them in <literal>rk</literal> variables for
274 <literal>k</literal> from 1 to
275 <literal>size(i,'*')</literal>
276 </para>
277 </listitem>
278 </varlistentry>
279 <varlistentry>
280 <term>
281 the symbol <literal>: </literal>
282 </term>
283 <listitem>
284 <para>which stands for "all elements".</para>
285 </listitem>
286 </varlistentry>
287 <varlistentry>
288 <term>a vector of booleans.</term>
289 <listitem>
290 <para>
291 If <literal>i</literal> is a vector of booleans it is
292 interpreted as <literal>find(i)</literal>.
293 </para>
294 </listitem>
295 </varlistentry>
296 <varlistentry>
297 <term>a polynomial</term>
298 <listitem>
299 <para>
300 If <literal>i</literal> is a vector of polynomials or
301 implicit polynomial vector it is interpreted as
302 <literal>horner(i,m)</literal> where
303 <literal>m=size(l)</literal>. Even if this feature works for
304 all polynomials, it is recommended to use polynomials in
305 <literal>$</literal> for readability.
306 </para>
307 </listitem>
308 </varlistentry>
309 </variablelist>
310 </listitem>
311 </varlistentry>
312 <varlistentry>
313 <term>k1 ... kn may be :</term>
314 <listitem>
315 <variablelist>
316 <varlistentry>
317 <term>real positive scalar</term>
318 <listitem>
319 <para/>
320 </listitem>
321 </varlistentry>
322 <varlistentry>
323 <term>a polynomial</term>
324 <listitem>
325 <para>
326 interpreted as <literal>horner(ki,m)</literal> where
327 <literal>m</literal> is the corresponding sub-list
328 size.
329 </para>
330 </listitem>
331 </varlistentry>
332 <varlistentry>
333 <term>a character string</term>
334 <listitem>
335 <para>associated with a sub-list entry name.</para>
336 </listitem>
337 </varlistentry>
338 </variablelist>
339 </listitem>
340 </varlistentry>
341 </variablelist>
342 </listitem> 163 </listitem>
343 </varlistentry> 164 </varlistentry>
344 </variablelist> 165 <varlistentry>
345 </refsection> 166 <term>a vector of boolean</term>
346 <refsection> 167 <listitem>
347 <title>Remarks</title> 168 <para>
348 <para>For soft coded matrix types such as rational functions and state 169 If an index (<literal>i</literal> or
349 space linear systems, <literal>x(i)</literal> syntax may not be used for 170 <literal>j</literal>) is a vector of booleans it is
350 vector element extraction due to confusion with list element extraction. 171 interpreted as <literal>find(i)</literal> or respectively
351 <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be 172 <literal>find(j)</literal>
352 used. 173 </para>
353 </para> 174 </listitem>
175 </varlistentry>
176 <varlistentry>
177 <term>a polynomial</term>
178 <listitem>
179 <para>
180 If an index (<literal>i</literal> or
181 <literal>j</literal>) is a vector of polynomials or implicit
182 polynomial vector it is interpreted as
183 <literal>horner(i,m)</literal> or respectively
184 <literal>horner(j,n)</literal> where <literal>m</literal> and
185 <literal>n</literal> are associated <literal>x</literal>
186 dimensions. Even if this feature works for all polynomials, it
187 is recommended to use polynomials in <literal>$</literal> for
188 readability.
189 </para>
190 </listitem>
191 </varlistentry>
192 </variablelist>
193 <para>
194 For matrices with more than 2 dimensions (see:<link linkend="hypermatrices">hypermatrices</link>) the dimensionality
195 is automatically reduced when right-most dimensions are equal to
196 1.
197 </para>
198 </refsect3>
199 <refsect3>
200 <title>List or Tlist case</title>
201 <para>
202 If they are present the <literal>ki</literal> give the path to
203 a sub-list entry of <literal>l</literal> data structure. They allow
204 a recursive extraction without intermediate copies. The
205 instructions
206 </para>
207 <para>
208 <literal>[...]=l(k1)...(kn)(i)</literal>
209 </para>
210 <para>and</para>
211 <para>
212 <literal>[...]=l(list(k1,...,kn,i))</literal>
213 </para>
214 <para>are interpreted as:</para>
215 <para>
216 <literal>lk1 = l(k1)</literal>
217 </para>
218 <para>
219 <literal>.. = .. </literal>
220 </para>
221 <para>
222 <literal>lkn = lkn-1(kn)</literal>
223 </para>
224 <para>
225 <literal>[...] = lkn(i)</literal>.
226 </para>
227 <para>
228 And the <literal>l(k1)...(kn)(i,j)</literal> and
229 </para>
230 <para>
231 <literal>l(list(k1,...,kn,list(i,j))</literal> instructions
232 are interpreted as:
233 </para>
234 <para>
235 <literal>lk1 = l(k1)</literal>
236 </para>
237 <para>
238 <literal>.. = .. </literal>
239 </para>
240 <para>
241 <literal>lkn = lkn-1(kn)</literal>
242 </para>
243 <para>
244 <literal>
245 lkn(i,j)
246 </literal>
247 </para>
248 <para>
249 When path points to more than one list component, the
250 instruction must have as many left-hand side arguments as selected
251 components. But if the extraction syntax is used as function
252 parameters, each returned list component is added to the
253 function parameters.
254 </para>
255 <para>
256 Note that <literal>l(list())</literal> is the same as
257 <literal>l</literal>.
258 </para>
259 <variablelist>
260 <varlistentry>
261 <term>i and j may be:</term>
262 <listitem>
263 <variablelist>
264 <varlistentry>
265 <term>real scalar or vector or matrix with positive
266 elements.
267 </term>
268 <listitem>
269 <para>
270 <literal>[r1,...rn]=l(i)</literal> extracts the
271 <literal>i(k)</literal> elements from the list <literal>l</literal> and store
272 them in <literal>rk</literal> variables for
273 <literal>k</literal> from 1 to
274 <literal>size(i,'*')</literal>
275 </para>
276 </listitem>
277 </varlistentry>
278 <varlistentry>
279 <term>
280 the symbol <literal>: </literal>
281 </term>
282 <listitem>
283 <para>which stands for "all elements".</para>
284 </listitem>
285 </varlistentry>
286 <varlistentry>
287 <term>a vector of booleans.</term>
288 <listitem>
289 <para>
290 If <literal>i</literal> is a vector of booleans it is
291 interpreted as <literal>find(i)</literal>.
292 </para>
293 </listitem>
294 </varlistentry>
295 <varlistentry>
296 <term>a polynomial</term>
297 <listitem>
298 <para>
299 If <literal>i</literal> is a vector of polynomials or
300 implicit polynomial vector it is interpreted as
301 <literal>horner(i,m)</literal> where
302 <literal>m=size(l)</literal>. Even if this feature works for
303 all polynomials, it is recommended to use polynomials in
304 <literal>$</literal> for readability.
305 </para>
306 </listitem>
307 </varlistentry>
308 </variablelist>
309 </listitem>
310 </varlistentry>
311 <varlistentry>
312 <term>k1 ... kn may be :</term>
313 <listitem>
314 <variablelist>
315 <varlistentry>
316 <term>real positive scalar</term>
317 <listitem>
318 <para/>
319 </listitem>
320 </varlistentry>
321 <varlistentry>
322 <term>a polynomial</term>
323 <listitem>
324 <para>
325 interpreted as <literal>horner(ki,m)</literal> where
326 <literal>m</literal> is the corresponding sub-list
327 size.
328 </para>
329 </listitem>
330 </varlistentry>
331 <varlistentry>
332 <term>a character string</term>
333 <listitem>
334 <para>associated with a sub-list entry name.</para>
335 </listitem>
336 </varlistentry>
337 </variablelist>
338 </listitem>
339 </varlistentry>
340 </variablelist>
341 </refsect3>
342 <refsect3>
343 <title>Remarks</title>
344 <para>For soft coded matrix types such as rational functions and state
345 space linear systems, <literal>x(i)</literal> syntax may not be used for
346 vector element extraction due to confusion with list element extraction.
347 <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be
348 used.
349 </para>
350 </refsect3>
354 </refsection> 351 </refsection>
355 <refsection> 352 <refsection>
356 <title>Examples</title> 353 <title>Examples</title>
354 <para>
355 Matrix case:
356 </para>
357 <programlisting role="example"><![CDATA[ 357 <programlisting role="example"><![CDATA[
358// MATRIX CASE 358a = [1 2 3 ; 4 5 6]
359a=[1 2 3;4 5 6]
360a(1,2) 359a(1,2)
361a([1 1],2) 360a([1 1], 2)
362a(:,1) 361a(:, 1)
363a(:,3:-1:1) 362a(:, 3:-1:1)
364a(1) 363a(1)
365a(6) 364a(6)
366a(:) 365a(:)
367a([%t %f %f %t]) 366a([%t %f %f %t])
368a([%t %f],[2 3]) 367a([%t %f], [2 3])
369a(1:2,$-1) 368a(1:2, $-1)
370a($:-1:1,2) 369a($:-1:1, 2)
371a($) 370a($)
372// 371//
373x='test' 372x = 'test'
374x([1 1;1 1;1 1]) 373x([1 1 ; 1 1 ; 1 1])
375// 374//
376b=[1/%s,(%s+1)/(%s-1)] 375b = [1/%s, (%s+1)/(%s-1)]
377b(1,1) 376b(1,1)
378b(1,$) 377b(1,$)
379b(2) // the numerator 378b(2) // the numerator
380// LIST OR TLIST CASE 379 ]]></programlisting>
381l=list(1,'qwerw',%s) 380 <para>
381 List ot Tlist case:
382 </para>
383 <programlisting role="example"><![CDATA[
384l = list(1,'qwerw',%s)
382l(1) 385l(1)
383[a,b]=l([3 2]) 386[a,b] = l([3 2])
384l($) 387l($)
385x=tlist(l(2:3)) //form a tlist with the last 2 components of l 388x = tlist(l(2:3)) // forms a tlist with the last 2 components of l
386// 389//
387dts=list(1,tlist(['x';'a';'b'],10,[2 3])); 390dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
388dts(2)('a') 391dts(2)('a')
389dts(2)('b')(1,2) 392dts(2)('b')(1,2)
390[a,b]=dts(2)(['a','b']) 393[a,b] = dts(2)(['a','b'])
391 ]]></programlisting> 394 ]]></programlisting>
392 </refsection> 395 </refsection>
393 <refsection role="see also"> 396 <refsection role="see also">
394 <title>See also</title> 397 <title>See also</title>
395 <simplelist type="inline"> 398 <simplelist type="inline">
396 <member> 399 <member>
400 <link linkend="insertion">insertion</link>
401 </member>
402 <member>
403 <link linkend="colon">colon</link>
404 </member>
405 <member>
397 <link linkend="find">find</link> 406 <link linkend="find">find</link>
398 </member> 407 </member>
399 <member> 408 <member>
@@ -402,9 +411,6 @@ dts(2)('b')(1,2)
402 <member> 411 <member>
403 <link linkend="parentheses">parentheses</link> 412 <link linkend="parentheses">parentheses</link>
404 </member> 413 </member>
405 <member>
406 <link linkend="insertion">insertion</link>
407 </member>
408 </simplelist> 414 </simplelist>
409 </refsection> 415 </refsection>
410</refentry> 416</refentry>
diff --git a/scilab/modules/elementary_functions/help/en_US/insertion.xml b/scilab/modules/elementary_functions/help/en_US/insertion.xml
index 8464866..ebc5904 100644
--- a/scilab/modules/elementary_functions/help/en_US/insertion.xml
+++ b/scilab/modules/elementary_functions/help/en_US/insertion.xml
@@ -1,5 +1,8 @@
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="insertion"> 2<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
4 xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
5 xml:lang="en" xml:id="insertion">
3 <refnamediv> 6 <refnamediv>
4 <refname>insertion</refname> 7 <refname>insertion</refname>
5 <refpurpose>partial variable assignation 8 <refpurpose>partial variable assignation
@@ -56,375 +59,380 @@
56 </refsection> 59 </refsection>
57 <refsection> 60 <refsection>
58 <title>Description</title> 61 <title>Description</title>
59 <variablelist> 62 <refsect3>
60 <varlistentry> 63 <title>Matrix case</title>
61 <term>MATRIX CASE</term> 64 <para>
65 If <literal>x</literal> is a matrix the indices <literal>i</literal> and <literal>j</literal>, may be:
66 </para>
67 <variablelist>
68 <varlistentry>
69 <term>Real scalars or vectors or matrices</term>
62 <listitem> 70 <listitem>
63 <para> 71 <para>In this case the values given as indices should be positive and
64 If <literal>x</literal> is a matrix the indices <literal>i</literal> and <literal>j</literal>, may be: 72 only their integer part are taken into account.
65 </para> 73 </para>
66 <variablelist> 74 <itemizedlist>
75 <listitem>
76 <para>
77 If <literal>a</literal> is a matrix with
78 dimensions
79 <literal>(size(i,'*'),size(j,'*'))</literal>,
80 <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
81 such as <literal>x(int(i(l)),int(j(k)))=a(l,k) </literal> for
82 <literal>l</literal> from 1 to
83 <literal>size(i,'*')</literal> and <literal>k</literal> from
84 1 to <literal>size(j,'*')</literal>, other initial
85 entries of <literal>x</literal> are unchanged.
86 </para>
87 </listitem>
88 <listitem>
89 <para>
90 If <literal>a</literal> is a scalar
91 <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
92 such as <literal>x(int(i(l)),int(j(k)))=a</literal> for
93 <literal>l</literal> from 1 to <literal>size(i,'*')</literal>
94 and <literal>k</literal> from 1 to
95 <literal>size(j,'*')</literal>, other initial entries
96 of <literal>x</literal> are unchanged.
97 </para>
98 </listitem>
99 <listitem>
100 <para>
101 If <literal>i</literal> or <literal>j</literal>
102 maximum value exceed corresponding <literal>x</literal> matrix
103 dimension, array <literal>x</literal> is previously extended to the
104 required dimensions with zeros entries for standard
105 matrices, 0 length character string for string matrices and
106 false values for boolean matrices.
107 </para>
108 </listitem>
109 <listitem>
110 <para>
111 <literal>x(i,j)=[]</literal> kills rows
112 specified by <literal>i</literal> if <literal>j</literal> matches all
113 columns of <literal>x</literal> or kills columns specified by
114 <literal>j</literal> if <literal>i</literal> matches all rows of
115 <literal>x</literal>. In other cases <literal>x(i,j)=[]</literal>
116 produce an error.
117 </para>
118 </listitem>
119 <listitem>
120 <para>
121 <literal>x(i)=a</literal> with an <literal>a</literal>
122 vector returns a new <literal>x</literal> matrix such as
123 <literal>x(int(i(l)))=a(l)</literal> for <literal>l</literal> from 1 to
124 <literal>size(i,'*')</literal>, other initial entries
125 of <literal>x</literal> are unchanged.
126 </para>
127 </listitem>
128 <listitem>
129 <para>
130 <literal>x(i)=a</literal> with an <literal>a</literal>
131 scalar returns a new <literal>x</literal> matrix such as
132 <literal>x(int(i(l)))=a</literal> for <literal>l</literal> from 1 to
133 <literal>size(i,'*')</literal>, other initial entries
134 of <literal>x</literal> are unchanged.
135 </para>
136 <para>
137 If <literal>i</literal> maximum value exceed
138 <literal>size(x,1)</literal>, <literal>x</literal> is previously
139 extended to the required dimension with zeros entries for
140 standard matrices, 0 length character string for string
141 matrices and false values for boolean matrices.
142 </para>
143 <variablelist>
67 <varlistentry> 144 <varlistentry>
68 <term>Real scalars or vectors or matrices</term> 145 <term>if</term>
69 <listitem> 146 <listitem>
70 <para>In this case the values given as indices should be positive and
71 only their integer part are taken into account.
72 </para>
73 <itemizedlist>
74 <listitem>
75 <para>
76 If <literal>a</literal> is a matrix with
77 dimensions
78 <literal>(size(i,'*'),size(j,'*'))</literal>,
79 <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
80 such as <literal>x(int(i(l)),int(j(k)))=a(l,k) </literal> for
81 <literal>l</literal> from 1 to
82 <literal>size(i,'*')</literal> and <literal>k</literal> from
83 1 to <literal>size(j,'*')</literal>, other initial
84 entries of <literal>x</literal> are unchanged.
85 </para>
86 </listitem>
87 <listitem>
88 <para>
89 If <literal>a</literal> is a scalar
90 <literal>x(i,j)=a</literal> returns a new <literal>x</literal> matrix
91 such as <literal>x(int(i(l)),int(j(k)))=a</literal> for
92 <literal>l</literal> from 1 to <literal>size(i,'*')</literal>
93 and <literal>k</literal> from 1 to
94 <literal>size(j,'*')</literal>, other initial entries
95 of <literal>x</literal> are unchanged.
96 </para>
97 </listitem>
98 <listitem>
99 <para>
100 If <literal>i</literal> or <literal>j</literal>
101 maximum value exceed corresponding <literal>x</literal> matrix
102 dimension, array <literal>x</literal> is previously extended to the
103 required dimensions with zeros entries for standard
104 matrices, 0 length character string for string matrices and
105 false values for boolean matrices.
106 </para>
107 </listitem>
108 <listitem>
109 <para>
110 <literal>x(i,j)=[]</literal> kills rows
111 specified by <literal>i</literal> if <literal>j</literal> matches all
112 columns of <literal>x</literal> or kills columns specified by
113 <literal>j</literal> if <literal>i</literal> matches all rows of
114 <literal>x</literal>. In other cases <literal>x(i,j)=[]</literal>
115 produce an error.
116 </para>
117 </listitem>
118 <listitem>
119 <para>
120 <literal>x(i)=a</literal> with an <literal>a</literal>
121 vector returns a new <literal>x</literal> matrix such as
122 <literal>x(int(i(l)))=a(l)</literal> for <literal>l</literal> from 1 to
123 <literal>size(i,'*')</literal>, other initial entries
124 of <literal>x</literal> are unchanged.
125 </para>
126 </listitem>
127 <listitem>
128 <para>
129 <literal>x(i)=a</literal> with an <literal>a</literal>
130 scalar returns a new <literal>x</literal> matrix such as
131 <literal>x(int(i(l)))=a</literal> for <literal>l</literal> from 1 to
132 <literal>size(i,'*')</literal>, other initial entries
133 of <literal>x</literal> are unchanged.
134 </para>
135 <para>
136 If <literal>i</literal> maximum value exceed
137 <literal>size(x,1)</literal>, <literal>x</literal> is previously
138 extended to the required dimension with zeros entries for
139 standard matrices, 0 length character string for string
140 matrices and false values for boolean matrices.
141 </para>
142 <variablelist>
143 <varlistentry>
144 <term>if</term>
145 <listitem>
146 <para>
147 <literal>x</literal> is a 1x1
148 </para>
149 <para>
150 matrix <literal>a</literal> may be a row (respectively a
151 column) vector with dimension
152 <literal>size(i,'*')</literal>. Resulting
153 <literal>x</literal> matrix is a row (respectively a column)
154 vector
155 </para>
156 </listitem>
157 </varlistentry>
158 <varlistentry>
159 <term>if</term>
160 <listitem>
161 <para>
162 <literal>x</literal> is a row
163 </para>
164 <para>
165 vector <literal>a</literal> must be a row vector with
166 dimension <literal>size(i,'*')</literal>
167 </para>
168 </listitem>
169 </varlistentry>
170 <varlistentry>
171 <term>if</term>
172 <listitem>
173 <para>
174 <literal>x</literal> is a column
175 </para>
176 <para>
177 vector <literal>a</literal> must be a column vector with
178 dimension <literal>size(i,'*')</literal>
179 </para>
180 </listitem>
181 </varlistentry>
182 <varlistentry>
183 <term>if</term>
184 <listitem>
185 <para>
186 <literal>x</literal> is a general
187 </para>
188 <para>
189 matrix <literal>a</literal> must be a row or column vector
190 with dimension <literal>size(i,'*')</literal> and
191 <literal>i</literal> maximum value cannot exceed
192 <literal>size(x,'*')</literal>.
193 </para>
194 </listitem>
195 </varlistentry>
196 </variablelist>
197 </listitem>
198 <listitem>
199 <para>
200 <literal>x(i)=[]</literal> kills entries
201 specified by <literal>i</literal>.
202 </para>
203 </listitem>
204 </itemizedlist>
205 </listitem>
206 </varlistentry>
207 <varlistentry>
208 <term>The : symbol</term>
209 <listitem>
210 <para>
211 The <literal>:</literal> symbol stands for "all elements".
212 </para>
213 <itemizedlist>
214 <listitem>
215 <para>
216 <literal>x(i,:)=a</literal> is interpreted as
217 <literal>x(i,1:size(x,2))=a</literal>
218 </para>
219 </listitem>
220 <listitem>
221 <para>
222 <literal>x(:,j)=a</literal> is interpreted as
223 <literal>x(1:size(x,1),j)=a</literal>
224 </para>
225 </listitem>
226 <listitem>
227 <para>
228 <literal>x(:)=a</literal> returns in
229 <literal>x</literal> the <literal>a</literal> matrix reshaped
230 according to <literal>x</literal>
231 dimensions. <literal>size(x,'*')</literal> must be
232 equal to <literal>size(a,'*')</literal>.
233 </para>
234 </listitem>
235 </itemizedlist>
236 </listitem>
237 </varlistentry>
238 <varlistentry>
239 <term>Vectors of boolean</term>
240 <listitem>
241 <para>
242 If an index (<literal>i</literal> or <literal>j</literal>) is a vector
243 of booleans it is interpreted as <literal>find(i)</literal> or
244 respectively <literal>find(j)</literal>.
245 </para>
246 </listitem>
247 </varlistentry>
248 <varlistentry>
249 <term>Polynomials</term>
250 <listitem>
251 <para>
252 If an index (<literal>i</literal> or <literal>j</literal>) is a vector of
253 polynomials or implicit polynomial vector it is interpreted
254 as <literal>horner(i,m)</literal> or respectively
255 <literal>horner(j,n)</literal> where <literal>m</literal> and
256 <literal>n</literal> are associated <literal>x</literal> dimensions.
257 Even if this feature works for all polynomials, it is
258 recommended to use polynomials in <literal>$</literal> for
259 readability.
260 </para>
261 </listitem>
262 </varlistentry>
263 </variablelist>
264 </listitem>
265 </varlistentry>
266 <varlistentry>
267 <term>LIST OR TLIST CASE</term>
268 <listitem>
269 <itemizedlist>
270 <listitem>
271 <para>If they are present
272 the <literal>ki</literal> give the path to a sub-list entry of
273 <literal>l</literal> data structure. They allow a recursive insertion
274 without intermediate copies. The <literal>l(k1)...(kn)(i)=a</literal>
275 and <literal>l(list(k1,...,kn,i)=a)</literal> instructions are
276 interpreted as:
277 </para>
278 <para>
279 <literal>lk1 = l(k1)</literal>
280 </para>
281 <para>
282 <literal> .. = .. </literal>
283 </para>
284 <para>
285 <literal>lkn = lkn-1(kn)</literal>
286 </para>
287 <para>
288 <literal>lkn(i) = a</literal>
289 </para>
290 <para>
291 <literal>lkn-1(kn) = lkn</literal>
292 </para>
293 <para>
294 <literal> .. = .. </literal>
295 </para>
296 <para>
297 <literal>l(k1) = lk1</literal>
298 </para>
299 <para>
300 And the <literal>l(k1)...(kn)(i,j)=a</literal> and <literal>l(list(k1,...,kn,list(i,j))=a</literal>
301 instructions are interpreted as:
302 </para>
303 <para>
304 <literal>lk1 = l(k1)</literal>
305 </para>
306 <para> 147 <para>
307 <literal> .. = .. </literal> 148 <literal>x</literal> is a 1x1
308 </para> 149 </para>
309 <para> 150 <para>
310 <literal>lkn = lkn-1(kn)</literal> 151 matrix <literal>a</literal> may be a row (respectively a
152 column) vector with dimension
153 <literal>size(i,'*')</literal>. Resulting
154 <literal>x</literal> matrix is a row (respectively a column)
155 vector
311 </para> 156 </para>
157 </listitem>
158 </varlistentry>
159 <varlistentry>
160 <term>if</term>
161 <listitem>
312 <para> 162 <para>
313 <literal>lkn(i,j) = a</literal> 163 <literal>x</literal> is a row
314 </para> 164 </para>
315 <para> 165 <para>
316 <literal>lkn-1(kn) = lkn</literal> 166 vector <literal>a</literal> must be a row vector with
167 dimension <literal>size(i,'*')</literal>
317 </para> 168 </para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term>if</term>
173 <listitem>
318 <para> 174 <para>
319 <literal> .. = .. </literal> 175 <literal>x</literal> is a column
320 </para> 176 </para>
321 <para> 177 <para>
322 <literal>l(k1)= lk1</literal> 178 vector <literal>a</literal> must be a column vector with
179 dimension <literal>size(i,'*')</literal>
323 </para> 180 </para>
324 </listitem> 181 </listitem>
325 <listitem> 182 </varlistentry>
183 <varlistentry>
184 <term>if</term>
185 <listitem>
326 <para> 186 <para>
327 <literal>i</literal> may be : 187 <literal>x</literal> is a general
328 </para> 188 </para>
329 <itemizedlist>
330 <listitem>
331 <para> a real non negative scalar (only its integer part is taken into account).
332 <literal>l(0)=a</literal> adds an entry on the "left"
333 of the list. <literal>l(i)=a</literal> sets the <literal>i</literal>
334 entry of the list <literal>l</literal> to <literal>a</literal>. If
335 <literal>i&gt;size(l)</literal>, <literal>l</literal> is previously
336 extended with zero length entries (undefined).
337 <literal>l(i)=null()</literal> deletes the <literal>i</literal>th list
338 entry.
339 </para>
340 </listitem>
341 <listitem>
342 <para>
343 a polynomial. If <literal>i</literal> is a
344 polynomial it is interpreted as <literal>horner(i,m)</literal>
345 where <literal>m=size(l)</literal>. Even if this feature works
346 for all polynomials, it is recommended to use polynomials
347 in <literal>$</literal> for readability.
348 </para>
349 </listitem>
350 </itemizedlist>
351 </listitem>
352 <listitem>
353 <para> 189 <para>
354 <literal>k1,..kn</literal> may be : 190 matrix <literal>a</literal> must be a row or column vector
191 with dimension <literal>size(i,'*')</literal> and
192 <literal>i</literal> maximum value cannot exceed
193 <literal>size(x,'*')</literal>.
355 </para> 194 </para>
356 <itemizedlist> 195 </listitem>
357 <listitem> 196 </varlistentry>
358 <para> 197 </variablelist>
359 real positive scalar. 198 </listitem>
360 </para> 199 <listitem>
361 </listitem> 200 <para>
362 <listitem> 201 <literal>x(i)=[]</literal> kills entries
363 <para> a polynomial, interpreted as 202 specified by <literal>i</literal>.
364 <literal>horner(ki,m)</literal> where <literal>m</literal> is the 203 </para>
365 corresponding sub-list size. 204 </listitem>
366 </para> 205 </itemizedlist>
367 </listitem>
368 <listitem>
369 <para> a character string associated with a
370 sub-list entry name.
371 </para>
372 </listitem>
373 </itemizedlist>
374 </listitem>
375 </itemizedlist>
376 </listitem> 206 </listitem>
377 </varlistentry> 207 </varlistentry>
378 </variablelist> 208 <varlistentry>
379 </refsection> 209 <term>The : symbol</term>
380 <refsection> 210 <listitem>
381 <title>Remarks</title> 211 <para>
382 <para> 212 The <literal>:</literal> symbol stands for "all elements".
383 For soft coded matrix types such as rational functions and state space linear systems, <literal>x(i)</literal> syntax must not be used for vector entry insertion due to confusion with list entry insertion. <literal>x(1,j)</literal> or <literal>x(i,1)</literal> syntax must be used. 213 </para>
384 </para> 214 <itemizedlist>
215 <listitem>
216 <para>
217 <literal>x(i,:)=a</literal> is interpreted as
218 <literal>x(i,1:size(x,2))=a</literal>
219 </para>
220 </listitem>
221 <listitem>
222 <para>
223 <literal>x(:,j)=a</literal> is interpreted as
224 <literal>x(1:size(x,1),j)=a</literal>
225 </para>
226 </listitem>
227 <listitem>
228 <para>
229 <literal>x(:)=a</literal> returns in
230 <literal>x</literal> the <literal>a</literal> matrix reshaped
231 according to <literal>x</literal>
232 dimensions. <literal>size(x,'*')</literal> must be
233 equal to <literal>size(a,'*')</literal>.
234 </para>
235 </listitem>
236 </itemizedlist>
237 </listitem>
238 </varlistentry>
239 <varlistentry>
240 <term>Vectors of boolean</term>
241 <listitem>
242 <para>
243 If an index (<literal>i</literal> or <literal>j</literal>) is a vector
244 of booleans it is interpreted as <literal>find(i)</literal> or
245 respectively <literal>find(j)</literal>.
246 </para>
247 </listitem>
248 </varlistentry>
249 <varlistentry>
250 <term>Polynomials</term>
251 <listitem>
252 <para>
253 If an index (<literal>i</literal> or <literal>j</literal>) is a vector of
254 polynomials or implicit polynomial vector it is interpreted
255 as <literal>horner(i,m)</literal> or respectively
256 <literal>horner(j,n)</literal> where <literal>m</literal> and
257 <literal>n</literal> are associated <literal>x</literal> dimensions.
258 Even if this feature works for all polynomials, it is
259 recommended to use polynomials in <literal>$</literal> for
260 readability.
261 </para>
262 </listitem>
263 </varlistentry>
264 </variablelist>
265 </refsect3>
266 <refsect3>
267 <title>List or Tlist case</title>
268 <itemizedlist>
269 <listitem>
270 <para>If they are present
271 the <literal>ki</literal> give the path to a sub-list entry of
272 <literal>l</literal> data structure. They allow a recursive insertion
273 without intermediate copies. The <literal>l(k1)...(kn)(i)=a</literal>
274 and <literal>l(list(k1,...,kn,i)=a)</literal> instructions are
275 interpreted as:
276 </para>
277 <para>
278 <literal>lk1 = l(k1)</literal>
279 </para>
280 <para>
281 <literal> .. = .. </literal>
282 </para>
283 <para>
284 <literal>lkn = lkn-1(kn)</literal>
285 </para>
286 <para>
287 <literal>lkn(i) = a</literal>
288 </para>
289 <para>
290 <literal>lkn-1(kn) = lkn</literal>
291 </para>
292 <para>
293 <literal> .. = .. </literal>
294 </para>
295 <para>
296 <literal>l(k1) = lk1</literal>
297 </para>
298 <para>
299 And the <literal>l(k1)...(kn)(i,j)=a</literal> and <literal>l(list(k1,...,kn,list(i,j))=a</literal>
300 instructions are interpreted as:
301 </para>
302 <para>
303 <literal>lk1 = l(k1)</literal>
304 </para>
305 <para>
306 <literal> .. = .. </literal>
307 </para>
308 <para>
309 <literal>lkn = lkn-1(kn)</literal>
310 </para>
311 <para>
312 <literal>lkn(i,j) = a</literal>
313 </para>
314 <para>
315 <literal>lkn-1(kn) = lkn</literal>
316 </para>
317 <para>
318 <literal> .. = .. </literal>
319 </para>
320 <para>
321 <literal>l(k1)= lk1</literal>
322 </para>
323 </listitem>
324 <listitem>
325 <para>
326 <literal>i</literal> may be :
327 </para>
328 <itemizedlist>
329 <listitem>
330 <para> a real non negative scalar (only its integer part is taken into account).
331 <literal>l(0)=a</literal> adds an entry on the "left"
332 of the list. <literal>l(i)=a</literal> sets the <literal>i</literal>
333 entry of the list <literal>l</literal> to <literal>a</literal>. If
334 <literal>i&gt;size(l)</literal>, <literal>l</literal> is previously
335 extended with zero length entries (undefined).
336 <literal>l(i)=null()</literal> deletes the <literal>i</literal>th list
337 entry.
338 </para>
339 </listitem>
340 <listitem>
341 <para>
342 a polynomial. If <literal>i</literal> is a
343 polynomial it is interpreted as <literal>horner(i,m)</literal>
344 where <literal>m=size(l)</literal>. Even if this feature works
345 for all polynomials, it is recommended to use polynomials
346 in <literal>$</literal> for readability.
347 </para>
348 </listitem>
349 </itemizedlist>
350 </listitem>
351 <listitem>
352 <para>
353 <literal>k1,..kn</literal> may be :
354 </para>
355 <itemizedlist>
356 <listitem>
357 <para>
358 real positive scalar.
359 </para>
360 </listitem>
361 <listitem>
362 <para> a polynomial, interpreted as
363 <literal>horner(ki,m)</literal> where <literal>m</literal> is the
364 corresponding sub-list size.
365 </para>
366 </listitem>
367 <listitem>
368 <para> a character string associated with a
369 sub-list entry name.
370 </para>
371 </listitem>
372 </itemizedlist>
373 </listitem>
374 </itemizedlist>
375 </refsect3>
376 <refsect3>
377 <title>Remarks</title>
378 <para>
379 For soft coded matrix types such as rational functions and state space linear
380 systems, <literal>x(i)</literal> syntax must not be used for vector entry
381 insertion due to confusion with list entry insertion. <literal>x(1,j)</literal>
382 or <literal>x(i,1)</literal> syntax must be used.
383 </para>
384 </refsect3>
385 </refsection> 385 </refsection>
386 <refsection> 386 <refsection>
387 <title>Examples</title> 387 <title>Examples</title>
388 <para>Matrix cases:</para>
388 <programlisting role="example"><![CDATA[ 389 <programlisting role="example"><![CDATA[
389// MATRIX CASE 390a = [1 2 3;4 5 6]
390a=[1 2 3;4 5 6] 391a(1,2) = 10
391a(1,2)=10 392a([1 1],2) = [-1;-2]
392a([1 1],2)=[-1;-2] 393a(:,1) = [8;5]
393a(:,1)=[8;5] 394a(1,3:-1:1) = [77 44 99]
394a(1,3:-1:1)=[77 44 99] 395a(1) = %s
395a(1)=%s 396a(6) = %s+1
396a(6)=%s+1 397a(:) = 1:6
397a(:)=1:6 398a([%t %f],1) = 33
398a([%t %f],1)=33 399a(1:2,$-1) = [2;4]
399a(1:2,$-1)=[2;4] 400a($:-1:1,1) = [8;7]
400a($:-1:1,1)=[8;7] 401a($) = 123
401a($)=123 402a(1,%pi) = 1 // equivalent to a(1,3)=1
402a(1,%pi)=1 //equivalent to a(1,3)=1
403// 403//
404x='test' 404x = 'test'
405x([4 5])=['4','5'] 405x([4 5]) = ['4','5']
406// 406//
407b=[1/%s,(%s+1)/(%s-1)] 407b = [1/%s, (%s+1)/(%s-1)]
408b(1,1)=0 408b(1,1) = 0
409b(1,$)=b(1,$)+1 409b(1,$) = b(1,$)+1
410b(2)=[1 2] // the numerator 410b(2) = [1 2] // the numerator
411// LIST OR TLIST CASE 411 ]]></programlisting>
412l=list(1,'qwerw',%s) 412 <para>List or Tlist cases:</para>
413l(1)='Changed' 413 <programlisting role="example"><![CDATA[
414l(0)='Added' 414l = list(1,'qwerw',%s)
415l(%pi)=1 //equivalent to l(3)=1 415l(1) = 'Changed'
416l(6)=['one more';'added'] 416l(0) = 'Added'
417l(%pi) = 1 // equivalent to l(3)=1
418l(6) = ['one more';'added']
417// 419//
418// 420//
419dts=list(1,tlist(['x';'a';'b'],10,[2 3])); 421dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
420dts(2).a=33 422dts(2).a = 33
421dts(2)('b')(1,2)=-100 423dts(2)('b')(1,2) = -100
422 ]]></programlisting> 424 ]]></programlisting>
423 </refsection> 425 </refsection>
424 <refsection role="see also"> 426 <refsection role="see also">
425 <title>See also</title> 427 <title>See also</title>
426 <simplelist type="inline"> 428 <simplelist type="inline">
427 <member> 429 <member>
430 <link linkend="extraction">extraction</link>
431 </member>
432 <member>
433 <link linkend="colon">colon</link>
434 </member>
435 <member>
428 <link linkend="find">find</link> 436 <link linkend="find">find</link>
429 </member> 437 </member>
430 <member> 438 <member>
@@ -433,9 +441,6 @@ dts(2)('b')(1,2)=-100
433 <member> 441 <member>
434 <link linkend="parentheses">parentheses</link> 442 <link linkend="parentheses">parentheses</link>
435 </member> 443 </member>
436 <member>
437 <link linkend="extraction">extraction</link>
438 </member>
439 </simplelist> 444 </simplelist>
440 </refsection> 445 </refsection>
441</refentry> 446</refentry>
diff --git a/scilab/modules/elementary_functions/help/en_US/matrixoperations/cumsum.xml b/scilab/modules/elementary_functions/help/en_US/matrixoperations/cumsum.xml
index 16dc100..5c71694 100644
--- a/scilab/modules/elementary_functions/help/en_US/matrixoperations/cumsum.xml
+++ b/scilab/modules/elementary_functions/help/en_US/matrixoperations/cumsum.xml
@@ -13,17 +13,20 @@
13 * along with this program. 13 * along with this program.
14 * 14 *
15 --> 15 -->
16<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xml:id="cumsum"> 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:ns5="http://www.w3.org/1999/xhtml"
18 xmlns:db="http://docbook.org/ns/docbook" xml:id="cumsum">
17 <refnamediv> 19 <refnamediv>
18 <refname>cumsum</refname> 20 <refname>cumsum</refname>
19 <refpurpose>cumulative sum of array elements</refpurpose> 21 <refpurpose>partial cumulative sums of the elements of an array</refpurpose>
20 </refnamediv> 22 </refnamediv>
21 <refsynopsisdiv> 23 <refsynopsisdiv>
22 <title>Syntax</title> 24 <title>Syntax</title>
23 <synopsis>y=cumsum(x) 25 <synopsis>
24 y=cumsum(x,orientation) 26 y = cumsum(x)
25 y=cumsum(x,outtype) 27 y = cumsum(x, outtype)
26 y=cumsum(x,orientation,outtype) 28 y = cumsum(x, orientation)
29 y = cumsum(x, orientation, outtype)
27 </synopsis> 30 </synopsis>
28 </refsynopsisdiv> 31 </refsynopsisdiv>
29 32
@@ -33,7 +36,11 @@
33 <varlistentry> 36 <varlistentry>
34 <term>x</term> 37 <term>x</term>
35 <listitem> 38 <listitem>
36 <para>an array of reals, complex, booleans, polynomials or rational fractions.</para> 39 <para>
40 array of booleans, integers, real or complex numbers, polynomials, or
41 rational fractions.
42 Hypermatrices or sparse boolean or numerical matrices are supported as well.
43 </para>
37 </listitem> 44 </listitem>
38 </varlistentry> 45 </varlistentry>
39 <varlistentry> 46 <varlistentry>
@@ -43,11 +50,16 @@
43 <itemizedlist> 50 <itemizedlist>
44 <listitem> 51 <listitem>
45 <para> 52 <para>
46 either a string with possible values <literal>"*"</literal>, <literal>"r"</literal>, <literal>"c"</literal> or <literal>"m"</literal> 53 either a string with possible values <literal>"*"</literal>,
54 <literal>"r"</literal>, <literal>"c"</literal> or <literal>"m"</literal>
47 </para> 55 </para>
48 </listitem> 56 </listitem>
49 <listitem> 57 <listitem>
50 <para>or a number with positive integer value</para> 58 <para>
59 positive integer 1 ≤ orientation ≤ ndims(x): the index of the
60 dimension along which the cumulative sum must be computed.
61 1 and "r", and 2 and "c", are equivalent.
62 </para>
51 </listitem> 63 </listitem>
52 </itemizedlist> 64 </itemizedlist>
53 </listitem> 65 </listitem>
@@ -56,14 +68,14 @@
56 <term>outtype</term> 68 <term>outtype</term>
57 <listitem> 69 <listitem>
58 <para> 70 <para>
59 a string with possible values <literal>"native"</literal> or <literal>"double"</literal>. 71 Word <literal>"native"</literal> or <literal>"double"</literal>.
60 </para> 72 </para>
61 </listitem> 73 </listitem>
62 </varlistentry> 74 </varlistentry>
63 <varlistentry> 75 <varlistentry>
64 <term>y</term> 76 <term>y</term>
65 <listitem> 77 <listitem>
66 <para>scalar or array</para> 78 <para>Array of size equal to that of <varname>x</varname>.</para>
67 </listitem> 79 </listitem>
68 </varlistentry> 80 </varlistentry>
69 </variablelist> 81 </variablelist>
@@ -72,15 +84,15 @@
72 <refsection role="description"> 84 <refsection role="description">
73 <title>Description</title> 85 <title>Description</title>
74 <para> 86 <para>
75 Returns the cumulative sum of array elements. 87 <emphasis role="bold">y = cumsum(x)</emphasis> computes and provides the partial
76 For an array <term>x</term>, <literal>y=cumsum(x)</literal> a matrix <term>y</term> of the same size as <term>x</term>. 88 cumulative sums <literal>y(i)=sum(x(1:i))</literal>, <emphasis role="italic">i.e.</emphasis>:
77 The value <literal>y(i)</literal> is the sum of all elements of <literal>x(1:i)</literal> <emphasis role="italic">i.e.</emphasis>:
78 </para> 89 </para>
79 <para> 90 <para>
80 <latex><![CDATA[ y(i) = \sum_{k=1}^i x(k)]]></latex> 91 <latex alt="y(i) = ∑u=1→i x(u)"><![CDATA[ y(i) = \sum_{u=1}^i x(u)]]></latex>
81 </para> 92 </para>
82 <para> 93 <para>
83 <literal>y=cumsum(x,orientation)</literal> returns in <term>y</term> the cumulative sum of <term>x</term> along the dimension given by <term>orientation</term>: 94 <emphasis role="bold">y = cumsum(x, orientation)</emphasis> returns the partial
95 cumulative sums of <term>x</term> along the dimension given by <term>orientation</term>:
84 </para> 96 </para>
85 <itemizedlist> 97 <itemizedlist>
86 <listitem> 98 <listitem>
@@ -88,11 +100,14 @@
88 if <term>orientation</term> is equal to 1 or "r" then: 100 if <term>orientation</term> is equal to 1 or "r" then:
89 </para> 101 </para>
90 <para> 102 <para>
91 <latex><![CDATA[ y(\mathbf{l},j) = \sum_{\mathbf{i}=1}^l x(\mathbf{i},j)]]></latex> 103 <latex alt="y(i,j) = ∑u=1→i x(u,j)"><![CDATA[
104 y(\mathbf{i},j) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j) ]]>
105 </latex>, or for a N-Dimensional array:
92 </para> 106 </para>
93 <para>or </para>
94 <para> 107 <para>
95 <latex><![CDATA[ y(\mathbf{l},j,k,\ldots) = \sum_{\mathbf{i}=1}^l x(\mathbf{i},j,k,\ldots)]]></latex> 108 <latex alt="y(i,j,k,…) = ∑u=1→i x(u,j,k,…)"><![CDATA[
109 y(\mathbf{i},j,k,\ldots) = \sum_{u=1}^{\mathbf{i}} x(\mathbf{u},j,k,\ldots) ]]>
110 </latex>
96 </para> 111 </para>
97 </listitem> 112 </listitem>
98 <listitem> 113 <listitem>
@@ -100,11 +115,14 @@
100 if <term>orientation</term> is equal to 2 or "c" then: 115 if <term>orientation</term> is equal to 2 or "c" then:
101 </para> 116 </para>
102 <para> 117 <para>
103 <latex><![CDATA[ y(i,\mathbf{l}) = \sum_{\mathbf{j}=1}^l x(i,{\mathbf{j})]]></latex> 118 <latex alt="y(i,j) = ∑u=1→j x(i,u)"><![CDATA[
119 y(i,\mathbf{j}) = \sum_{u=1}^{\mathbf{j}} x(i,{\mathbf{u}) ]]>
120 </latex>, or for a N-Dimensional array:
104 </para> 121 </para>
105 <para> or </para>
106 <para> 122 <para>
107 <latex><![CDATA[ y(i,\mathbf{l},k,\ldots) = \sum_{\mathbf{j}=1}^l x(i,\mathbf{j},k,\ldots)]]></latex> 123 <latex alt="y(i,j,k,…) = ∑u=1→j x(i,u,k,…)"><![CDATA[
124 y(i,\mathbf{j},k,\ldots) = \sum_{u=1}^{\mathbf{j}} x(i,\mathbf{u},k,\ldots) ]]>
125 </latex>
108 </para> 126 </para>
109 </listitem> 127 </listitem>
110 <listitem> 128 <listitem>
@@ -112,37 +130,48 @@
112 if <term>orientation</term> is equal to n then: 130 if <term>orientation</term> is equal to n then:
113 </para> 131 </para>
114 <para> 132 <para>
115 <latex><![CDATA[ y(i_1,\ldots,i_{n-1},\mathbf{l},i_{n+1},\ldots) = \sum_{\mathbf{i_n}=1}^l x(i_1,\ldots,i_{n-1},\mathbf{i_n},i_{n+1},\ldots)]]></latex> 133 <latex alt="y(i₁,…,iₙ₋₁, iₙ,iₙ₊₁,…) = ∑u=1…iₙ  x(i₁,…,iₙ₋₁, u,iₙ₊₁,…)"><![CDATA[
134 y(i_1,\ldots,i_{n-1},\mathbf{i_{n}},i_{n+1},\ldots) =
135 \sum_{u=1}^{\mathbf{i_n}} x(i_1,\ldots,i_{n-1},\mathbf{u},i_{n+1},\ldots) ]]>
136 </latex>
116 </para> 137 </para>
117 </listitem> 138 </listitem>
118 <listitem> 139 <listitem>
119 <para> 140 <para>
120 <literal>y=cumsum(x,"*")</literal> is equivalent to <literal>y=cumsum(x)</literal> 141 <emphasis role="bold">y = cumsum(x, "*")</emphasis> is equivalent to
142 <literal>y = cumsum(x)</literal>
121 </para> 143 </para>
122 </listitem> 144 </listitem>
123 <listitem> 145 <listitem>
124 <para> 146 <para>
125 <literal>y=cumsum(x,"m")</literal> is equivalent to <literal>y=cumsum(x,orientation)</literal> where <term>orientation</term> is the index of the first dimension of <term>x</term> that is greater than 1. This option is used for Matlab compatibility. 147 <emphasis role="bold">y = cumsum(x, "m")</emphasis> is equivalent to
148 <literal>y = cumsum(x, orientation)</literal> where <term>orientation</term>
149 is the index of the first dimension of <term>x</term> that is greater than 1.
150 This option is used for Matlab compatibility.
126 </para> 151 </para>
127 </listitem> 152 </listitem>
128 </itemizedlist> 153 </itemizedlist>
129 <para/> 154 <para/>
130 <para> 155 <para>
131 The <term>outtype</term> argument rules the way the summation is done: 156 The <term>outtype</term> argument rules the way the summations are done:
132 </para> 157 </para>
133 <itemizedlist> 158 <itemizedlist>
134 <listitem> 159 <listitem>
135 <para> 160 <para>
136 For arrays of floats, of polynomials, of rational fractions, the evaluation is always done using floating points computations. The <literal>"double"</literal> or <literal>"native"</literal> options are equivalent. 161 For arrays of floats, of polynomials, of rational fractions, the evaluation
162 is always done using floating points computations. The <literal>"double"</literal>
163 or <literal>"native"</literal> options are equivalent.
137 </para> 164 </para>
138 </listitem> 165 </listitem>
139 <listitem> 166 <listitem>
140 <para>For arrays of integers,</para> 167 <para>For arrays of integers,</para>
141 <para> 168 <para>
142 if <literal>outtype="native"</literal> the evaluation is done using integer computations (modulo 2^b, where b is the number of bits used), 169 if <literal>outtype="native"</literal> the evaluation is done using integer
170 computations (modulo 2^b, where b is the number of bits used),
143 </para> 171 </para>
144 <para> 172 <para>
145 if <literal>outtype="double"</literal> the evaluation is done using floating point computations. 173 if <literal>outtype="double"</literal> the evaluation is done using floating
174 point computations.
146 </para> 175 </para>
147 <para> 176 <para>
148 The default value is <literal>outtype="native"</literal>. 177 The default value is <literal>outtype="native"</literal>.
@@ -151,41 +180,44 @@
151 <listitem> 180 <listitem>
152 <para>For arrays of booleans,</para> 181 <para>For arrays of booleans,</para>
153 <para> 182 <para>
154 if <literal>outtype="native"</literal> the evaluation is done using boolean computations ( + is replaced by |), 183 if <literal>outtype="native"</literal> the evaluation is done using boolean
184 computations ( + is replaced with |),
155 </para> 185 </para>
156 <para> 186 <para>
157 if <literal>outtype="double"</literal> the evaluation is done using floating point computations (%t values are replaced by 1 and %f values by 0). 187 if <literal>outtype="double"</literal> the evaluation is done using floating
188 point computations (%t values are replaced by 1 and %f values by 0).
158 </para> 189 </para>
159 <para> 190 <para>
160 The default value is <literal>outtype="double"</literal>. 191 The default value is <literal>outtype="double"</literal>.
161 </para> 192 </para>
162 </listitem> 193 </listitem>
163 </itemizedlist> 194 </itemizedlist>
164 <note> 195 <warning>
165 This function applies, with identical rules to <link linkend="sparse">sparse matrices</link>. 196 When the input <varname>x</varname> is sparse, please keep in mind that the density
166 </note> 197 of the result <varname>y</varname> will be almost always close to 100%.
198 </warning>
167 </refsection> 199 </refsection>
168 200
169 <refsection role="examples"> 201 <refsection role="examples">
170 <title>Examples</title> 202 <title>Examples</title>
171 <programlisting role="example"><![CDATA[ 203 <programlisting role="example"><![CDATA[
172A=[1,2;3,4]; 204A = [1,2;3,4];
173cumsum(A) 205cumsum(A)
174cumsum(A,1) 206cumsum(A,1)
175 207
176I=uint8([2 95 103;254 9 0]) 208I = uint8([2 95 103 ; 254 9 0])
177cumsum(I) //native evaluation 209cumsum(I) // native evaluation
178cumsum(I,"double") 210cumsum(I,"double")
179cumsum(I,2,"double") 211cumsum(I,2,"double")
180 212
181s=poly(0,"s"); 213s = poly(0,"s");
182P=[s,%i+s;s^2,1]; 214P = [s, %i+s ; s^2 , 1];
183cumsum(P), 215cumsum(P)
184cumsum(P,2) 216cumsum(P, 2)
185 217
186B=[%t %t %f %f]; 218B = [%t %t %f %f];
187cumsum(B) //evaluation in float 219cumsum(B) // evaluation in float
188cumsum(B,"native") //similar to or(B) 220cumsum(B,"native") // similar to or(B)
189 ]]></programlisting> 221 ]]></programlisting>
190 </refsection> 222 </refsection>
191 223
diff --git a/scilab/modules/elementary_functions/help/en_US/matrixoperations/kron.xml b/scilab/modules/elementary_functions/help/en_US/matrixoperations/kron.xml
index 89baff4..8dbc457 100644
--- a/scilab/modules/elementary_functions/help/en_US/matrixoperations/kron.xml
+++ b/scilab/modules/elementary_functions/help/en_US/matrixoperations/kron.xml
@@ -3,7 +3,7 @@
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab 3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 2008 - INRIA 4 * Copyright (C) 2008 - INRIA
5 * Copyright (C) 2012 - 2016 - Scilab Enterprises 5 * Copyright (C) 2012 - 2016 - Scilab Enterprises
6 * Copyright (C) 2014, 2019 - Samuel GOUGEON 6 * Copyright (C) 2014, 2019, 2020 - Samuel GOUGEON
7 * 7 *
8 * This file is hereby licensed under the terms of the GNU GPL v2.0, 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. 9 * pursuant to article 5.3.4 of the CeCILL v.2.1.
@@ -40,8 +40,8 @@
40 can't be an hypermatrix. 40 can't be an hypermatrix.
41 </para> 41 </para>
42 <para> 42 <para>
43 Supported encodings and types: integer, real, complex, polynomial, rational, 43 Supported encodings and types: boolean, integer, real, complex, polynomial,
44 sparse. 44 rational, sparse boolean, sparse real, sparse complex.
45 </para> 45 </para>
46 </listitem> 46 </listitem>
47 </varlistentry> 47 </varlistentry>
@@ -208,7 +208,13 @@ a.*.b
208 <revision> 208 <revision>
209 <revnumber>5.5.1</revnumber> 209 <revnumber>5.5.1</revnumber>
210 <revdescription> 210 <revdescription>
211 <para>Extension to hypermatrices</para> 211 Extension to hypermatrices.
212 </revdescription>
213 </revision>
214 <revision>
215 <revnumber>6.1.1</revnumber>
216 <revdescription>
217 Extension to boolean and sparse boolean arrays.
212 </revdescription> 218 </revdescription>
213 </revision> 219 </revision>
214 </revhistory> 220 </revhistory>
diff --git a/scilab/modules/elementary_functions/help/en_US/matrixoperations/unwrap.xml b/scilab/modules/elementary_functions/help/en_US/matrixoperations/unwrap.xml
deleted file mode 100644
index 6aa7f3e..0000000
--- a/scilab/modules/elementary_functions/help/en_US/matrixoperations/unwrap.xml
+++ /dev/null
@@ -1,306 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!--
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 2013 - 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" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="unwrap" xml:lang="en">
17 <refnamediv>
18 <refname>unwrap</refname>
19 <refpurpose>unwrap a Y(x) profile or a Z(x,y) surface. Unfold a Y(x) profile</refpurpose>
20 </refnamediv>
21 <refsynopsisdiv>
22 <title>Syntaxes</title>
23 <synopsis>unwrap() // runs some examples
24 [U, breakPoints] = unwrap(Y)
25 [U, breakPoints] = unwrap(Y, z_jump)
26 [U, cuspPoints] = unwrap(Y, "unfold")
27 U = unwrap(Z)
28 U = unwrap(Z, z_jump)
29 U = unwrap(Z, z_jump, dir)
30 </synopsis>
31 </refsynopsisdiv>
32 <refsection>
33 <title>Arguments</title>
34 <variablelist>
35 <varlistentry>
36 <term>Y</term>
37 <listitem>
38 <para>Vector of real numbers: the profile to unwrap or unfold. Implicit abscissae X are assumed to be equispaced.</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term>Z</term>
43 <listitem>
44 <para>Matrix of real numbers: the surface to unwrap. Implicit abscissae (X,Y) are assumed to be cartesian and equispaced (constant steps may be different along X versus along Y).</para>
45 </listitem>
46 </varlistentry>
47 <varlistentry>
48 <term>z_jump</term>
49 <listitem>
50 <para>
51 Scalar real positive number used in unwrapping mode: the jump's height applied at breakpoints, performing the unwrapping. Only its absolute value is considered. The jump actually applied has the sign of the slope on both sides of each breakpoint. The default value is <literal>z_jump = 2*%pi</literal>. The special value <literal>z_jump = 0</literal> applies jumps equal to the average slope around each breakpoint, restoring a continuous slope over the whole profile or surface.
52 </para>
53 </listitem>
54 </varlistentry>
55 <varlistentry>
56 <term>dir</term>
57 <listitem>
58 <para>"c" | "r" | "" (default): direction along which unwrapping is performed. "c" unwraps along columns, "r" unwraps along rows, "" unwraps in both directions.</para>
59 </listitem>
60 </varlistentry>
61 <varlistentry>
62 <term>"unfold"</term>
63 <listitem>
64 <para>Provide this switch to unfold the given curve if it is folded, instead of unwrapping it.</para>
65 </listitem>
66 </varlistentry>
67 <varlistentry>
68 <term>U</term>
69 <listitem>
70 <para>
71 Unwrapped profile or surface, or unfolded profile. <varname>U</varname> has the same sizes as <varname>Y</varname> or <varname>Z</varname>.
72 </para>
73 </listitem>
74 </varlistentry>
75 <varlistentry>
76 <term>breakPoints, cuspPoints</term>
77 <listitem>
78 <para>
79 Vector of indices of points in <varname>Y</varname> where wrapping or folding has been detected and processed.
80 </para>
81 </listitem>
82 </varlistentry>
83 </variablelist>
84 </refsection>
85 <refsection>
86 <title>Description</title>
87 <para>UNWRAPPING</para>
88 <para>
89 <function>unwrap()</function> will be useful to process profiles or even surfaces wrapped for instance by a periodic and monotonic function such as
90 <literal>Y = modulo(X,w)</literal> or <literal>Y = atan(tan(X))</literal>. It aims to somewhat invert these functions, recovering the input <literal>X</literal> over it full range instead of the limited <literal>w</literal> or <literal>[-%pi/2, %pi/2]</literal> one.
91 </para>
92 <para>A breakpoint of a wrapped profile is detected as a point where slopes on both neighbouring sides of the point are almost equal but much smaller (in absolute value) from and opposite to the slope at the considered point: at the point, there is a jump breaking and opposed to the neighbouring slope.
93 </para>
94 <para>This detection strategy avoids considering any particular level as a wrapping one. It allows to process wrapped profiles to which a constant (or even a trend) has been added afterwards.
95 </para>
96 <para>
97 Unwrapping consists in reducing every detected jump and somewhat restoring a continuous slope (initially assumed to be so). At each point, it is performed by applying a Y-shift on a whole side of the profile, with respect to the other. The Y-shift may be the same for all breakpoints, as provided by the user. If the user specifies a null Y-shift, <function>unwrap()</function> applies a jump equal to the average neighbouring slope, depending on each breakpoint.
98 </para>
99 <warning>An unwrapped profile is always defined but for a constant.</warning>
100 <para>
101 Unless <varname>dir</varname> is used, <function>unwrap()</function> applied to a surface unwraps its first column. Each point of this one is then taken as reference level for unwrapping each line starting with it.
102 </para>
103 <para> </para>
104 <para>UNFOLDING</para>
105 <para>
106 If the <varname>"unfold"</varname> keyword is used and a profile -- not a surface -- is provided, the profile is assumed to be folded instead of being wrapped.
107 </para>
108 <para>At a folding point -- or "cusp point" --, the profile is continuous, but its slope is broken: the slope has almost the same absolute value on both sides of the point, but is somewhat opposed from one side to the other.
109 </para>
110 <para>
111 Folding may occur for instance when a non-monotonic periodic function and its inverse are applied to a profile X, like with <varname>Y= acos(cos(X))</varname>. Recovering X from Y is quite more difficult than if it was wrapped. Indeed, some ambiguous situations may exist, like when the profile is tangentially folded on one of its quasi-horizontal sections (if any).
112 </para>
113 <para>When a cusp point is detected, a) one side of the profile starting from it is opposed (upside down), and b) the continuity of the profile and of its slope are preserved and retrieved at the considered point (this may need adding a small jump by the local slope).</para>
114 <warning>The slope on the left edge of the input profile is used as starting reference. The unfolded profile may be upside down with respect to the original true one. In addition, as for unwrapping, it is defined but for a constant.
115 </warning>
116 <para>Known limitations: presently, folded surfaces can't be processed.</para>
117 </refsection>
118 <refsection>
119 <title>Examples</title>
120 <para>Unwrapping or unfolding 1D profiles:</para>
121 <programlisting role="example"><![CDATA[
122// 1D EXAMPLES
123// -----------
124f = scf();
125f.figure_size = [800 1000];
126f.figure_position(2) = 0;
127f.figure_name = "unwrap() & ""unfold""" + _(": 1-D examples ");
128ax = gda();
129ax.y_label.font_size=2;
130drawlater()
131
132// Original 1D profile
133t = linspace(-4,4.2,800);
134alpha = t.^2 + t -1;
135subplot(5,2,1)
136titlepage("unwrap(): unwrap | unfold")
137subplot(5,2,2)
138plot(t,alpha)
139t2 = "$\text{Original profile: } \alpha=t^2+t-1$";
140ax = gca();
141ax.tight_limits = "on";
142yT = max(alpha) - strange(alpha)*0.1;
143xstring(0,yT,t2)
144e = gce();
145e.text_box_mode = "centered";
146e.font_size = 2;
147
148// Loop over cases
149for i=1:4
150 subplot(5,2,2*i+1)
151 if i==1 then
152 // Wrapping by atan(tan())
153 ralpha = atan(tan(alpha)); // Raw recovered alpha [pi]
154 ylabel("$atan(tan(\alpha))$")
155 [u, K] = unwrap(ralpha, %pi); // arctan
156 t2 = "$\text{unwrap(Y, \%pi)}$";
157 elseif i==2
158 // Wrapping by modulo() + Y-shift
159 c = (rand(1,1)-0.5)*4;
160 ralpha = pmodulo(alpha, 5) + c;
161 ylabel("$modulo(\alpha,\ 5)"+msprintf("%+5.2f",c)+"$")
162 [u, K] = unwrap(ralpha, 0);
163 t2 = "$\text{unwrap(Y, 0)}$";
164 elseif i==3
165 // Folding by asin(sin()) + Y-shift
166 ralpha = 1+asin(sin(alpha)); // Raw recovered alpha [2.pi]
167 ylabel("$1+asin(sin(\alpha))$")
168 [u, K] = unwrap(ralpha, "unfold");
169 t2 = "$\text{unwrap(Y,""unfold"")}$";
170 else
171 // Folding by acos(cos()) + a trend
172 ralpha = 1+alpha/10+acos(cos(alpha)); // Raw recovered alpha [2.pi]
173 ylabel("$1+\frac{\alpha}{10}+acos(cos(\alpha))$")
174 [u, K] = unwrap(ralpha, "unfold");
175 t2 = "$\text{unwrap(Y,""unfold"")}$";
176 end
177 // Plotting the profile to be processed
178 plot(t, ralpha)
179 // Staring the breakpoints or the cusp points on the curve:
180 if K~=[] then
181 plot(t(K), ralpha(K),"*")
182 end
183 // Plotting the processed (unwrapped/unfolded) profile:
184 subplot(5,2,2*i+2)
185 plot(t,u)
186 ax = gca();
187 ax.tight_limits = "on";
188 // Adding a legend:
189 yT = max(u) - strange(u)*0.2;
190 xstring(0,yT,t2)
191 e = gce();
192 e.text_box_mode = "centered";
193 e.font_size = 2;
194end
195sda();
196drawnow()
197 ]]></programlisting>
198 <scilab:image>
199 %_unwrap()
200 </scilab:image>
201 <para>Unwrapping 2-D surfaces:</para>
202 <programlisting role="example"><![CDATA[
203// 2-D EXAMPLES
204// -----------
205ax = gda();
206ax.title.font_size = 2;
207f = scf();
208f.color_map = hotcolormap(100);
209f.axes_size = [900 450];
210f.figure_position(2) = 0;
211f.figure_name = "unwrap()" + _(": 2-D examples");
212drawlater()
213
214nx = 300;
215ny = 400;
216rmax = 8.8;
217x = linspace(-rmax/2, rmax/2, nx)-1;
218y = linspace(-rmax/2, rmax/2, ny)+1;
219[X, Y] = meshgrid(x,y);
220for ex=0:1 // examples
221 // Original surface
222 // Generating the surface
223 if ex==0 then
224 z = X.^2 + Y.^2;
225 else
226 z = sqrt(0.3+sinc(sqrt(z)*3))*17-7;
227 end
228 // PLotting it in 3D
229 subplot(2,4,1+4*ex)
230 surf(x, y, z)
231 title("Original profile Z")
232 e = gce();
233 e.thickness = 0; // removes the mesh
234 e.parent.tight_limits = "on";
235
236 // Wrapped surface (flat)
237 m = 2.8;
238 zw = pmodulo(z, m); // wraps it
239 subplot(2,4,2+4*ex)
240 grayplot(x, y, zw')
241 title(msprintf("Zw = pmodulo(Z, %g) (flat)",m))
242 ax0 = gca();
243 ax0.tight_limits = "on";
244
245 // Unwrapped surfaces (flat):
246 // in both directions:
247 u = unwrap(zw, 0);
248 subplot(2,4,3+4*ex)
249 grayplot(x, y, u')
250 title(msprintf("unwrap(Zw, %g) (flat)", 0))
251 ax3 = gca();
252 ax3.tight_limits = "on";
253
254 if ex==0 then
255 direc = "r";
256 else
257 direc = "c";
258 end
259 // Along a single direction:
260 u = unwrap(zw, m, direc);
261 subplot(2,4,4+4*ex)
262 grayplot(x, y, u')
263 title(msprintf("unwrap(Zw, %g, ""%s"") (flat)",m,direc))
264 ax1 = gca();
265 ax1.tight_limits = "on";
266end
267sda();
268drawnow()
269 ]]></programlisting>
270 <para/>
271 <inlinemediaobject>
272 <imageobject>
273 <imagedata fileref="../../images/unwrap_2D.png"/>
274 </imageobject>
275 </inlinemediaobject>
276 </refsection>
277 <refsection role="see also">
278 <title>See also</title>
279 <simplelist type="inline">
280 <member>
281 <link linkend="atan">atan</link>
282 </member>
283 <member>
284 <link linkend="modulo">modulo</link>
285 </member>
286 </simplelist>
287 </refsection>
288 <refsection role="bibliography">
289 <title>Bibliography</title>
290 <para>
291 <ulink url="http://siptoolbox.sourceforge.net/doc/sip-0.7.0-reference/unwrapl.html">SIP toolbox: unwrap linear</ulink>
292 </para>
293 <para>
294 <ulink url="http://siptoolbox.sourceforge.net/doc/sip-0.7.0-reference/unwrapp.html">SIP toolbox: unwrap along path</ulink>
295 </para>
296 </refsection>
297 <refsection role="history tag">
298 <title>History</title>
299 <revhistory>
300 <revision>
301 <revnumber>5.5.0</revnumber>
302 <revdescription>unwrap() function introduced</revdescription>
303 </revision>
304 </revhistory>
305 </refsection>
306</refentry>
diff --git a/scilab/modules/elementary_functions/help/en_US/searchandsort/gsort.xml b/scilab/modules/elementary_functions/help/en_US/searchandsort/gsort.xml
index 1f64025..6d886e1 100644
--- a/scilab/modules/elementary_functions/help/en_US/searchandsort/gsort.xml
+++ b/scilab/modules/elementary_functions/help/en_US/searchandsort/gsort.xml
@@ -19,7 +19,7 @@
19 xmlns:scilab="http://www.scilab.org" xml:id="gsort" xml:lang="en"> 19 xmlns:scilab="http://www.scilab.org" xml:id="gsort" xml:lang="en">
20 <refnamediv> 20 <refnamediv>
21 <refname>gsort</refname> 21 <refname>gsort</refname>
22 <refpurpose>sorts boolean, numerical and text arrays</refpurpose> 22 <refpurpose>sorts boolean, numerical and string arrays</refpurpose>
23 </refnamediv> 23 </refnamediv>
24 <refsynopsisdiv> 24 <refsynopsisdiv>
25 <title>Syntax</title> 25 <title>Syntax</title>
@@ -38,7 +38,7 @@
38 <term>A</term> 38 <term>A</term>
39 <listitem> 39 <listitem>
40 Scalar, vector, matrix or hypermatrix of booleans, integers, real or 40 Scalar, vector, matrix or hypermatrix of booleans, integers, real or
41 complex numbers, or text. Sparse matrices of real numbers, 41 complex numbers, or strings. Sparse matrices of real numbers,
42 of complex numbers, or of booleans can also be sorted. 42 of complex numbers, or of booleans can also be sorted.
43 <note> 43 <note>
44 Overloading for unhandled types is allowed. 44 Overloading for unhandled types is allowed.
@@ -151,7 +151,7 @@
151 </listitem> 151 </listitem>
152 <listitem> 152 <listitem>
153 <literal>R</literal> must be of simple sortable type: boolean, 153 <literal>R</literal> must be of simple sortable type: boolean,
154 integer, real, text. 154 integer, real, string.
155 </listitem> 155 </listitem>
156 </itemizedlist> 156 </itemizedlist>
157 </para> 157 </para>
@@ -246,8 +246,9 @@
246 The multilevel mode is described with details in a dedicated subsection below. 246 The multilevel mode is described with details in a dedicated subsection below.
247 </para> 247 </para>
248 <para> 248 <para>
249 Texts are sorted in alphabetical order, in a case-sensitive way. 249 Strings are sorted in alphabetical order, in a case-sensitive way.
250 Extended UTF characters are supported. 250 Extended UTF characters are supported. The empty string "" is considered "smaller"
251 than any other string.
251 </para> 252 </para>
252 <para> 253 <para>
253 Sorting boolean arrays is mostly useful with the "r", "c", "lr" or "lc" methods. 254 Sorting boolean arrays is mostly useful with the "r", "c", "lr" or "lc" methods.
@@ -316,7 +317,7 @@
316 <para/> 317 <para/>
317 </listitem> 318 </listitem>
318 <listitem> 319 <listitem>
319 <emphasis>Sorting the columns of a matrix T of texts, 320 <emphasis>Sorting the columns of a matrix T of strings,
320 first: by increasing length, second: in anti-alphabetical order</emphasis>: 321 first: by increasing length, second: in anti-alphabetical order</emphasis>:
321 <para/> 322 <para/>
322 <literal>gsort(T, "c", ["i" "d"], list(length, :))</literal> 323 <literal>gsort(T, "c", ["i" "d"], list(length, :))</literal>
@@ -509,7 +510,7 @@ c = evstr(s)
509]]></screen> 510]]></screen>
510 </para> 511 </para>
511 <para> 512 <para>
512 <emphasis role="bold">With some texts:</emphasis> 513 <emphasis role="bold">With some strings:</emphasis>
513 Sorting rows in columns, first by increasing lengths, second by alphabetical order 514 Sorting rows in columns, first by increasing lengths, second by alphabetical order
514 </para> 515 </para>
515 <para> 516 <para>
diff --git a/scilab/modules/elementary_functions/help/en_US/setoperations/intersect.xml b/scilab/modules/elementary_functions/help/en_US/setoperations/intersect.xml
index 6bc8ad1..b27d588 100644
--- a/scilab/modules/elementary_functions/help/en_US/setoperations/intersect.xml
+++ b/scilab/modules/elementary_functions/help/en_US/setoperations/intersect.xml
@@ -2,9 +2,8 @@
2<!-- 2<!--
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab 3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 2008 - INRIA 4 * Copyright (C) 2008 - INRIA
5 * Copyright (C) 2018 - Samuel GOUGEON
6 *
7 * Copyright (C) 2012 - 2016 - Scilab Enterprises 5 * Copyright (C) 2012 - 2016 - Scilab Enterprises
6 * Copyright (C) 2018 - 2020 - Samuel GOUGEON
8 * 7 *
9 * This file is hereby licensed under the terms of the GNU GPL v2.0, 8 * 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. 9 * pursuant to article 5.3.4 of the CeCILL v.2.1.
@@ -21,7 +20,7 @@
21 <refnamediv> 20 <refnamediv>
22 <refname>intersect</refname> 21 <refname>intersect</refname>
23 <refpurpose> 22 <refpurpose>
24 returns the unduplicated elements or rows or columns met in both input arrays 23 elements or rows or columns met in both input arrays, without duplicates
25 </refpurpose> 24 </refpurpose>
26 </refnamediv> 25 </refnamediv>
27 <refsynopsisdiv> 26 <refsynopsisdiv>
@@ -39,10 +38,13 @@
39 <varlistentry> 38 <varlistentry>
40 <term>a, b</term> 39 <term>a, b</term>
41 <listitem> 40 <listitem>
42 vectors, matrices or hypermatrices of encoded integers, real or complex 41 vectors, matrices or hypermatrices of booleans, encoded integers, real or
43 numbers, or text. <varname>a</varname> and <varname>b</varname> must have 42 complex numbers, or text. <varname>a</varname> and <varname>b</varname> must
44 the same datatype, but have independent sizes. 43 have the same datatype.
45 For text inputs, UTF characters are accepted. 44 For text inputs, UTF characters are accepted.
45 Sparse numeric or boolean matrices are accepted : Either <varname>a</varname> or
46 <varname>b</varname> or both <varname>a</varname> and <varname>b</varname> may
47 be sparse.
46 <para/> 48 <para/>
47 </listitem> 49 </listitem>
48 </varlistentry> 50 </varlistentry>
@@ -75,19 +77,23 @@
75 </listitem> 77 </listitem>
76 </itemizedlist> 78 </itemizedlist>
77 </para> 79 </para>
80 <para>
81 <varname>M</varname> is sparse as soon as either <varname>a</varname> or
82 <varname>b</varname> is sparse and none is empty.
83 </para>
78 </listitem> 84 </listitem>
79 </varlistentry> 85 </varlistentry>
80 <varlistentry> 86 <varlistentry>
81 <term>ka</term> 87 <term>ka</term>
82 <listitem> 88 <listitem>
83 row vector of indices in <varname>a</varname>. 89 Dense row vector of indices in <varname>a</varname>.
84 <para/> 90 <para/>
85 </listitem> 91 </listitem>
86 </varlistentry> 92 </varlistentry>
87 <varlistentry> 93 <varlistentry>
88 <term>kb</term> 94 <term>kb</term>
89 <listitem> 95 <listitem>
90 row vector of indices in <varname>b</varname>. 96 Dense row vector of indices in <varname>b</varname>.
91 <para/> 97 <para/>
92 </listitem> 98 </listitem>
93 </varlistentry> 99 </varlistentry>
@@ -96,7 +102,7 @@
96 <refsection> 102 <refsection>
97 <title>Description</title> 103 <title>Description</title>
98 <para> 104 <para>
99 <literal>intersect(a,b)</literal> returns a row vector of unduplicated values 105 <literal>intersect(a,b)</literal> returns a row vector of unique values
100 present in both <literal>a</literal> and <literal>b</literal> arrays. Values are 106 present in both <literal>a</literal> and <literal>b</literal> arrays. Values are
101 sorted in increasing order 107 sorted in increasing order
102 <itemizedlist> 108 <itemizedlist>
@@ -258,6 +264,47 @@ M, ka, kb
258 kb = 264 kb =
259 2. 3. 4. 265 2. 3. 4.
260]]></screen> 266]]></screen>
267 <para/>
268 <para>
269 <literal>intersect()</literal> for booleans is mainly useful with the "r" or "c" option.
270 Here is an example with a sparse boolean matrix:
271 </para>
272 <programlisting role="example"><![CDATA[
273[F, T] = (%f, %t);
274A = [F F T F T F ; T F F T T T ; T T F T F F]
275B = [F T F T F F ; T F F F T F ; F T F F T F]
276[M,ka,kb] = intersect(A, sparse(B), "c");
277issparse(M), full(M), ka, kb
278 ]]></programlisting>
279 <screen><![CDATA[
280--> A = [F F T F T F ; T F F T T T ; T T F T F F]
281 A =
282 F F T F T F
283 T F F T T T
284 T T F T F F
285
286--> B = [F T F T F F ; T F F F T F ; F T F F T F]
287 B =
288 F T F T F F
289 T F F F T F
290 F T F F T F
291
292--> [M,ka,kb] = intersect(A, sparse(B), "c");
293--> issparse(M), full(M), ka, kb
294 ans =
295 T
296
297 ans =
298 F F T
299 T T F
300 F T F
301
302 ka =
303 6. 1. 3.
304
305 kb =
306 1. 5. 4.
307]]></screen>
261 </refsection> 308 </refsection>
262 <refsection role="see also"> 309 <refsection role="see also">
263 <title>See also</title> 310 <title>See also</title>
@@ -282,7 +329,13 @@ M, ka, kb
282 <revision> 329 <revision>
283 <revnumber>6.1.0</revnumber> 330 <revnumber>6.1.0</revnumber>
284 <revdescription> 331 <revdescription>
285 complex numbers are now accepted. 332 Complex numbers are now accepted.
333 </revdescription>
334 </revision>
335 <revision>
336 <revnumber>6.1.1</revnumber>
337 <revdescription>
338 Sparse matrices are now accepted (numbers or booleans).
286 </revdescription> 339 </revdescription>
287 </revision> 340 </revision>
288 </revhistory> 341 </revhistory>
diff --git a/scilab/modules/elementary_functions/help/en_US/setoperations/setdiff.xml b/scilab/modules/elementary_functions/help/en_US/setoperations/setdiff.xml
index 6df05ff..248adf4 100644
--- a/scilab/modules/elementary_functions/help/en_US/setoperations/setdiff.xml
+++ b/scilab/modules/elementary_functions/help/en_US/setoperations/setdiff.xml
@@ -38,12 +38,14 @@
38 <term>a, b</term> 38 <term>a, b</term>
39 <listitem> 39 <listitem>
40 <para> 40 <para>
41 vectors, matrices or hypermatrices of real or complex numbers, or encoded 41 vectors, matrices or hypermatrices of real or complex numbers, encoded
42 integers, or strings. Both must have the same data types (and integer types). 42 integers, booleans, or strings. Sparse-encoded inputs are accepted.
43 Both <varname>a</varname> and <varname>b</varname> must have the same
44 data type (and integer type), but may mix dense and sparse encoding.
43 </para> 45 </para>
44 <para> 46 <para>
45 If the option <literal>orien="r"</literal> is used, <literal>a</literal> 47 If the option <literal>orien="r"</literal> is used, <varname>a</varname>
46 and <literal>b</literal> must have the same number of columns. 48 and <varname>b</varname> must have the same number of columns.
47 If the <literal>orien="c"</literal> is used, they must have the same 49 If the <literal>orien="c"</literal> is used, they must have the same
48 number of rows. 50 number of rows.
49 </para> 51 </para>
@@ -56,15 +58,15 @@
56 <itemizedlist> 58 <itemizedlist>
57 <listitem> 59 <listitem>
58 <literal>"r"</literal>: rows of 60 <literal>"r"</literal>: rows of
59 <literal>a</literal> are searched among <literal>b</literal> ones. 61 <varname>a</varname> are searched among <varname>b</varname> ones.