SWIG 3 中文手冊——10. 參數處理

目錄

• 10 參數處理
  • 10.1 typemaps.i 庫
    • 10.1.1 引言
    • 10.1.2 輸入參數
    • 10.1.3 輸出參數
    • 10.1.4 輸入 / 輸出參數
    • 10.1.5 使用不一樣的名稱
  • 10.2 對輸入值施加約束
    • 10.2.1 簡單約束的例子
    • 10.2.2 約束方法
    • 10.2.3 對新的數據類型應用約束

10 參數處理

In Chapter 3, SWIG's treatment of basic datatypes and pointers was described. In particular, primitive types such as int and double are mapped to corresponding types in the target language. For everything else, pointers are used to refer to structures, classes, arrays, and other user-defined datatypes. However, in certain applications it is desirable to change SWIG's handling of a specific datatype. For example, you might want to return multiple values through the arguments of a function. This chapter describes some of the techniques for doing this.

第 3 章介紹了 SWIG 對基本數據類型和指針的處理。特別地，原始類型（諸如 int 和 double）被映射到目標語言中的相應類型。對於其餘全部類型，都使用指針來引用結構體、類、數組和其餘用戶定義的數據類型。可是，在某些應用程序中，但願更改 SWIG 對特定數據類型的處理。例如，你可能想經過函數的參數返回多個值。本章介紹了一些執行此類操做的技術。

10.1 typemaps.i 庫

This section describes the typemaps.i library file--commonly used to change certain properties of argument conversion.

本節描述 typemaps.i 庫文件——一般用於更改參數轉換的某些屬性。

10.1.1 引言

Suppose you had a C function like this:

假設你有以下 C 函數：

void add(double a, double b, double *result) {
  *result = a + b;
}

From reading the source code, it is clear that the function is storing a value in the double *result parameter. However, since SWIG does not examine function bodies, it has no way to know that this is the underlying behavior.

One way to deal with this is to use the typemaps.i library file and write interface code like this:

經過閱讀源代碼，很明顯該函數將值存儲在 double *result 參數中。可是，因爲 SWIG 不檢查函數主體，所以沒有辦法知道函數的底層行爲。

一種解決方法是使用 typemaps.i 庫文件，並編寫以下接口代碼：

// Simple example using typemaps
%module example
%include "typemaps.i"

%apply double *OUTPUT { double *result };
%inline %{
extern void add(double a, double b, double *result);
%}

The %apply directive tells SWIG that you are going to apply a special type handling rule to a type. The double *OUTPUT specification is the name of a rule that defines how to return an output value from an argument of type double *. This rule gets applied to all of the datatypes listed in curly braces--in this case double *result.

When the resulting module is created, you can now use the function like this (shown for Python):

%apply 指令告訴 SWIG 你將要對某類型應用特殊的類型處理規則。double *OUTPUT 規範是一個規則的名稱，該規則定義瞭如何從類型爲 double * 的參數返回輸出值。該規則將應用於大括號中列出的全部數據類型，在這個例子中爲 double *result。

結果模塊建立後，你如今能夠這樣使用如下函數（針對 Python）：

>>> a = add(3, 4)
>>> print a
7
>>>

In this case, you can see how the output value normally returned in the third argument has magically been transformed into a function return value. Clearly this makes the function much easier to use since it is no longer necessary to manufacture a special double * object and pass it to the function somehow.

Once a typemap has been applied to a type, it stays in effect for all future occurrences of the type and name. For example, you could write the following:

在這個例子中，你能夠看到一般在第三個參數中返回的輸出值如何神奇地轉換爲函數返回值。顯然，這使函數更易於使用，由於再也不須要製造特殊的 double * 對象，並將其以某種方式傳遞給函數。

一旦將類型映射應用於類型後，它對於之後全部出現的類型和名稱都保持有效。例如，你能夠編寫如下內容：

%module example
%include "typemaps.i"

%apply double *OUTPUT { double *result };

%inline %{
extern void add(double a, double b, double *result);
extern void sub(double a, double b, double *result);
extern void mul(double a, double b, double *result);
extern void div(double a, double b, double *result);
%}
...

In this case, the double *OUTPUT rule is applied to all of the functions that follow.

Typemap transformations can even be extended to multiple return values. For example, consider this code:

在這個例子中，double *OUTPUT 規則將應用於隨後的全部函數。

類型映射轉換甚至能夠擴展爲多個返回值。例如，考慮如下代碼：

%include "typemaps.i"
%apply int *OUTPUT { int *width, int *height };

