new
[scilab.git] / scilab_doc / intro / chap2.tex
1 % Copyright INRIA
2
3 \chapter{Data Types}
4 \label{ch2}
5 \index{data types}
6 Scilab recognizes several data types.
7  Scalar objects are numerical constants, booleans, polynomials, strings and 
8 rationals (quotients of polynomials). These objects in turn allow to 
9 define matrices which admit these scalars as entries.
10 Other basic objects are lists, typed-lists and functions.
11 %
12 The objective of this chapter is to describe the use of each of 
13 these data types.
14
15 \section{Special Constants}
16 \label{s2.1}
17 \index{data types!constants}
18 \index{constants}
19
20         Scilab provides special constants {\tt \%i}, {\tt \%pi},
21 {\tt \%e}, and {\tt \%eps} as primitives.  The {\tt \%i} constant
22 represents $\sqrt{-1}$, {\tt \%pi} is $\pi=3.1415927\cdots$ , {\tt \%e}
23 is the trigonometric constant $e=2.7182818\cdots$, and {\tt \%eps}
24 is a constant representing the precision of the machine ({\tt \%eps}
25 is the biggest number for which $1+\mbox{\tt \%eps}=1$). {\tt \%inf}
26 and {\tt \%nan} stand for ``Infinity'' and ``NotANumber'' respectively.
27 {\tt \%s} is the polynomial s={\tt poly(0,'s')} with symbol {\tt s}.
28
29 (More generally, given a vector {\tt rts}, {\tt p=poly(rts,'x')}
30 defines the polynomial p(x) with variable {\tt x} and such 
31 that {\tt roots(p)} = {\tt rts}).
32
33 Finally boolean constants are {\tt \%t} and {\tt \%f} which stand for
34 ``true'' and ``false'' respectively. Note that {\tt \%t} is the
35 same as {\tt 1==1} and {\tt \%f} is the same as {\verb!~%t!}.
36
37 These variables are considered as ``predefined''. They are protected, cannot 
38 be deleted and are not saved by the {\tt save} command. It is possible
39 for a user to have his own ``predefined'' variables by using the
40 {\tt predef} command. The best way is probably to set these special variables
41 in his own startup file {\tt <home dir>/.scilab}.
42 Of course, the user can use e.g. {\tt i=sqrt(-1)} instead of {\tt \%i}.
43
44 \section{Constant Matrices}
45 \label{s2.2}
46 \index{data types!matrices}
47
48         Scilab considers a number of data objects as matrices.  
49 Scalars and  vectors are all considered as matrices.  The details of the use
50 of these objects are revealed in the following Scilab sessions.
51
52 \paragraph{Scalars}\index{scalars}
53 Scalars are either real or complex numbers.  The values of
54 scalars can be assigned to variable names chosen by the user.
55 \begin{verbatim}
56 --> a=5+2*%i   //a complex number
57  a         =
58  
59     5. + 2.i  
60  
61 --> B=-2+%i;
62
63 --> b=4-3*%i
64  b  =
65  
66     4. - 3.i 
67  
68 --> a*b
69  ans  =
70  
71     26. - 7.i  
72  
73 -->a*B
74  ans  =
75  
76   - 12. + i    
77 \end{verbatim}
78 Note that Scilab evaluates immediately lines that
79 end with a carriage return.  Instructions that ends with a semi-colon
80 are evaluated but are not displayed on screen. 
81
82 \paragraph{Vectors}\index{vectors}
83 The usual way of creating vectors is as follows, using 
84 commas (or blanks) and semi-columns:
85 \begin{verbatim}
86  
87 --> v=[2,-3+%i,7]
88  v         =
89  
90 !   2.  - 3. + i      7. !
91  
92 --> v'
93  ans       =
94  
95 !   2.       !
96 ! - 3. - i   !
97 !   7.       !
98  
99 --> w=[-3;-3-%i;2]
100  w         =
101  
102 ! - 3.       !
103 ! - 3. - i   !
104 !   2.       !
105  
106 --> v'+w
107  ans       =
108  
109 ! - 1.       !
110 ! - 6. - 2.i !
111 !   9.       !
112  
113 --> v*w
114  ans       =
115  
116     18.  
117  
118 --> w'.*v
119  ans       =
120  
121 ! - 6.    8. - 6.i    14. !
122 \end{verbatim}
123 Notice that vector elements that are separated by commas (or by blanks)
124 yield row vectors and those separated by semi-colons give column
125 vectors. The empty matrix is \verb![]! ; it has zero rows and zero columns.
126 Note also that a single quote is used for transposing a 
127 vector\index{vectors!transpose} 
128 (one obtains the complex conjugate for complex entries).  Vectors of same
129 dimension can be added and subtracted.  The scalar product of a row and
130 column vector is demonstrated above.  Element-wise
131 multiplication ({\tt .*}) and division ({\tt ./}) is also possible 
132 as was demonstrated.
133
134 Note with the following example the role of the position of the blank:
135 \begin{verbatim}
136 -->v=[1 +3]
137  v  =
138  
139 !   1.    3. !
140  
141 -->w=[1 + 3]
142  w  =
143  
144 !   1.    3. !
145  
146 -->w=[1+ 3] 
147  w  =
148  
149     4. 
150  
151 -->u=[1, + 8- 7]
152  u  =
153  
154 !   1.    1. !
155
156 \end{verbatim}
157
158         Vectors\index{vectors!incremental} of elements which increase
159 or decrease incrementely are constructed as follows 
160 \begin{verbatim}
161  
162 --> v=5:-.5:3
163  v         =
164  
165 !   5.    4.5    4.    3.5    3. !
166 \end{verbatim}
167 The resulting vector begins with the first value and ends
168 with the third value stepping in increments of the second value.
169 When not specified the default increment is one.  A constant vector
170 can be created using the {\tt ones}\index{ones@{\tt ones}}\index{vectors!constant} and {\tt zeros} facility 
171 \begin{verbatim}
172  
173 --> v=[1 5 6]
174  v         =
175  
176 !   1.    5.    6. !
177  
178 --> ones(v)
179  ans       =
180  
181 !   1.    1.    1. !
182  
183 --> ones(v')
184  ans       =
185  
186 !   1. !
187 !   1. !
188 !   1. !
189  
190 --> ones(1:4)
191  ans       =
192  
193 !   1.    1.    1.    1. !
194  
195 --> 3*ones(1:4)
196  ans       =
197  
198 !   3.    3.    3.    3. !
199
200 -->zeros(v)
201  ans  =
202  
203 !   0.    0.    0. !
204  
205 -->zeros(1:5)
206  ans  =
207  
208 !   0.    0.    0.    0.    0. !
209  
210 \end{verbatim}
211 Notice that {\tt ones} or {\tt zeros} replace its vector argument by a vector 
212 of equivalent dimensions filled with ones or zeros.
213
214 \paragraph{Matrices}\index{matrices}\index{data types!matrices}\label{Matrices}
215 Row elements are separated by commas or spaces
216  and column elements by semi-colons.  Multiplication
217 of matrices by scalars, vectors, or other matrices is in the usual
218 sense.  Addition and
219 subtraction of matrices is element-wise and element-wise
220 multiplication and division can be accomplished with the {\tt .*}
221 and {\tt ./} operators.
222 \begin{verbatim}
223  
224 --> A=[2 1 4;5 -8 2]
225  A         =
226  
227 !   2.    1.    4. !
228 !   5.  - 8.    2. !
229  
230 --> b=ones(2,3)
231  b         =
232  
233 !   1.    1.    1. !
234 !   1.    1.    1. !
235  
236 --> A.*b
237  ans       =
238  
239 !   2.    1.    4. !
240 !   5.  - 8.    2. !
241  
242 --> A*b'
243  ans       =
244  
245 !   7.    7. !
246 ! - 1.  - 1. !
247 \end{verbatim}
248 Notice that the {\tt ones}\index{ones@{\tt ones}}\index{matrices!constant}
249 operator with two real numbers as arguments separated
250 by a comma creates a matrix of ones using the arguments as
251 dimensions (same for {\tt zeros}).
252 Matrices can be used as elements to larger 
253 matrices\index{matrices!block construction}.  Furthermore,
254 the dimensions of a matrix can be changed.
255 \begin{verbatim}
256  
257 --> A=[1 2;3 4]
258  A         =
259  
260 !   1.    2. !
261 !   3.    4. !
262  
263 --> B=[5 6;7 8];
264  
265 --> C=[9 10;11 12];
266  
267 --> D=[A,B,C]
268  D         =
269  
270 !   1.    2.    5.    6.    9.     10. !
271 !   3.    4.    7.    8.    11.    12. !
272  
273 --> E=matrix(D,3,4)
274  E         =
275  
276 !   1.    4.    6.    11. !
277 !   3.    5.    8.    10. !
278 !   2.    7.    9.    12. !
279
280 -->F=eye(E)
281  F  =
282  
283 !   1.    0.    0.    0. !
284 !   0.    1.    0.    0. !
285 !   0.    0.    1.    0. !
286  
287 -->G=eye(4,3)
288  G  =
289  
290 !   1.    0.    0. !
291 !   0.    1.    0. !
292 !   0.    0.    1. !
293 !   0.    0.    0. !
294
295 \end{verbatim}
296 Notice that matrix {\tt D} is created by using other matrix
297 elements.  The {\tt matrix}\index{matrix@{\tt matrix}} 
298 primitive creates a new matrix {\tt E} with the elements of the
299 matrix {\tt D} using
300 the dimensions specified by the second two arguments.  The element
301 ordering in the matrix {\tt D} is top to bottom and then left to right
302 which explains the ordering of the re-arranged matrix in {\tt E}.
303
304 The function {\tt eye} creates an $m\times n$ matrix with 1 along the main
305 diagonal (if the argument is a matrix {\tt E} , $m$ and $n$ are the 
306 dimensions of {\tt E} ) .
307
308 Sparse constant matrices are defined through their nonzero entries 
309 (type help {\tt sparse} for more details). Once defined, they are
310 manipulated as full matrices.
311
312
313 \section{Matrices of Character Strings}
314 \label{s2.3}
315 \index{data types!character strings}
316 \index{character strings}
317
318 Character strings can be created by using single or double quotes.
319 Concatenation of strings is performed by the {\tt +} operation.
320 Matrices of character strings are constructed as ordinary matrices,
321 e.g. using brackets.  An important feature of matrices of
322 character strings is the capacity to manipulate and create functions.
323 Furthermore, symbolic manipulation of mathematical objects can be
324 implemented using matrices of character strings.  The following
325 illustrates some of these features.
326 \begin{verbatim}
327  
328 --> A=['x' 'y';'z' 'w+v']
329  A         =
330  
331 !x  y    !
332 !        !
333 !z  w+v  !
334  
335 --> At=trianfml(A)
336  At        =
337  
338 !z  w+v          !
339 !                !
340 !0  z*y-x*(w+v)  !
341  
342 --> x=1;y=2;z=3;w=4;v=5;
343  
344 --> evstr(At)
345  ans       =
346  
347 !   3.    9. !
348 !   0.  - 3. !
349
350 \end{verbatim}
351 Note that in the above Scilab session the function 
352 {\tt trianfml}\index{trianfml@{\tt trianfml}}\index{symbolic triangularization}
353 performs the symbolic triangularization of the matrix {\tt A}.
354 The value of the resulting symbolic matrix can be obtained by
355 using {\tt evstr}.
356
357 The following table gives the list of some useful functions:
358
359 \begin{center}
360 \begin{tabular}{|c|c|}
361 \hline
362 \verb!ascii! & ascii code of strings\\ \hline
363
364 \verb!execstr! & executes the string\\ \hline
365
366 \verb!grep ! & looks for a chain into a matrix \\ \hline
367
368 \verb!sort, gsort ! & sorting (lexicographic,...) \\ \hline
369
370 \verb!part! & extract a subchain  \\ \hline
371
372 \verb!mmscanf! & formated read into a chain \\ \hline
373
374 \verb!msprintf! & construct a chain/vector   \\ \hline
375
376 \verb!strindex! & location of a subchain \\ \hline
377
378 \verb!string ! & convert into a string \\ \hline
379
380 \verb!stripblanks! & remove blank characters \\ \hline
381
382 \verb!strsubst! & chain replacement \\ \hline
383
384 \verb!tokens! &  cuts a chain \\ \hline
385
386 \verb!strcat! & catenates chains  \\ \hline
387
388 \verb!length! &  chain length  \\ \hline
389 \end{tabular}
390 \end{center}
391
392
393         A string matrices can be used to create new 
394 functions (for more on functions
395 see Section~\ref{s4.2}).  An example of automatically creating a 
396 function is illustrated in the following Scilab session where it is
397 desired to study a polynomial of two variables {\tt s} and {\tt t}.
398 Since polynomials in two independent variables are not directly 
399 supported in Scilab, we can construct a new data structure using
400 a list (see Section~\ref{s2.5}).
401 The polynomial to be studied is $(t^2+2t^3)-(t+t^2)s+ts^2+s^3$.
402 \begin{verbatim}
403 -->s=poly(0,'s');t=poly(0,'t');
404  
405 -->p=list(t^2+2*t^3,-t-t^2,t,1+0*t);
406  
407 -->pst=makefunction(p) //pst is a function 
408 //                t->p (number->polynomial)
409  pst       =
410  
411 [p]=pst(t)
412  
413 -->pst(1)
414  ans       =
415  
416               2   3  
417     3 - 2s + s + s   
418 \end{verbatim}
419 Here the polynomial is represented by the command which puts
420 the coefficients of the variable {\tt s} in the list {\tt p}.
421 The list {\tt p} is then processed by the function {\tt makefunction}
422 which makes a new function {\tt pst}.  The contents of the new function
423 can be displayed and this function can be evaluated
424 at values of {\tt t}.  The creation of the new function {\tt pst}
425 is accomplished as follows
426
427 \input{macros/make_macro.vtex}
428
429 Here the function {\tt makefunction} takes the list {\tt p} and creates the
430 function {\tt pst}.  Inside of {\tt makefunction} there is a call to another 
431 function {\tt makestr} which makes the string which represents each 
432 term of the new two variable polynomial.  The functions {\tt addf} and
433 {\tt mulf} are used for adding and multiplying strings (i.e. 
434 {\tt addf(x,y)} yields the string {\tt x+y}).  Finally, the 
435 essential command for creating the new function 
436 is the primitive {\tt deff}.  The {\tt deff} primitive 
437 creates a function defined by two matrices
438 of character strings.  Here the 
439 function {\tt p} is defined by the two character strings
440 {\tt '[p]=newfunction(t)'} and {\tt text} where the string {\tt text}
441 evaluates to the polynomial in two variables.
442
443 \section{Polynomials and Polynomial Matrices}
444 \label{s2.4}
445 \index{data types!polynomials}
446 \index{polynomials}
447
448         Polynomials are easily created and manipulated in Scilab.
449 Manipulation of polynomial matrices is essentially identical
450 to that of constant numerical matrices.
451 The {\tt poly}\index{poly@{\tt poly}} 
452 primitive in Scilab can be used to specify the coefficients
453 of a polynomial or the roots of a polynomial.
454 \begin{verbatim}
455 -->p=poly([1 2],'s')   //polynomial defined by its roots
456  p         =
457  
458               2  
459     2 - 3s + s   
460  
461 -->q=poly([1 2],'s','c')  //polynomial defined by its coefficients
462  q         =
463  
464     1 + 2s   
465  
466 -->p+q
467  ans       =
468  
469              2  
470     3 - s + s   
471  
472 -->p*q
473  ans       =
474  
475               2    3  
476     2 + s - 5s + 2s   
477  
478 --> q/p
479  ans       =
480  
481       1 + 2s     
482     -----------  
483               2  
484     2 - 3s + s   
485 \end{verbatim}
486 Note that the polynomial {\tt p} has the {\em roots}
487 1 and 2 whereas the polynomial {\tt q} has the {\em coefficients}
488 1 and 2.  It is the third argument in the {\tt poly} primitive which
489 specifies the coefficient flag option.  
490 In the case where the first argument of {\tt poly} is a square matrix
491 and the roots option is in effect the result is the characteristic
492 polynomial of the matrix.
493 \begin{verbatim}
494  
495 --> poly([1 2;3 4],'s')
496  ans       =
497  
498               2  
499   - 2 - 5s + s   
500 \end{verbatim}
501 Polynomials can be added,
502 subtracted, multiplied, and divided, as usual, but only between polynomials
503 of same formal variable.
504
505         Polynomials, like real and complex constants, can be used
506 as elements in matrices.  This is a very useful feature of Scilab
507 for systems theory.
508 \begin{verbatim}
509  
510 -->s=poly(0,'s');
511  
512 -->A=[1 s;s 1+s^2];   //Polynomial matrix
513  
514 --> B=[1/s 1/(1+s);1/(1+s) 1/s^2]
515  B         =
516  
517 !   1           1    !
518 ! ------      ------ !
519 !   s         1 + s  !
520 !                    !
521 !     1       1      !
522 !    ---     ---     !
523 !              2     !
524 !   1 + s     s      !
525
526 \end{verbatim}
527 From the above examples it can be seen that matrices can be constructed
528 from polynomials and rationals.
529
530 \subsection{Rational polynomial simplification}
531 Scilab automatically performs pole-zero simplifications when the 
532 the built-in primitive {\tt simp} finds a common factor in the
533 numerator and denominator of a rational polynomial {\tt num/den}.
534 Pole-zero simplification is a difficult problem from a
535 numerical viewpoint and {\tt simp} function is usually conservative.
536 When making calculations with polynomials, it is sometimes desirable
537 to avoid pole-zero simplifications: this is possible by switching
538 Scilab into a ``no-simplify'' mode: \verb!help simp_mode!. The
539 function {\tt trfmod} can also be used for simplifying specific
540 pole-zero pairs.
541
542
543 \section{Boolean Matrices}
544 \index{data types!booleans}
545 \index{boolean}
546
547 Boolean constants are {\tt \%t} and {\tt \%f}. They can be used in
548 boolean matrices. The syntax is the same as for ordinary matrices i.e.
549 they can be concatenated, transposed, etc...
550
551 Operations symbols used with boolean matrices or used to create
552 boolean matrices are {\tt ==} and \verb!~!. 
553
554 If {\tt B} is a matrix of booleans {\tt or(B)} and {\tt and(B)} 
555 perform the logical {\tt or} and {\tt and}.
556 \begin{verbatim}
557 -->%t
558  %t  =
559  
560   T  
561  
562 -->[1,2]==[1,3]
563  ans  =
564  
565 ! T F !
566  
567 -->[1,2]==1
568  ans  =
569  
570 ! T F !
571  
572 -->a=1:5; a(a>2)
573  ans  =
574  
575 !   3.    4.    5. !
576
577 -->A=[%t,%f,%t,%f,%f,%f];   
578  
579 -->B=[%t,%f,%t,%f,%t,%t]
580  B  =
581  
582 ! T F T F T T !
583  
584 -->A|B
585  ans  =
586  
587 ! T F T F T T !
588
589 -->A&B
590  ans  =
591  
592 ! T F T F F F !
593  
594 \end{verbatim} 
595
596 Sparse boolean matrices are generated when, e.g., two constant sparse
597 matrices are compared. These matrices are handled as ordinary boolean
598 matrices.
599
600
601 %%%%%
602 \section{Integer Matrices}
603 \index{data types!integer}
604 \index{integer}
605
606 There are 6 integer data types defined in Scilab, all these types have
607 the same major type (see the {\tt type} function) which is 8  and
608 different sub-types (see the {\tt inttype}\index{inttype@{\tt inttype}} function)
609 \begin{itemize}
610 \item 32 bit signed integers (sub-type 4)
611 \item 32 bit unsigned integers (sub-type 14)
612 \item 16 bit signed integers (sub-type 2)
613 \item 16 bit unsigned integers (sub-type 23)
614 \item 8 bit signed integers (sub-type 2)
615 \item 8 bit unsigned integers (sub-type 12)
616 \end{itemize}
617 It is possible to build these integer data types from standard matrix
618 (see \ref{Matrices}) using the {\tt int32}\index{int32@{\tt int32}}, {\tt uint32}\index{uint32@{\tt uint32}}, {\tt int16}\index{int16@{\tt int16}},
619 {\tt uint16}\index{uint16@{\tt uint16}}, {\tt int8}\index{int8@{\tt
620 int8}}, {\tt uint8}\index{uint8@{\tt uint8}} 
621 conversion functions
622 \begin{verbatim}
623 -->x=[0 3.2 27 135] ;
624
625 -->int32(x)
626  ans  =
627  
628 !0   3  27  135 !
629
630 -->int8(x)
631  ans  =
632  
633 !0   3  27  -121!
634 -->uint8(x)
635  ans  =
636  
637 !0   3  27  135 !
638 \end{verbatim}
639
640 The same function can also convert from one sub-type to another
641 one. The {\tt double} function transform any of the integer type in a
642 standard type:
643
644 \begin{verbatim}
645
646 -->y=int32([2 5 285])
647  y  =
648  
649 !2  5  285 !
650
651 -->uint8(y)
652  ans  =
653  
654 !2  5  29 !
655
656 -->double(ans)
657  ans  =
658  
659 !   2.    5.    29. !
660 \end{verbatim}
661
662 Arithmetic and comparison operations can be applied to this type
663
664 \begin{verbatim}
665
666 -->x=int16([1 5 12])
667  x  =
668  
669 !1  5  12 !
670
671 -->x([1 3])
672  ans  =
673  
674 !1  12 !
675  
676 -->x+x
677
678  ans  =
679  
680 !2  10  24 !
681
682 -->x*x'             
683  ans  =
684  
685  170
686 -->y=int16([1 7 11])
687  y  =
688  
689 !1  7  11 !
690 -->x>y
691  ans  =
692  
693 ! F F T !
694 \end{verbatim} 
695
696 The operators \verb!&!, {\tt |} and {\tt ~} used with these datatypes correspond to
697 AND, OR and NOT bit-wise operations. 
698
699
700 \begin{verbatim}
701 -->x=int16([1 5 12])
702  x  =
703  
704 !1  5  12 !
705  
706 -->x|int16(2)
707  ans  =
708  
709 !3  7  14 !
710
711 -->int16(14)&int16(2)
712  ans  =
713  
714  2  
715 -->~uint8(2)
716  ans  =
717  
718  253
719 \end{verbatim}
720 %%%%%
721 \section{N-dimensionnal arrays}
722 N-dimensionnal array can be defined and handled in simple way:
723 \begin{verbatim}
724 -->M(2,2,2)=3
725  M  =
726  
727 (:,:,1)
728  
729 !   0.    0. !
730 !   0.    0. !
731 (:,:,2)
732  
733 !   0.    0. !
734 !   0.    3. !
735  
736 -->M(:,:,1)=rand(2,2)
737  M  =
738  
739 (:,:,1)
740  
741 !   0.9329616    0.312642  !
742 !   0.2146008    0.3616361 !
743 (:,:,2)
744  
745 !   0.    0. !
746 !   0.    3. !
747  
748 -->M(2,2,:)
749  ans  =
750  
751 (:,:,1)
752  
753     0.3616361  
754 (:,:,2)
755  
756     3.  
757 -->size(M)
758  ans  =
759  
760 !   2.    2.    2. !
761  
762 -->size(M,3)
763  ans  =
764  
765     2.  
766  
767 \end{verbatim}
768
769 They can be created from a vector of data and a vector of dimension 
770
771 \begin{verbatim}
772 -->hypermat([2 3,2],1:12)
773  ans  =
774  
775 (:,:,1)
776  
777 !   1.    3.    5. !
778 !   2.    4.    6. !
779 (:,:,2)
780  
781 !   7.    9.     11. !
782 !   8.    10.    12. !
783  
784 \end{verbatim}
785
786 N-dimensionnal matrices are coded as {\tt mlists} with 2 fields~:
787 \begin{verbatim}
788 -->M=hypermat([2,3,2],1:12);
789 -->M.dims
790  ans  =
791  
792 !   2.    3.    2. !
793 -->M.entries'
794 ans  =
795          column  1 to 11
796  
797 !   1.    2.    3.    4.    5.    6.    7.    8.    9.    10.    11. !
798  
799          column 12
800  
801 !   12. !
802 \end{verbatim}
803
804
805 \section{Lists}
806 \label{s2.5}
807 \index{data types!lists}
808 \index{lists}
809
810         Scilab has a list data type.  The list is a collection of data
811 objects not necessarily of the same type.  A list can contain any of
812 the already discussed data types (including functions) as well as
813 other lists.  Lists are useful for defining structured data objects.
814
815 There are two kinds of lists, ordinary lists and typed-lists.
816 A list is defined by the {\tt list} function. Here is a simple
817 example:
818
819 \begin{verbatim}
820 -->L=list(1,'w',ones(2,2))  //L is a list made of 3 entries
821  L  =
822        L(1)
823  
824     1.  
825        L(2)
826  w   
827        L(3)
828  !   1.    1. !
829 !   1.    1. !
830
831 -->L(3);   //extracting entry 3 of list L
832
833 -->L(3)(2,2)  //entry 2,2 of matrix L(3)
834  ans  =
835  
836     1.  
837
838 -->L(2)=list('w',rand(2,2)) //nested list: L(2) is now a list
839  L  =
840        L(1)
841  
842     1.  
843        L(2)
844         L(2)(1)
845  w   
846         L(2)(2)
847 !   0.6653811    0.8497452 !
848 !   0.6283918    0.6857310 !
849        L(3)
850 !   1.    1. !
851 !   1.    1. !
852
853 -->L(2)(2)(1,2)  //extracting entry 1,2 of entry 2 of L(2)
854  ans  =
855  
856     0.8497452  
857
858 -->L(2)(2)(1,2)=5; //assigning a new value to this entry.
859
860 \end{verbatim}
861
862 Typed lists have a specific first entry. This first entry must be a 
863 character string (the type) or a vector of character string (the first
864 component is then the type, and the following elements the names given
865 to the entries of the list). Typed lists entries can be manipulated
866 by using character strings (the names) as shown below.
867
868 \begin{verbatim}
869 -->L=tlist(['Car';'Name';'Dimensions'],'Nevada',[2,3])
870  L  =
871        L(1)
872 !Car         !
873 !            !
874 !Name        !
875 !            !
876 !Dimensions  !
877  
878        L(2)
879  Nevada   
880        L(3)
881 !   2.    3. !
882
883 -->L.Name    //same as L(2)
884  ans  =
885  Nevada   
886 -->L.Dimensions(1,2)=2.3
887
888  L  =
889        L(1)
890  
891 !Car         !
892 !            !
893 !Name        !
894 !            !
895 !Dimensions  !
896  
897        L(2)
898  Nevada   
899        L(3)
900  
901 !   2.    2.3 !
902
903 -->L(3)(1,2)
904  ans  =
905  
906     2.3  
907
908 -->L(1)(1)
909  ans  =
910  
911  Car
912 \end{verbatim}
913 An important feature of typed-lists is that it is possible to define
914 operators acting on them (overloading), i.e., it is possible
915 to define e.g. the multiplication \verb!L1*L2! of the two typed lists 
916 \verb!L1! and \verb!L2!. 
917
918
919 \section{Functions}
920 \label{s2.6}
921 \index{data types!functions}
922 \index{functions}
923
924  Functions are collections of commands which are executed in a
925 new environment thus isolating function variables from the original
926 environments variables.  Functions
927 can be created and executed in a number of different ways.
928 Furthermore, functions can pass arguments, have programming features
929 such as conditionals and loops, and can be recursively called.
930 Functions can be arguments
931 to other functions and can be elements in lists.  The most useful
932 way of creating functions is by using a text editor, however, functions
933 can be created directly in the Scilab environment using the syntax
934 {\tt function}\index{function@{\tt function}} or the
935 {\tt deff}\index{deff@{\tt deff}}\index{functions!{\tt deff}} primitive.
936 \begin{verbatim}
937 --> function [x]=foo(y)
938 -->    if y>0 then, x=1; else, x=-1; end
939 --> endfunction
940  
941 --> foo(5)
942  ans       =
943  
944     1.  
945  
946 --> foo(-3)
947  ans       =
948  
949   - 1.  
950 \end{verbatim}
951 Usually functions are defined in a file using an editor and loaded
952 into Scilab with:\\
953 {\tt exec('filename')}.\\
954 This can be done also by clicking in the {\tt File operation} button.
955 This latter syntax loads the function(s) in {\tt filename} and compiles
956 them.
957 The first line of {\tt filename} must be as follows:
958 \begin{verbatim}
959 function [y1,...,yn]=macname(x1,...,xk)
960 \end{verbatim}
961 where the {\tt yi}'s are output variables and the {\tt xi}'s the
962 input variables.
963
964 For more on the use and creation of functions see Section~\ref{s4.2}.
965
966 \section{Libraries}
967 \label{s2.7}
968 \index{data types!libraries}
969 \index{libraries}
970
971         Libraries are collections of functions which can be either 
972 automatically loaded into the Scilab environment when
973 Scilab is called, or loaded when desired by the user.  
974 Libraries are created by the {\tt lib} command. Examples of librairies
975 are given in the {\tt SCIDIR/macros} directory. Note that in these
976 directory there is an ASCII file ``names'' which contains the names
977 of each function of the library, a set of {\tt .sci} files which
978 contains the source code of the functions and a set of {\tt .bin} files
979 which contains the compiled code of the functions. The Makefile invokes
980 {\tt scilab} for compiling the functions and generating the {\tt .bin}
981 files. The compiled functions of a library are automatically loaded 
982 into Scilab at their first call. To build a library the command {\tt
983 genlib} can be used (\verb!help genlib!).
984
985 \section{Objects}
986 We conclude this chapter by noting that the function {\tt typeof}
987 returns the type of the various Scilab objects. The following objects
988 are defined:
989 \begin{itemize}
990 \item{\tt usual}        for matrices with real or complex entries.
991 \item{\tt polynomial}   for polynomial matrices: coefficients can be 
992 real or complex.
993 \item{\tt boolean}      for boolean matrices.
994 \item{\tt character}    for matrices of character strings.
995 \item{\tt function}     for functions.
996 \item{\tt rational}     for rational matrices ({\tt syslin} lists)
997 \item{\tt state-space}  for linear systems in state-space 
998 form ({\tt syslin} lists).
999 \item{\tt sparse}       for sparse constant matrices (real or complex)
1000 \item{\tt boolean sparse} for sparse boolean matrices.
1001 \item{\tt list}         for ordinary lists.
1002 \item{\tt tlist}        for typed lists.
1003 \item{\tt mlist}        for matrix oriented typed lists.
1004 \item{\tt state-space (or rational)} for syslin lists.
1005 \item{\tt library}      for library definition.
1006 \end{itemize}
1007
1008
1009 \section{Matrix Operations}
1010 The following table gives the syntax of the basic matrix operations
1011 available in Scilab.
1012
1013 \begin{center}
1014 \begin{tabular}{|c|c|}
1015 \hline
1016 SYMBOL & OPERATION 
1017 \\ \hline \hline
1018 \verb![ ]! & matrix definition, concatenation\\ \hline
1019
1020 \verb!;! & row separator\\ \hline
1021
1022 \verb!( )! & extraction \verb!m=a(k)! \\ \hline
1023
1024 \verb!( )! & insertion:  \verb!a(k)=m!  \\ \hline
1025
1026 \verb!.'! & transpose \\ \hline
1027
1028 \verb!'! & conjugate transpose \\ \hline
1029
1030 \verb!+! & addition  \\ \hline
1031
1032 \verb!-! & subtraction \\ \hline
1033
1034 \verb!*! & multiplication \\ \hline
1035
1036 \verb!\! & left division \\ \hline
1037
1038 \verb!/! & right division \\ \hline
1039
1040 \verb!^! &  exponent \\ \hline
1041
1042 \verb!.*! & elementwise multiplication  \\ \hline
1043
1044 \verb!.\! &  elementwise left division  \\ \hline
1045
1046 \verb!./! &  elementwise right division  \\ \hline
1047
1048 \verb!.^! &  elementwise exponent  \\ \hline
1049
1050 \verb!.*.! & kronecker product \\ \hline
1051
1052 \verb!./.! & kronecker right division \\ \hline
1053
1054 \verb!.\.! &  kronecker left division \\ \hline  
1055 \end{tabular}
1056 \end{center}
1057
1058 \section{Indexing}
1059
1060 The following sample sessions shows the flexibility which is offered
1061 for extracting and inserting entries in matrices or lists.
1062 For additional details enter \verb!help extraction! 
1063 or \verb!help insertion!.
1064 \subsection{Indexing in matrices}
1065 Indexing in matrices can be done by giving the indices of selected
1066 rows and columns or by boolean indices or by using the \verb!$! symbol.
1067 Here is a sample of commands: 
1068 \input{diary/extract.dia}
1069
1070 \subsection{Indexing in lists}
1071 The following session illustrates how to create lists and
1072 insert/extract entries in {\tt list} and {\tt tlist} or {\tt mlist}.
1073 Enter {\tt help insertion} and {\tt help extraction} for additinal examples.
1074 Below is a sample of commands:
1075 \input{diary/list.dia}
1076
1077 \subsection{Structs and Cells \`a la Matlab}
1078 The command {\tt X=tlist(...)} or {\tt Y=mlist(...)} creates a
1079 Scilab variable X of type {\tt tlist} or {\tt mlist}.
1080 The entries of {\tt X} are obtained by the names of their fields.
1081
1082 For instance, if {\tt X=tlist(['mytype','a','b'],A,B)} the command
1083 X.a returns A. If A is a matrix the command X.a(2,3) returns the 
1084 entry at row 2 and column 3 of X;a, i.e. {\tt A(2,3)}.
1085 Similarly, if {\tt Y=mlist(['mytype','a','b'],A,B)}, we can use the
1086 syntax Y(2,3), once the extraction function \verb! %mytype_e(varargin)!
1087 has been defined. 
1088
1089 Also the syntax {\tt Y(2,3)=33} can be given a meaning
1090 through the function \verb!%s_i_mytype(varargin)!. 
1091 This powerful overloading mechanism allows to define complex objects
1092 with a general indexing where indices can be fields (string) or a set
1093 of integers.
1094
1095 If the variable X is not defined in the Scilab workspace, then
1096 the command X.a=A creates a particular mlist which behaves as 
1097 a Matlab struct. Its internal representation is similar to
1098 {\tt X=mlist(['st','dims','a'],int32([1,1]),A)}.
1099 It is a one dimensional {\tt struct} with one field called 'a' and 
1100 the value of X.a is A.
1101 Multidimensional structs are created and manipulated in a similar way.
1102 For instance {\tt X(2,3).a.b(2)=4} creates a 2 x 3 struct with one field
1103 a. It is represented as
1104 \begin{verbatim}
1105 mlist(['st','dims','a'],int32([2,3]),list([],[],[],[],[],w))
1106 \end{verbatim}
1107 where w is a struct with one field 'b', and w.b is the vector [0,4].
1108 A particular display is done for structs. Here, we have:
1109 \begin{verbatim}
1110 -->X(2,3)
1111  ans  =
1112  
1113    a: [1x1 struct]
1114  
1115 -->X(2,3).a
1116  ans  =
1117  
1118    b: [0;4]
1119 \end{verbatim}
1120
1121 All the struct manipulations are implemented by soft coded operations
1122 i.e. Scilab overloaded functions. As structs are not basic data types
1123 some operations are slow. They have been implemented for a better 
1124 Matlab compatibility.
1125
1126 The Matlab cells are also easily emulated. A cell is seen as a particular
1127 struct with one field called 'entries'. We just show a simple example:
1128
1129 \begin{verbatim}
1130
1131 -->X=cell(1,2)
1132  X  =
1133  
1134 !{}  {}  !
1135
1136 -->X(2).entries=11
1137  X  =
1138  
1139 !{}  !
1140 !    !
1141 !11  !
1142 \end{verbatim}
1143
1144 Note that Matlab uses braces \verb!X{2}! for extracting entries from
1145 a cell.