11.1 介绍

11.1.1 类型转换(Type Conversion)

在编程语言之间做数据类型的装换(conversion)或列集(marshalling)是包装代码生成器(wrapper code generator)的一项中非常重要的工作。对每一种c/C++的类型声明(declaration)，SWIG必须以某种方式生成包装代码用以在语言间来回传递数据的值（value）。由于每种编程语言表达数据的方式不同，因此不能简单将代码使用C连接器连接在一起。SWIG需要知道每种语言是如何表达数据的，并且需要知道怎样去操作它们。

为说明问题，假设你有下面一段简单的C代码：

int factorial(int n);

为了能从Python中访问该函数，需要使用一对Python API函数转换整形数据。例如：

long PyInt_AsLong(PyObject *obj); /* Python --> C */
PyObject *PyInt_FromLong(long x); /* C --> Python */

第一个函数用来将输入参数Python整形对象转换为C语言的long类型。第二个函数用来将C语言的long型数值转换回Python的整形对象。

在包装函数内部，你可能看到类似下面的下面的函数：

PyObject *wrap_factorial(PyObject *self, PyObject *args) {
    int arg1;
    int result;
    PyObject *obj1;
    PyObject *resultobj;
    if (!PyArg_ParseTuple("O:factorial", &obj1)) return NULL;
    arg1 = PyInt_AsLong(obj1);
    result = factorial(arg1);
    resultobj = PyInt_FromLong(result);
    return resultobj;
}

SWIG支持的每一种目标语言都有类似的转换函数。比如，在Perl中，使用如下的函数：

IV SvIV(SV *sv); /* Perl --> C */
void sv_setiv(SV *sv, IV val); /* C --> Perl */

在TCL中：

int Tcl_GetLongFromObj(Tcl_Interp *interp, Tcl_Obj *obj, long *value);
Tcl_Obj *Tcl_NewIntObj(long value);

在这里，具体细节不是那么重要。重要的是，所有的底层类型转换都使用类似的功能函数，如果你对语言扩展感兴趣可以阅读各种语言相关的文档，这些实验就留给你们自己去练习吧。

11.1.2 Typemaps

因为类型转换时代码包装生成器的中心工作，SWIG允许用户完全定义（或重定义）。为此，你可以使用特

殊的%typemap指令。例如：

/* Convert from Python --> C */
%typemap(in) int {
    $1 = PyInt_AsLong($input);
}

/* Convert from C --> Python */
%typemap(out) int {
    $result = PyInt_FromLong($1);
}

第一次看到这样的代码，你肯定会迷迷糊糊地。但这真的是没什么大不了的。第一个typemap("in" typemap)用来从目标语言转换数值(value)到C语言。第二个typemap("out" typemap)用于从C语言转换数据到目标语言。每个typemap的内容都是一小段代码片段，直接插入SWIG生成的包装函数代码中。这些代码一般是C或C++代码，通过包装代码生成器处理后插入包装函数中。需要注意的是，某些目标语言的typemap也允许目标语言代码的插入。在这些代码中，带$前缀的特殊变量会自动展开。这些变量只是C/C++语言变量的占位符号，经处理后会插入最终的包装代码中。$input表示需要转换到C/C++的输入对象，$result表示包装函数要返回的对象。$1表示C/C++变量，它的类型就是typemap申明中(这个例子中的int)指定的。

给一个简单的例子更好理解。如果你想包装如下的函数：

int gcd(int x, int y);

包装函数可能如下：

PyObject *wrap_gcd(PyObject *self, PyObject *args) {
  int arg1;
  int arg2;
  int result;
  PyObject *obj1;
  PyObject *obj2;
  PyObject *resultobj;
  if (!PyArg_ParseTuple("OO:gcd", &obj1, &obj2)) return NULL;
  /* "in" typemap, argument 1 */
  {
      arg1 = PyInt_AsLong(obj1);
  }
  /* "in" typemap, argument 2 */
  {
    arg2 = PyInt_AsLong(obj2);
  }
  result = gcd(arg1, arg2);
  /* "out" typemap, return value */
  {
    resultobj = PyInt_FromLong(result);
  }
  return resultobj;
}