// Returns a pair (width, height)
void getwinsize(int winid, int *width, int *height);

In this case, the function returns multiple values, allowing it to be used like this:

在這個例子中，該函數返回多個值，從而能夠像這樣使用它：

>>> w, h = genwinsize(wid)
>>> print w
400
>>> print h
300
>>>

It should also be noted that although the %apply directive is used to associate typemap rules to datatypes, you can also use the rule names directly in arguments. For example, you could write this:

還應該注意，儘管已經使用 %apply 指令將類型映射規則與數據類型相關聯，可是你也能夠直接在參數中使用規則名稱。例如，你能夠這樣編寫接口文件：

// Simple example using typemaps
%module example
%include "typemaps.i"

%{
extern void add(double a, double b, double *OUTPUT);
%}
extern void add(double a, double b, double *OUTPUT);

Typemaps stay in effect until they are explicitly deleted or redefined to something else. To clear a typemap, the %clear directive should be used. For example:

類型映射將一直有效，直到將其明確刪除或從新定義爲其餘類型爲止。要清除類型映射，應使用 %clear 指令。例如：

%clear double *result;      // Remove all typemaps for double *result

10.1.2 輸入參數

The following typemaps instruct SWIG that a pointer really only holds a single input value:

如下類型映射告訴 SWIG，指針實際上僅保存一個輸入值：

int *INPUT
short *INPUT
long *INPUT
unsigned int *INPUT
unsigned short *INPUT
unsigned long *INPUT
double *INPUT
float *INPUT

When used, it allows values to be passed instead of pointers. For example, consider this function:

使用時，它容許傳遞值而不是指針。例如，考慮如下函數：

double add(double *a, double *b) {
  return *a + *b;
}

Now, consider this SWIG interface:

如今，考慮編寫 SWIG 接口文件：

%module example
%include "typemaps.i"
...
%{
extern double add(double *, double *);
%}
extern double add(double *INPUT, double *INPUT);

When the function is used in the scripting language interpreter, it will work like this:

在腳本語言解釋器中使用該函數時，它將像下面這樣工做：

result = add(3, 4)

10.1.3 輸出參數

The following typemap rules tell SWIG that pointer is the output value of a function. When used, you do not need to supply the argument when calling the function. Instead, one or more output values are returned.

如下類型映射規則告訴 SWIG，指針是函數的輸出值。使用時，在調用函數時不須要提供參數。而是返回一個或多個輸出值。

int *OUTPUT
short *OUTPUT
long *OUTPUT
unsigned int *OUTPUT
unsigned short *OUTPUT
unsigned long *OUTPUT
double *OUTPUT
float *OUTPUT

These methods can be used as shown in an earlier example. For example, if you have this C function :

能夠如先前示例中所示使用這些方法。例如，若是你具備如下 C 函數：

void add(double a, double b, double *c) {
  *c = a + b;
}

A SWIG interface file might look like this :

SWIG 接口文件可能以下：

%module example
%include "typemaps.i"
...
%inline %{
extern void add(double a, double b, double *OUTPUT);
%}

In this case, only a single output value is returned, but this is not a restriction. An arbitrary number of output values can be returned by applying the output rules to more than one argument (as shown previously).

If the function also returns a value, it is returned along with the argument. For example, if you had this:

在這個例子中，僅返回單個輸出值，但這不是限制。經過將輸出規則應用於多個參數（如上所示），能夠返回任意數量的輸出值。

若是函數還返回值，則將其與參數一塊兒返回。例如，若是你有：

extern int foo(double a, double b, double *OUTPUT);

The function will return two values like this:

函數將返回兩個值：

iresult, dresult = foo(3.5, 2)

10.1.4 輸入 / 輸出參數

When a pointer serves as both an input and output value you can use the following typemaps :

當指針既用做輸入值又用做輸出值時，可使用如下類型映射：

int *INOUT
short *INOUT
long *INOUT
unsigned int *INOUT
unsigned short *INOUT
unsigned long *INOUT
double *INOUT
float *INOUT

A C function that uses this might be something like this:

有這樣一個 C 函數：

void negate(double *x) {
  *x = -(*x);
}

To make x function as both and input and output value, declare the function like this in an interface file :

要使 x 既做爲函數的輸入值又做爲輸出值，請在接口文件中聲明以下函數：

%module example
%include "typemaps.i"
...
%{
extern void negate(double *);
%}
extern void negate(double *INOUT);

Now within a script, you can simply call the function normally :

