From 65fe133e2d6ab1aa9a4bcf03bfeb3bb4e37074b3 Mon Sep 17 00:00:00 2001 From: Simon Marchetto Date: Wed, 2 Apr 2014 16:39:26 +0200 Subject: [PATCH] scilab: document argument passing --- Doc/Manual/Scilab.html | 118 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 114 insertions(+), 4 deletions(-) diff --git a/Doc/Manual/Scilab.html b/Doc/Manual/Scilab.html index 5fc527c34..9b321f2e3 100644 --- a/Doc/Manual/Scilab.html +++ b/Doc/Manual/Scilab.html @@ -316,7 +316,8 @@ SWIG for Scilab provides only low-level C interface for Scilab. This means that In Scilab 5.x, identifier names can be composed of 24 chars maximum (this limitation disappears in future version of Scilab 6.0).
So long function or variable names may be truncated, which can be cause of conflict.

-

It happens especially when wrapping structs/classes, for which the wrapping functions name are composed of the struct/class name and field names. In that case, the SWIG rename instruction, to choose a different wrapping name, can be useful. +

It happens especially when wrapping structs/classes, for which the wrapping functions name are composed of the struct/class name and field names. +In that case, the SWIG rename instruction, to choose a different wrapping name, can be useful.

37.3.3 Functions

@@ -327,8 +328,16 @@ Functions are wrapped as new Scilab built-in functions. For example: 

-%module example
-int fact(int n);
+%module example
+
+%inline %{
+int fact(int n) {
+  if (n > 1)
+    return n * fact(n - 1);
+  else
+    return 1;
+}
+%}

@@ -343,6 +352,105 @@ ans = +

+In this example, the function parameter is of simple type, and transmitted by value. +So this function is wrapped without any other work than declaring it. +

+ +

+Argument values are converted automatically between C and Scilab through type mappings which are described here. +There are several available type mappings for simple and complex types. +

+ +

+When a parameter is not transmitted by value, is a pointer (or a reference), SWIG does not know if it is an input, output (or both) parameter. +The argument type can be specified with the INPUT, OUTPUT, INOUT keywords defined in the library typemaps.i +

+ +

+Let's see it on two simple functions: +

+ +
+%module example
+
+%include typemaps.i
+
+extern void sub(int *INPUT, int *INPUT, int *OUTPUT);
+extern void inc(int *INOUT, int *INPUT);
+
+%{
+void sub(int *x, int *y, int *result) {
+  *result = *x - *y;
+}
+void inc(int *x, int *delta) {
+  *x = *x + *delta;
+}
+%}
+
+ +

+Note: in fact, it is not necessary to include the library typemaps.i, this one is included by default. +

+ +

+In Scilab, parameters are passed by value. The output (and inout) parameters are returned as result of the functions: +

+ +
+-->sub(5, 3)
+ ans  =
+
+    2.
+
+-->inc(4, 3)
+ ans  =
+
+    7.
+
+ +

+Scilab supports multiple values to be returned from a function. +A C function can have several output parameters, they are all returned as results of the wrapped function. +If the function itself returns also a result, it is returned in first in the result of the function. +

+ +

+This example shows this for a function returning 2 values and a result: +

+ +
+%module example
+
+int divide(int n, int d, int *OUTPUT, int *OUTPUT);
+
+%{
+int divide(int n, int d, int q*, int *r) {
+   if (d != 0) {
+     *q = n / d;
+     *r = n % d;
+     return 1;
+   }
+   else return 0;
+}
+%}
+
+ +

+

+-->[ret, q, r] = divide(20, 6)
+ r  =
+
+    2.
+ q  =
+
+    3.
+ ret  =
+
+    1.
+
+

+

37.3.4 Global variables

@@ -554,7 +662,9 @@ typedef enum { RED, BLUE, GREEN } color; C/C++ pointers are fully supported by SWIG. They are mapped to the Scilab pointer type ("pointer", type ID 128).

-

Given a wrapping of some of the C file functions:

+

+Given a wrapping of some of the C file functions: +

 %module example