add new help pages and examples for CAPI
[scilab.git] / scilab / modules / core / help / en_US / capi / CreateListVarFrom.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="CreateListVarFrom"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:xi="http://www.w3.org/2001/XInclude"
6           xmlns:svg="http://www.w3.org/2000/svg"
7           xmlns:mml="http://www.w3.org/1998/Math/MathML"
8           xmlns:html="http://www.w3.org/1999/xhtml"
9           xmlns:db="http://docbook.org/ns/docbook">
10   <refnamediv>
11     <refname>CreateListVarFrom</refname>
12
13     <refpurpose>a C interface function which allows to create a new Scilab
14     variable in a [mt]list</refpurpose>
15   </refnamediv>
16
17   <refsynopsisdiv>
18     <title>Calling Sequence</title>
19
20     <synopsis>CreateListVarFrom(StackPos,Type, &amp;m_rows, &amp;n_cols, &amp;l_stack_list_pos, &amp;l_stack_pos);</synopsis>
21   </refsynopsisdiv>
22
23   <refsection>
24     <title>Parameters</title>
25
26     <variablelist>
27       <varlistentry>
28         <term>StackPos</term>
29
30         <listitem>
31           <para>the rank of the variable to be created (input
32           parameter)</para>
33         </listitem>
34       </varlistentry>
35
36       <varlistentry>
37         <term>Type</term>
38
39         <listitem>
40           <para>the Scilab type of the variable to be created (input
41           parameter). Can be (see Scilab C Type for more informations):</para>
42
43           <itemizedlist>
44             <listitem>
45               <para>STRING_DATATYPE "c"</para>
46             </listitem>
47
48             <listitem>
49               <para>MATRIX_OF_STRING_DATATYPE "S"</para>
50             </listitem>
51
52             <listitem>
53               <para>MATRIX_OF_DOUBLE_DATATYPE "d"</para>
54             </listitem>
55
56             <listitem>
57               <para>MATRIX_OF_RATIONAL_DATATYPE "r"</para>
58             </listitem>
59
60             <listitem>
61               <para>MATRIX_OF_VARIABLE_SIZE_INTEGER_DATATYPE "I"</para>
62             </listitem>
63
64             <listitem>
65               <para>MATRIX_OF_INTEGER_DATATYPE "i"</para>
66             </listitem>
67
68             <listitem>
69               <para>MATRIX_OF_BOOLEAN_DATATYPE "b"</para>
70             </listitem>
71
72             <listitem>
73               <para>MATRIX_OF_COMPLEX_DATATYPE "z"</para>
74             </listitem>
75
76             <listitem>
77               <para>SPARSE_MATRIX_DATATYPE "s"</para>
78             </listitem>
79
80             <listitem>
81               <para>TYPED_LIST_DATATYPE "t"</para>
82             </listitem>
83
84             <listitem>
85               <para>MATRIX_ORIENTED_TYPED_LIST_DATATYPE "m"</para>
86             </listitem>
87
88             <listitem>
89               <para>SCILAB_POINTER_DATATYPE "p"</para>
90             </listitem>
91
92             <listitem>
93               <para>GRAPHICAL_HANDLE_DATATYPE "h"</para>
94             </listitem>
95
96             <listitem>
97               <para>EXTERNAL_DATATYPE "f"</para>
98             </listitem>
99
100             <listitem>
101               <para>MATRIX_OF_POLYNOMIAL_DATATYPE "x"</para>
102             </listitem>
103           </itemizedlist>
104         </listitem>
105       </varlistentry>
106
107       <varlistentry>
108         <term>m_rows</term>
109
110         <listitem>
111           <para>the number of lines of the matrix to be created (input
112           parameter)</para>
113         </listitem>
114       </varlistentry>
115
116       <varlistentry>
117         <term>n_cols</term>
118
119         <listitem>
120           <para>the number of columns of the matrix to be created (input
121           parameter)</para>
122         </listitem>
123       </varlistentry>
124
125       <varlistentry>
126         <term>l_stack_list_pos</term>
127
128         <listitem>
129           <para>the position on the stack of the created variable in the
130           list(output parameter)</para>
131         </listitem>
132       </varlistentry>
133
134       <varlistentry>
135         <term>l_stack_pos</term>
136
137         <listitem>
138           <para>the position on the stack of the created variable (input
139           parameter)</para>
140         </listitem>
141       </varlistentry>
142     </variablelist>
143   </refsection>
144
145   <refsection>
146     <title>Description</title>
147
148     <para>A C interface function which allows to create a new Scilab variable
149     in a [mt]list</para>
150   </refsection>
151
152   <refsection>
153     <title>Examples</title>
154
155     <programlisting role="example"> 
156 #include &lt;stack-c.h&gt;
157 #include &lt;string.h&gt;
158
159 int sci_create_list(char * fname)
160 {
161   int m_list_out, n_list_out;
162   int m_var1,     n_var1,     l_var1,  l_list_var1;
163   int m_var2,     n_var2,     l_var2,  l_list_var2;
164   int m_mlist,    n_mlist,    l_mlist;
165  
166   // The labels of our mlist 
167   static const char * ListLabels [] = {"mylist","var1","var2"};
168
169   // First, we create the variables using a classical way
170   // The size of the Scilab variables
171   m_var1  = 1; n_var1  = strlen("a string")+1; // a null terminated string
172   m_var2  = 2; n_var2  = 2; // A 2x2 double matrix
173   m_mlist = 3; n_mlist = 1; // A mlist with 3 elements
174   
175   // Creation of the Scilab variables
176   // A('var1')
177   CreateVar(1, "c", &amp;m_var1,  &amp;n_var1,  &amp;l_var1);
178   // A('var2')
179   CreateVar(2, "d", &amp;m_var2,  &amp;n_var2,  &amp;l_var2);
180   // A
181   CreateVar(3, "m", &amp;m_mlist, &amp;n_mlist, &amp;l_mlist);
182   
183   // We store values in the create variables
184   // The matrix will be stored in A('var2')
185   *stk(l_var2+0) = 1;              
186   *stk(l_var2+1) = 2;              
187   *stk(l_var2+2) = 3;              
188   *stk(l_var2+3) = 4;              
189   
190   // The string will be stored in A('var1')
191   strncpy(cstk(l_var1),"a string\0",n_var1);
192   
193   m_list_out = 3; n_list_out = 1;
194   
195   // now, affect the variable  to the mlist
196   // The labels (it corresponds to A = mlist(['mylist','var1','var2'], ...
197   CreateListVarFromPtr(3, 1, "S", &amp;m_list_out, &amp;n_list_out, ListLabels);
198   // The value stored in A('var1') (it corresponds to A = ...,'a string', ...
199   CreateListVarFrom(3, 2, "c", &amp;m_var1, &amp;n_var1, &amp;l_list_var1, &amp;l_var1);
200   // The value stored in A('var2') (it corresponds to A = ...,[1 2,3 4]);
201   CreateListVarFrom(3, 3, "d", &amp;m_var2, &amp;n_var2, &amp;l_list_var2, &amp;l_var2);
202   
203   // We return only the mlist which has been created at position 3
204   LhsVar(1) = 3;
205   
206   return 0;
207 }
208  </programlisting>
209
210     <para>This example is available in example/create_list.</para>
211
212   </refsection>
213
214   <refsection>
215     <title>See Also</title>
216
217     <simplelist type="inline">
218       <member><link linkend="ScilabCTypes">Scilab C Type</link></member>
219
220       <member><link linkend="istk">istk</link></member>
221
222       <member><link linkend="LhsVar">LhsVar</link></member>
223
224       <member><link linkend="CreateVar">CreateVar</link></member>
225     </simplelist>
226   </refsection>
227 </refentry>