add more help pages related to CAPI - check parameters - optional parameters
[scilab.git] / scilab / modules / core / help / en_US / capi / OverLoad.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="OverLoad" 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>OverLoad</refname>
11
12     <refpurpose>C interface function which tells Scilab to look for another
13     overloaded function</refpurpose>
14   </refnamediv>
15
16   <refsynopsisdiv>
17     <title>Calling Sequence</title>
18
19     <synopsis>OverLoad(StackPos)</synopsis>
20   </refsynopsisdiv>
21
22   <refsection>
23     <title>Parameters</title>
24
25     <variablelist>
26       <varlistentry>
27         <term>StackPos</term>
28
29         <listitem>
30           <para>the position on the stack of the variable for which we want to
31           take into account for the overloading process (input
32           parameter)</para>
33         </listitem>
34       </varlistentry>
35     </variablelist>
36   </refsection>
37
38   <refsection>
39     <title>Description</title>
40
41     <para>C interface function which tells Scilab to look for another
42     overloaded function. Scilab then appends to the name of the function a
43     prefix (like %sp_ if the parameter taken into account is sparse) and look
44     for the overloaded function. You must include stack-c.h to benefit from
45     this function. Be careful with the Scilab name of the function. Indeed,
46     the current overloading process of Scilab works only on Scilab primitives
47     (Scilab function wrote in C) which must have a name which is maximum 8
48     char wide.</para>
49   </refsection>
50
51   <refsection>
52     <title>Examples</title>
53
54     <para>In this example, the C interface function takes one input parameters
55     and prints the integer corresponding to the type of the variable sent as
56     parameter in the Scilab console.</para>
57
58     <programlisting> 
59 #include &lt;stack-c.h&gt;
60 #include &lt;sciprint.h&gt;
61
62 int sci_check_properties_2(char * fname)
63 {
64   int m1,n1,l1;
65
66   CheckRhs(1,1);
67   CheckLhs(0,1) ;
68
69   switch(VarType(1)) 
70     {
71     case sci_matrix: 
72       GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
73       sciprint("1 is a scalar matrix\n");
74       break;
75     case sci_strings:
76       GetRhsVar(1, "c", &amp;m1, &amp;n1, &amp;l1);
77       sciprint("1 is a string\n");
78       break;
79     case sci_sparse:
80       sciprint("1 is a sparse trying to overload\n");
81       OverLoad(1);
82     }
83
84   LhsVar(1) = 0;
85
86   return 0;
87 }
88  </programlisting>
89
90     <para>The builder.sce script look like this:</para>
91
92     <programlisting> 
93 // This is the builder.sce 
94 // must be run from this directory 
95
96 lines(0);
97
98 ilib_name  = 'lib_check_properties';
99
100 files = ['check_properties.c'];
101
102 libs  = [];
103
104 table =['chprop2', 'sci_check_properties_2'];
105
106 // We must be careful when we choose a scilab function name in case of overloading.
107 // We Scilab name function must be 8 char max.
108
109 ldflags = "";
110 cflags  = "";
111 fflags  = "";
112
113 // do not modify below 
114 // ----------------------------------------------
115 ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
116  </programlisting>
117
118     <para>And now, an example of use of this new function:</para>
119
120     <programlisting> 
121 chprop2([1,2,2]);
122 chprop2('foo');
123
124 // overload case 
125
126 deff('[]=%sp_chprop2(sp)','disp(''sparse overloaded'')');
127 chprop2(sparse([1,2,3]));
128  </programlisting>
129   </refsection>
130
131   <refsection>
132     <title>See Also</title>
133
134     <simplelist type="inline">
135       <member><link linkend="CheckColumn">CheckColumn</link></member>
136       <member><link linkend="CheckDims">CheckDims</link></member>
137       <member><link linkend="CheckRow">CheckRow</link></member>
138       <member><link linkend="CheckScalar">CheckScalar</link></member>
139       <member><link linkend="CheckVector">CheckVector</link></member>
140       <member><link linkend="CheckDimProp">CheckDimProp</link></member>
141       <member><link linkend="CheckLength">CheckLength</link></member>
142       <member><link linkend="CheckSameDims">CheckSameDims</link></member>
143       <member><link linkend="CheckSquare">CheckSquare</link></member>
144       <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
145     </simplelist>
146   </refsection>
147 </refentry>