8464866e73bab5dadea1806aacf7912b0e5ec443
[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" 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">
3     <refnamediv>
4         <refname>insertion</refname>
5         <refpurpose>partial variable assignation
6             or   modification
7         </refpurpose>
8     </refnamediv>
9     <refnamediv xml:id="assignation">
10         <refname>assignation</refname>
11         <refpurpose>partial variable assignation</refpurpose>
12     </refnamediv>
13     <refsynopsisdiv>
14         <title>Syntax</title>
15         <synopsis>x(i,j)=a
16             x(i)=a
17             l(i)=a
18             l(k1)...(kn)(i)=a or l(list(k1,...,kn,i))=a
19             l(k1)...(kn)(i,j)=a or l(list(k1,...,kn,list(i,j))=a
20         </synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>x</term>
27                 <listitem>
28                     <para>matrix  of any  kind (constant, sparse, polynomial,...)</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>l</term>
33                 <listitem>
34                     <para>list</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>i,j</term>
39                 <listitem>
40                     <para>indices</para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>k1,...kn</term>
45                 <listitem>
46                     <para>indices  with integer value</para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>a</term>
51                 <listitem>
52                     <para>new entry value</para>
53                 </listitem>
54             </varlistentry>
55         </variablelist>
56     </refsection>
57     <refsection>
58         <title>Description</title>
59         <variablelist>
60             <varlistentry>
61                 <term>MATRIX CASE</term>
62                 <listitem>
63                     <para>
64                         If <literal>x</literal> is a matrix the indices <literal>i</literal> and <literal>j</literal>, may be:
65                     </para>
66                     <variablelist>
67                         <varlistentry>
68                             <term>Real scalars or vectors or matrices</term>
69                             <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>
307                                 <literal> ..  = ..  </literal>
308                             </para>
309                             <para>
310                                 <literal>lkn = lkn-1(kn)</literal>
311                             </para>
312                             <para>
313                                 <literal>lkn(i,j) = a</literal>
314                             </para>
315                             <para>
316                                 <literal>lkn-1(kn) = lkn</literal>
317                             </para>
318                             <para>
319                                 <literal> ..  = ..  </literal>
320                             </para>
321                             <para>
322                                 <literal>l(k1)= lk1</literal>
323                             </para>
324                         </listitem>
325                         <listitem>
326                             <para>
327                                 <literal>i</literal> may be :
328                             </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>
354                                 <literal>k1,..kn</literal> may be :
355                             </para>
356                             <itemizedlist>
357                                 <listitem>
358                                     <para>
359                                         real positive scalar.
360                                     </para>
361                                 </listitem>
362                                 <listitem>
363                                     <para> a polynomial, interpreted as
364                                         <literal>horner(ki,m)</literal> where <literal>m</literal> is the
365                                         corresponding sub-list size.
366                                     </para>
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>
377             </varlistentry>
378         </variablelist>
379     </refsection>
380     <refsection>
381         <title>Remarks</title>
382         <para>
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.
384         </para>
385     </refsection>
386     <refsection>
387         <title>Examples</title>
388         <programlisting role="example"><![CDATA[
389 // MATRIX CASE
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 // LIST OR TLIST CASE
412 l=list(1,'qwerw',%s)
413 l(1)='Changed'
414 l(0)='Added'
415 l(%pi)=1 //equivalent to l(3)=1
416 l(6)=['one more';'added']
417 //
418 //
419 dts=list(1,tlist(['x';'a';'b'],10,[2 3]));
420 dts(2).a=33
421 dts(2)('b')(1,2)=-100
422  ]]></programlisting>
423     </refsection>
424     <refsection role="see also">
425         <title>See also</title>
426         <simplelist type="inline">
427             <member>
428                 <link linkend="find">find</link>
429             </member>
430             <member>
431                 <link linkend="horner">horner</link>
432             </member>
433             <member>
434                 <link linkend="parentheses">parentheses</link>
435             </member>
436             <member>
437                 <link linkend="extraction">extraction</link>
438             </member>
439         </simplelist>
440     </refsection>
441 </refentry>