在这段代码中，你能看到typemap是如何插入到生成的函数中的。你也可以看到特殊变量$是如何匹配特定变量名，并在包装函数中展开的。这就是typemap的全部思想，它们可以让你插入任意代码到生成的包装函数的不同地方。因为人意代码都可以插入，它可能完全改变值被改变的方式。

11.1.3 模式匹配(Pattern Matching)

正如名字所暗含的意思，typemap的目的就是在目标语言中映射("map")C语言数据类型。一旦某个C语言数据类型的typemap被定义，输入文件中所有出现的该类型都会应用其特征。例如：

/* Convert from Perl --> C */
%typemap(in) int {
    $1 = SvIV($input);
}
...
int factorial(int n);
int gcd(int x, int y);
int count(char *s, char *t, int max);

匹配typemap到其相应的C语言数据类型不是简单的文本匹配。事实上，typemap全面内置(builtin)于底层的类型系统中。因此，typemap并不受typedef、namespace或其他可能会隐藏底层类型的声明的影响。例如，可能你有如下代码：

/* Convert from Ruby--> C */
%typemap(in) int {
    $1 = NUM2INT($input);
}.
..
typedef int Integer;
namespace foo {
    typedef Integer Number;
};
int foo(int x);
int bar(Integer y);
int spam(foo::Number a, foo::Number b);

这种情况下，typemap依然可以应用到合适的参数上，即使typemap的类型名不总能匹配int。实际上，这种跟踪类型的能力是SWIG的重要部分，所有的目标语言模块都为基础类型定义了一组typemap。同时，没有必要为typedef定义新的typemap。

除了跟踪类型名字，typemap还可以特别指定去匹配特定的参数名。例如，你写了如下代码：

%typemap(in) double nonnegative {
  $1 = PyFloat_AsDouble($input);
  if ($1 < 0) {
    PyErr_SetString(PyExc_ValueError, "argument must be nonnegative.");
    SWIG_fail;
  }
}
...
double sin(double x);
double cos(double x);
double sqrt(double nonnegative);
typedef double Real;
double log(Real nonnegative);

在对输入参数进行转换的情况下，typemap可以被定义成能处理连续参数的样式。例如：

%typemap(in) (char *str, int len) {
  $1 = PyString_AsString($input);     /* char *str */
  $2 = PyString_Size($input);         /* int len */
}.
..
int count(char *str, int len, char c);

这种情况下，目标语言的一个输入对象被扩展成一对C语言参数。这个例子还展示了不常用的变量命名方案，$1、$2，诸如此类等。

11.1.4 重用typemap

Typemap一般用于指定的类型和参数名模式。但是，也可以被拷贝和复制。这样做的一种方式是想下面这样赋值：

%typemap(in) Integer = int;
%typemap(in) (char *buffer, int size) = (char *str, int len);

更通用的拷贝形式是使用如下的%apply指令：

%typemap(in) int {
/* Convert an integer argument */
...
}%
typemap(out) int {
/* Return an integer value */
...
}
/* Apply all of the integer typemaps to size_t */
%apply int { size_t };

%apply指令仅仅是把针对某种类型的所有typemap应用到另外一种类型上。

需要注意是是，没有必要为某种类型的typedef拷贝新的typemap。例如，如果你有如下代码：

typedef int size_t;

SWIG就已经知道应用int的typemap了，不需要再做其他工作。

11.1.5 使用typemap能干什么

使用typemap的主要目的就是为C/C++数据类型层面定义包装器的行为。当前typemap可以定位6种通用类别的问题：

参数处理(Argument Handing)

