add new help pages and examples for CAPI
[scilab.git] / scilab / modules / core / help / en_US / capi / CreateListVarFromPtr.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="CreateListVarFromPtr"
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>CreateListVarFromPtr</refname>
12
13     <refpurpose>a C interface function which allows to create a new Scilab
14     variable from a pointer 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, void * Pointer);</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 list
130           (output parameter)</para>
131         </listitem>
132       </varlistentry>
133
134       <varlistentry>
135         <term>Pointer</term>
136
137         <listitem>
138           <para>the pointer to the data area (input parameter)</para>
139         </listitem>
140       </varlistentry>
141     </variablelist>
142   </refsection>
143
144   <refsection>
145     <title>Description</title>
146
147     <para>A C interface function which allows to create a new Scilab variable
148     from a pointer in a [mt]list</para>
149   </refsection>
150
151   <refsection>
152     <title>Examples</title>
153
154     <programlisting role="example"> 
155 #include &lt;stack-c.h&gt;
156 #include &lt;string.h&gt;
157
158 int sci_create_list(char * fname)
159 {
160   int m_list_out, n_list_out;
161   int m_var1,     n_var1,     l_var1,  l_list_var1;
162   int m_var2,     n_var2,     l_var2,  l_list_var2;
163   int m_mlist,    n_mlist,    l_mlist;
164  
165   // The labels of our mlist 
166   static const char * ListLabels [] = {"mylist","var1","var2"};
167
168   // First, we create the variables using a classical way
169   // The size of the Scilab variables
170   m_var1  = 1; n_var1  = strlen("a string")+1; // a null terminated string
171   m_var2  = 2; n_var2  = 2; // A 2x2 double matrix
172   m_mlist = 3; n_mlist = 1; // A mlist with 3 elements
173   
174   // Creation of the Scilab variables
175   // A('var1')
176   CreateVar(1, "c", &amp;m_var1,  &amp;n_var1,  &amp;l_var1);
177   // A('var2')
178   CreateVar(2, "d", &amp;m_var2,  &amp;n_var2,  &amp;l_var2);
179   // A
180   CreateVar(3, "m", &amp;m_mlist, &amp;n_mlist, &amp;l_mlist);
181   
182   // We store values in the create variables
183   // The matrix will be stored in A('var2')
184   *stk(l_var2+0) = 1;              
185   *stk(l_var2+1) = 2;              
186   *stk(l_var2+2) = 3;              
187   *stk(l_var2+3) = 4;              
188   
189   // The string will be stored in A('var1')
190   strncpy(cstk(l_var1),"a string\0",n_var1);
191   
192   m_list_out = 3; n_list_out = 1;
193   
194   // now, affect the variable  to the mlist
195   // The labels (it corresponds to A = mlist(['mylist','var1','var2'], ...
196   CreateListVarFromPtr(3, 1, "S", &amp;m_list_out, &amp;n_list_out, ListLabels);
197   // The value stored in A('var1') (it corresponds to A = ...,'a string', ...
198   CreateListVarFrom(3, 2, "c", &amp;m_var1, &amp;n_var1, &amp;l_list_var1, &amp;l_var1);
199   // The value stored in A('var2') (it corresponds to A = ...,[1 2,3 4]);
200   CreateListVarFrom(3, 3, "d", &amp;m_var2, &amp;n_var2, &amp;l_list_var2, &amp;l_var2);
201   
202   // We return only the mlist which has been created at position 3
203   LhsVar(1) = 3;
204   
205   return 0;
206 }
207  </programlisting>
208
209     <para>This example is available in example/create_list.</para>
210
211   </refsection>
212
213   <refsection>
214     <title>See Also</title>
215
216     <simplelist type="inline">
217       <member><link linkend="ScilabCTypes">Scilab C Type</link></member>
218
219       <member><link linkend="istk">istk</link></member>
220
221       <member><link linkend="LhsVar">LhsVar</link></member>
222
223       <member><link linkend="CreateVar">CreateVar</link></member>
224     </simplelist>
225   </refsection>
226 </refentry>