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