如今，在腳本中能夠輕鬆地調用函數：

a = negate(3);         # a = -3 after calling this

One subtle point of the INOUT rule is that many scripting languages enforce mutability constraints on primitive objects (meaning that simple objects like integers and strings aren't supposed to change). Because of this, you can't just modify the object's value in place as the underlying C function does in this example. Therefore, the INOUT rule returns the modified value as a new object rather than directly overwriting the value of the original input object.

Compatibility note : The INOUT rule used to be known as BOTH in earlier versions of SWIG. Backwards compatibility is preserved, but deprecated.

INOUT 規則的一個細微之處是，許多腳本語言對原始對象實施了可變性約束（這意味着簡單的對象，如整數和字符串，不該更改）。所以，你不能像在此示例中基礎 C 函數那樣就地修改對象的值。所以，INOUT 規則將修改後的值做爲新對象返回，而不是直接覆蓋原始輸入對象的值。

注意兼容性：在早期版本的 SWIG 中，INOUT 規則之前被稱爲 BOTH。已保留向後兼容性，但已棄用。

10.1.5 使用不一樣的名稱

As previously shown, the %apply directive can be used to apply the INPUT, OUTPUT, and INOUT typemaps to different argument names. For example:

如前所示，%apply 指令可用於將 INPUT、OUTPUT 和 INOUT 類型映射應用於不一樣的參數名稱。例如：

// Make double *result an output value
%apply double *OUTPUT { double *result };

// Make Int32 *in an input value
%apply int *INPUT { Int32 *in };

// Make long *x inout
%apply long *INOUT {long *x};

To clear a rule, the %clear directive is used:

爲了清理掉規則，要使用 %clear 指令：

%clear double *result;
%clear Int32 *in, long *x;

Typemap declarations are lexically scoped so a typemap takes effect from the point of definition to the end of the file or a matching %clear declaration.

類型映射聲明在詞法上是做用域的，所以類型映射從定義點開始到文件末尾，或匹配的 %clear 聲明以前均生效。

10.2 對輸入值施加約束

In addition to changing the handling of various input values, it is also possible to use typemaps to apply constraints. For example, maybe you want to insure that a value is positive, or that a pointer is non-NULL. This can be accomplished including the constraints.i library file.

除了更改對各類輸入值的處理以外，還可使用類型映射來應用約束。例如，也許你想確保一個值是正數，或者一個指針是非 NULL 的。這能夠經過包含 constraints.i 庫文件來完成。

10.2.1 簡單約束的例子

The constraints library is best illustrated by the following interface file :

如下接口文件是對 constraints.i 庫最好的說明：

// Interface file with constraints
%module example
%include "constraints.i"

double exp(double x);
double log(double POSITIVE);         // Allow only positive values
double sqrt(double NONNEGATIVE);     // Non-negative values only
double inv(double NONZERO);          // Non-zero values
void   free(void *NONNULL);          // Non-NULL pointers only

The behavior of this file is exactly as you would expect. If any of the arguments violate the constraint condition, a scripting language exception will be raised. As a result, it is possible to catch bad values, prevent mysterious program crashes and so on.

該文件的行爲與你指望的徹底同樣。若是任何參數違反約束條件，將引起腳本語言異常。最終，可能會捕獲錯誤的值，防止神祕的程序崩潰，等等。

10.2.2 約束方法

The following constraints are currently available

下列約束是當前可用的：

POSITIVE                     Any number > 0 (not zero)
NEGATIVE                     Any number < 0 (not zero)
NONNEGATIVE                  Any number >= 0
NONPOSITIVE                  Any number <= 0
NONZERO                      Nonzero number
NONNULL                      Non-NULL pointer (pointers only).

10.2.3 對新的數據類型應用約束

The constraints library only supports the primitive C datatypes, but it is easy to apply it to new datatypes using %apply. For example :

約束庫僅支持原始 C 數據類型，但使用 %apply 能夠很容易地將其應用於新的數據類型。例如 ：

// Apply a constraint to a Real variable
%apply Number POSITIVE { Real in };

// Apply a constraint to a pointer type
%apply Pointer NONNULL { Vector * };

The special types of "Number" and "Pointer" can be applied to any numeric and pointer variable type respectively. To later remove a constraint, the %clear directive can be used :

特殊類型的 Number 和 Pointer 能夠分別應用於任何數字和指針變量類型。爲了之後刪除約束，可使用 %clear 指令：

%clear Real in;
%clear Vector *;