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>