[doc] misc fix & improvements
[scilab.git] / scilab / modules / elementary_functions / help / en_US / insertion.xml
1 <?xml version="1.0" encoding="UTF-8"?>
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">
6     <refnamediv>
7         <refname>insertion</refname>
8         <refpurpose>partial variable assignation
9             or   modification
10         </refpurpose>
11     </refnamediv>
12     <refnamediv xml:id="assignation">
13         <refname>assignation</refname>
14         <refpurpose>partial variable assignation</refpurpose>
15     </refnamediv>
16     <refsynopsisdiv>
17         <title>Syntax</title>
18         <synopsis>x(i,j)=a
19             x(i)=a
20             l(i)=a
21             l(k1)...(kn)(i)=a or l(list(k1,...,kn,i))=a
22             l(k1)...(kn)(i,j)=a or l(list(k1,...,kn,list(i,j))=a
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>x</term>
30                 <listitem>
31                     <para>matrix  of any  kind (constant, sparse, polynomial,...)</para>
32                 </listitem>
33             </varlistentry>
34             <varlistentry>
35                 <term>l</term>
36                 <listitem>
37                     <para>list</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>i,j</term>
42                 <listitem>
43                     <para>indices</para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>k1,...kn</term>
48                 <listitem>
49                     <para>indices  with integer value</para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>a</term>
54                 <listitem>
55                     <para>new entry value</para>
56                 </listitem>
57             </varlistentry>
58         </variablelist>
59     </refsection>
60     <refsection>
61         <title>Description</title>
62         <refsect3>
63             <title>Matrix case</title>
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>
70                 <listitem>
71                   <para>In this case the values given as indices should be positive and
72                     only their integer part are taken into account.
73                   </para>
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>
144                         <varlistentry>
145                           <term>if</term>
146                           <listitem>
147                             <para>
148                               <literal>x</literal> is a 1x1
149                             </para>
150                             <para>
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
156                             </para>
157                           </listitem>
158                         </varlistentry>
159                         <varlistentry>
160                           <term>if</term>
161                           <listitem>
162                             <para>
163                               <literal>x</literal> is a row
164                             </para>
165                             <para>
166                               vector <literal>a</literal> must be a row vector with
167                               dimension <literal>size(i,'*')</literal>
168                             </para>
169                           </listitem>
170                         </varlistentry>
171                         <varlistentry>
172                           <term>if</term>
173                           <listitem>
174                             <para>
175                               <literal>x</literal> is a column
176                             </para>
177                             <para>
178                               vector <literal>a</literal> must be a column vector with
179                               dimension <literal>size(i,'*')</literal>
180                             </para>
181                           </listitem>
182                         </varlistentry>
183                         <varlistentry>
184                           <term>if</term>
185                           <listitem>
186                             <para>
187                               <literal>x</literal> is a general
188                             </para>
189                             <para>
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>.
194                             </para>
195                           </listitem>
196                         </varlistentry>
197                       </variablelist>
198                     </listitem>
199                     <listitem>
200                       <para>
201                         <literal>x(i)=[]</literal> kills entries
202                         specified by <literal>i</literal>.
203                       </para>
204                     </listitem>
205                   </itemizedlist>
206                 </listitem>
207               </varlistentry>
208               <varlistentry>
209                 <term>The : symbol</term>
210                 <listitem>
211                   <para>
212                     The <literal>:</literal> symbol stands for "all elements".
213                   </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>
386     <refsection>
387         <title>Examples</title>
388         <para>Matrix cases:</para>
389         <programlisting role="example"><![CDATA[
390 a = [1 2 3;4 5 6]
391 a(1,2) = 10
392 a([1 1],2) = [-1;-2]
393 a(:,1) = [8;5]
394 a(1,3:-1:1) = [77 44 99]
395 a(1) = %s
396 a(6) = %s+1
397 a(:) = 1:6
398 a([%t %f],1) = 33
399 a(1:2,$-1) = [2;4]
400 a($:-1:1,1) = [8;7]
401 a($) = 123
402 a(1,%pi) = 1 // equivalent to a(1,3)=1
403 //
404 x = 'test'
405 x([4 5]) = ['4','5']
406 //
407 b = [1/%s, (%s+1)/(%s-1)]
408 b(1,1) = 0
409 b(1,$) = b(1,$)+1
410 b(2) = [1 2] // the numerator
411      ]]></programlisting>
412         <para>List or Tlist cases:</para>
413         <programlisting role="example"><![CDATA[
414 l = list(1,'qwerw',%s)
415 l(1) = 'Changed'
416 l(0) = 'Added'
417 l(%pi) = 1 // equivalent to l(3)=1
418 l(6) = ['one more';'added']
419 //
420 //
421 dts = list(1, tlist(['x';'a';'b'],10,[2 3]));
422 dts(2).a = 33
423 dts(2)('b')(1,2) = -100
424      ]]></programlisting>
425     </refsection>
426     <refsection role="see also">
427         <title>See also</title>
428         <simplelist type="inline">
429             <member>
430                 <link linkend="extraction">extraction</link>
431             </member>
432             <member>
433                 <link linkend="colon">colon</link>
434             </member>
435             <member>
436                 <link linkend="find">find</link>
437             </member>
438             <member>
439                 <link linkend="horner">horner</link>
440             </member>
441             <member>
442                 <link linkend="parentheses">parentheses</link>
443             </member>
444         </simplelist>
445     </refsection>
446 </refentry>