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>