add more help pages related to CAPI - check parameters - optional parameters
[scilab.git] / scilab / modules / core / help / en_US / capi / FindOpt.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="FindOpt" xml:lang="en"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:svg="http://www.w3.org/2000/svg"
6           xmlns:mml="http://www.w3.org/1998/Math/MathML"
7           xmlns:html="http://www.w3.org/1999/xhtml"
8           xmlns:db="http://docbook.org/ns/docbook">
9   <refnamediv>
10     <refname>FindOpt</refname>
11
12     <refpurpose>C interface function find the position of an optional argument
13     given its name</refpurpose>
14   </refnamediv>
15
16   <refsynopsisdiv>
17     <title>Calling Sequence</title>
18
19     <synopsis>Pos FindOpt(varname, opts)</synopsis>
20   </refsynopsisdiv>
21
22   <refsection>
23     <title>Parameters</title>
24
25     <variablelist>
26       <varlistentry>
27         <term>varname</term>
28
29         <listitem>
30           <para>the name of the optional parameter</para>
31         </listitem>
32       </varlistentry>
33
34       <varlistentry>
35         <term>opts</term>
36
37         <listitem>
38           <para>a C list of optional parameters</para>
39
40           <programlisting> 
41 typedef struct rhs_opts__ {
42   int position ; // stack position : -1 if not present
43   char *name; // the name of the variable
44   char *type; // a Scilab type (like "d") representing the type of the variable
45   int m,n; // the size of the variable
46   unsigned long int l; // a pointer to the Scilab stack
47 } rhs_opts;
48  </programlisting>
49         </listitem>
50       </varlistentry>
51
52       <varlistentry>
53         <term>Pos</term>
54
55         <listitem>
56           <para>the rank of the optional parameter if it has been found in the
57           parameters sent to the C function, 0 otherwise.</para>
58         </listitem>
59       </varlistentry>
60     </variablelist>
61   </refsection>
62
63   <refsection>
64     <title>Description</title>
65
66     <para>C interface function find the position of an optional argument given
67     its name. You must include stack-c.h to benefit from this function.</para>
68   </refsection>
69
70   <refsection>
71     <title>Examples</title>
72
73     <para>A more complete example is available in the directory
74     example/optional_parameters.</para>
75
76     <programlisting role="example"> 
77 #include &lt;stack-c.h&gt;
78
79 int sci_optional_parameters(char * fname)
80
81   int m1,n1,l1;
82
83   // optional names must be stored in alphabetical order in opts
84   static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
85                            {-1,"v2","d",0,0,0},
86                            {-1,NULL,NULL,0,0}};
87
88   int minrhs = 1, maxrhs = 1;
89   int minlhs = 1, maxlhs = 3;
90   int nopt, iopos, res;
91   char buffer_name[csiz]; // csiz used for character coding
92
93   nopt = NumOpt();
94
95   CheckRhs(minrhs,maxrhs+nopt);
96   CheckLhs(minlhs,maxlhs);
97
98   // first non optional argument
99   GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
100   
101   if (get_optionals(fname,opts)==0) return 0;
102
103   sciprint("number of optional parameters = %d\n", NumOpt());
104   sciprint("first optional parameters = %d\n", FirstOpt());
105   sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
106   sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
107
108   if (IsOpt(1,buffer_name))
109     sciprint("parameter 1 is optional: %s\n", buffer_name);
110   if (IsOpt(2,buffer_name))
111     sciprint("parameter 2 is optional: %s\n", buffer_name);
112   if (IsOpt(3,buffer_name))
113     sciprint("parameter 3 is optional: %s\n", buffer_name);
114
115   return 0;
116 }
117  </programlisting>
118   </refsection>
119
120   <refsection>
121     <title>See Also</title>
122
123     <simplelist type="inline">
124       <member><link linkend="CheckDims">CheckDims</link></member>
125
126       <member><link linkend="CheckRow">CheckRow</link></member>
127
128       <member><link linkend="CheckScalar">CheckScalar</link></member>
129
130       <member><link linkend="CheckVector">CheckVector</link></member>
131
132       <member><link linkend="OverLoad">CheckOverLoad</link></member>
133
134       <member><link linkend="CheckDimProp">CheckDimProp</link></member>
135
136       <member><link linkend="CheckLength">CheckLength</link></member>
137
138       <member><link linkend="CheckSameDims">CheckSameDims</link></member>
139
140       <member><link linkend="CheckSquare">CheckSquare</link></member>
141
142       <member><link
143       linkend="How to check parameters">HowToCheckParameters</link></member>
144     </simplelist>
145   </refsection>
146 </refentry>