int foo(int x, double y, char *s);
- 输入参数转换("in" typemap)
- 重载(overloading)函数输入参数类型转换检查("typecheck" typemap)
- 输出产出处理("argout" typemap)
- 输入参数值的检查("check" typemap)
- 输入参数值的初始化("arginit" typemap)
- 默认参数("default" typemap)
- 输入参数资源管理("freearg" typemap)
返回值处理（Return Value Handling）

int foo(int x, double y, char *s);
- 函数返回值转换（"out" typemap)
- 返回值资源管理("ret" typemap)
- 新分配对象的资源管理("newfree" typemap)
异常处理(Exception Handling)

int foo(int x, double y, char s) throw(*MemoryError, IndexError);
- 处理C++异常说明("throw" typemap)
全局变量(Global Variables)

int foo;
- 全局变量的赋值("varin" typemap)
- 返回全局变量("varout" typemap)
成员变量(Member Variables)

struct Foo { int x[20]; };

对类或结构体的成员进行赋值("memberin" typemap)

创建常量(Constant Creation)

#define FOO 3

%constant int BAR = 42; enum { ALE, LAGER, STOUT };
- 常量的创建("consttab"或者"constcode" typemap)

每个typemap我们都会做简短地描述。某些语言的模块也会定义额外的typemap。例如，Java模块就定义了一大堆typemap,用于控制Java绑定(binding)的各个方面。请参考各语言的特定文档了解细节。

11.1.6 Typemap不可以干什么？

Typemap不能用于给C/C++的声明定义属性(properties)。例如，比方说你有下面的声明：

Foo *make_Foo(int n);

你想告诉SWIGmake_Foo(int n)要返回一个新的分配对象（可能是为了提供更好的内存分配策略）。显然make_Foo(int n)不是类型Foo *关联的属性。因此，如果想达到这样的目的，需要使用SWIG提供的另外自定义机制(%feature)。请查看自定义属性章节连接详情。

Typemap也不能用于重新组织或装换参数的顺序。例如，你有如下的函数：

void foo(int, char *);

你不能使用typemap来交换参数，达到如下的目的：

foo("hello",3) # Reversed arguments

如果你想更改函数的调用规则，可以像下面一样写一个帮助函数(helper function)：

%rename(foo) wrap_foo;
%inline %{
void wrap_foo(char *s, int x) {
    foo(x,s);
}
%}

11.1.7 面向切面编程的相似性

SWIG与面向切面编程（Aspect Oriented Programming）是相似的。Typemap中关于AOP术语可以表述如下：

横切关注点(cross-cutting concerns): 横切关注点就是typemap实现的功能模块，主要用于在目标语言和C/C++语言互相间列集类型。
增强(Advice,也叫通知): typemap的代码体，只要列集需要就会执行。
切点(Pointcut)：切点就是typemap生成的包装代码放置的位置。
切面(Aspect)：切面就是切点和增强的组合，因此每个typemap都是切面。

SWIG的%feature也可以看做是切面。像%exception这样的特征也具备横切关注点的特征，因为它也可以包装用于添加日志或异常处理的功能。

11.1.8 本章剩下内容要讲什么

本章剩下的内容会给像了解如何编写typemap的人们提供详细信息。这些信息对那些想给新的目标语言编写模块的人特别重要。高级用户可以使用这些信息编写应用特定的类型转换规则。

因为typemap与底层的C++类型系统严格绑定，接下来的章节假设你熟悉一下C++基础概念：值、指针、引用、数组、类型修饰符（如：const）、结构体、命名空间、模板以及内存分配。如果你不了解的话建议去看看Kernighan and Ritchie的《The C Programming Language》和Stroustrup的《The C++ Programming Language》。

11.1 介绍

11.1 介绍

11.1.1 类型转换(Type Conversion)

11.1.2 Typemaps

11.1.3 模式匹配(Pattern Matching)

11.1.4 重用typemap

11.1.5 使用typemap能干什么

11.1.6 Typemap不可以干什么？

11.1.7 面向切面编程的相似性

11.1.8 本章剩下内容要讲什么

results matching ""

No results matching ""