In many cases, it is desirable to change the default wrapping of particular declarations in an interface. For example, you might want to provide hooks for catching C++ exceptions, add assertions, or provide hints to the underlying code generator. This chapter describes some of these customization techniques. First, a discussion of exception handling is presented. Then, a more general-purpose customization mechanism known as "features" is described.html
在许多状况下，用户但愿更改接口文件中特定声明的默认包装。例如，你可能想要提供钩子来捕获 C++ 异常，添加断言或为底层代码生成器提供提示。本章介绍其中一些自定义技术。首先，对异常处理进行了讨论。而后，描述了一种称为“功能”的，更通用的自定义机制。c++
%exception 处理异常The %exception directive allows you to define a general purpose exception handler. For example, you can specify the following:app
%exception指令容许你定义通用异常处理程序。例如，你能够指定如下内容：less
%exception {
try {
$action
}
catch (RangeError) {
... handle error ...
}
}
How the exception is handled depends on the target language, for example, Python:ide
异常的处理方式取决于目标语言，例如在 Python 中：函数
%exception {
try {
$action
}
catch (RangeError) {
PyErr_SetString(PyExc_IndexError, "index out-of-bounds");
SWIG_fail;
}
}
When defined, the code enclosed in braces is inserted directly into the low-level wrapper functions. The special variable $action is one of a few %exception special variables supported and gets replaced with the actual operation to be performed (a function call, method invocation, attribute access, etc.). An exception handler remains in effect until it is explicitly deleted. This is done by using either %exception or %noexception with no code. For example:flex
一旦定义，用大括号括起来的代码直接插入到低级包装器函数中。特殊变量
$action是受支持的少数%exception特殊变量之一，并被替换为要执行的实际操做（函数调用、方法调用、属性访问等）。异常处理程序将一直有效，直到被明确删除。这能够经过%exception或%noexception来完成，无须编写代码。例如：ui
%exception; // Deletes any previously defined handler
Compatibility note: Previous versions of SWIG used a special directive %except for exception handling. That directive is deprecated--%exception provides the same functionality, but is substantially more flexible.this
注意兼容性：早期版本的 SWIG 使用特殊指令
%except进行异常处理。该指令已被弃用——%exception提供相同的功能，但实质上更为灵活。idea
C has no formal exception handling mechanism so there are several approaches that might be used. A somewhat common technique is to simply set a special error code. For example:
C 没有正式的异常处理机制，所以可使用几种方法来实现。某种常见的技术是简单地设置特殊的错误代码。例如：
/* File : except.c */
static char error_message[256];
static int error_status = 0;
void throw_exception(char *msg) {
strncpy(error_message, msg, 256);
error_status = 1;
}
void clear_exception() {
error_status = 0;
}
char *check_exception() {
if (error_status)
return error_message;
else
return NULL;
}
To use these functions, functions simply call throw_exception() to indicate an error occurred. For example :
要使用这些函数，函数只需调用
throw_exception()来指示发生了错误。例如 ：
double inv(double x) {
if (x != 0)
return 1.0/x;
else {
throw_exception("Division by zero");
return 0;
}
}
To catch the exception, you can write a simple exception handler such as the following (shown for Perl5) :
要捕获异常，你能够编写一个简单的异常处理程序，例如如下代码（针对 Perl5）：
%exception {
char *err;
clear_exception();
$action
if ((err = check_exception())) {
croak(err);
}
}
In this case, when an error occurs, it is translated into a Perl error. Each target language has its own approach to creating a runtime error/exception in and for Perl it is the croak method shown above.
在这种状况下，一旦错误发生，它将转换为 Perl 错误。每种目标语言都有本身的方法来在其中建立运行时错误/异常，对于 Perl 来讲，这是上面显示的
croak方法。
longjmp() 处理异常Exception handling can also be added to C code using the <setjmp.h> library. Here is a minimalistic implementation that relies on the C preprocessor :
也可使用
<setjmp.h>库将异常处理添加到 C 代码中。这是一个依赖 C 预处理器的简约实现：
/* File : except.c Just the declaration of a few global variables we're going to use */ #include <setjmp.h> jmp_buf exception_buffer; int exception_status; /* File : except.h */ #include <setjmp.h> extern jmp_buf exception_buffer; extern int exception_status; #define try if ((exception_status = setjmp(exception_buffer)) == 0) #define catch(val) else if (exception_status == val) #define throw(val) longjmp(exception_buffer, val) #define finally else /* Exception codes */ #define RangeError 1 #define DivisionByZero 2 #define OutOfMemory 3
Now, within a C program, you can do the following :
如今，在 C 程序中，你能够这样作：
double inv(double x) {
if (x)
return 1.0/x;
else
throw(DivisionByZero);
}
Finally, to create a SWIG exception handler, write the following :
最终，以下能够建立一个 SWIG 异常处理器：
%{
#include "except.h"
%}
%exception {
try {
$action
} catch(RangeError) {
croak("Range Error");
} catch(DivisionByZero) {
croak("Division by zero");
} catch(OutOfMemory) {
croak("Out of memory");
} finally {
croak("Unknown exception");
}
}
Note: This implementation is only intended to illustrate the general idea. To make it work better, you'll need to modify it to handle nested try declarations.
注意：此实现仅用于说明通常想法。为了使其更好地工做，你须要对其进行修改以处理嵌套的
try声明。
Handling C++ exceptions is also straightforward. For example:
处理 C++ 异常也很简单。例如：
%exception {
try {
$action
} catch(RangeError) {
croak("Range Error");
} catch(DivisionByZero) {
croak("Division by zero");
} catch(OutOfMemory) {
croak("Out of memory");
} catch(...) {
croak("Unknown exception");
}
}
The exception types need to be declared as classes elsewhere, possibly in a header file :
异常类型须要在其余地方声明为类，多是在头文件中：
class RangeError {};
class DivisionByZero {};
class OutOfMemory {};
By default all variables will ignore %exception, so it is effectively turned off for all variables wrappers. This applies to global variables, member variables and static member variables. The approach is certainly a logical one when wrapping variables in C. However, in C++, it is quite possible for an exception to be thrown while the variable is being assigned. To ensure %exception is used when wrapping variables, it needs to be 'turned on' using the %allowexception feature. Note that %allowexception is just a macro for %feature("allowexcept"), that is, it is a feature called allowexcept. Any variable which has this feature attached to it, will then use the %exception feature, but of course, only if there is a %exception attached to the variable in the first place. The %allowexception feature works like any other feature and so can be used globally or for selective variables.
默认状况下，全部变量都将忽略
%exception，所以对于全部变量包装器均将其关闭。这适用于全局变量、成员变量和静态成员变量。在用 C 包装变量时，这种方法固然是合乎逻辑的。可是，在 C++ 中，极可能在分配变量时引起异常。为了确保在包装变量时使用%exception，须要使用%allowexception功能将其turned on。请注意，%allowexception只是%feature("allowexcept")的宏，也就是说，它是一个名为allowexcept的功能。任何具备此功能的变量都将使用%exception功能，可是，前提固然是首先要在变量上附加%exception。%allowexception功能与任何其余功能同样工做，所以能够全局使用或用于选择性变量。
%allowexception; // turn on globally %allowexception Klass::MyVar; // turn on for a specific variable %noallowexception Klass::MyVar; // turn off for a specific variable %noallowexception; // turn off globally
By default, the %exception directive creates an exception handler that is used for all wrapper functions that follow it. Unless there is a well-defined (and simple) error handling mechanism in place, defining one universal exception handler may be unwieldy and result in excessive code bloat since the handler is inlined into each wrapper function.
To fix this, you can be more selective about how you use the %exception directive. One approach is to only place it around critical pieces of code. For example:
默认状况下，
%exception指令建立一个异常处理程序，该异常处理程序用于其后的全部包装函数。除非有一个定义明确（且简单）的错误处理机制，不然定义一个通用异常处理程序可能会很麻烦，而且因为该处理程序被内联到每一个包装器函数中，所以会致使代码过于膨胀。为了解决这个问题，你能够更具选择性地使用
%exception指令。一种方法是仅将其放置在关键的代码周围。例如：
%exception {
... your exception handler ...
}
/* Define critical operations that can throw exceptions here */
%exception;
/* Define non-critical operations that don't throw exceptions */
More precise control over exception handling can be obtained by attaching an exception handler to specific declaration name. For example:
经过将异常处理程序附加到特定的声明名称，能够得到对异常处理更精确的控制。例如：
%exception allocate {
try {
$action
}
catch (MemoryError) {
croak("Out of memory");
}
}
In this case, the exception handler is only attached to declarations named allocate. This would include both global and member functions. The names supplied to %exception follow the same rules as for %rename described in the section on Ambiguity resolution and renaming. For example, if you wanted to define an exception handler for a specific class, you might write this:
在这种状况下，异常处理程序仅附加到名为
allocate的声明。这将包括全局和成员函数。提供给%exception的名称遵循与消歧义和重命名一节中所述的%rename相同的规则。例如，若是你想为特定的类定义异常处理程序，则能够这样编写：
%exception Object::allocate {
try {
$action
}
catch (MemoryError) {
croak("Out of memory");
}
}
When a class prefix is supplied, the exception handler is applied to the corresponding declaration in the specified class as well as for identically named functions appearing in derived classes.
%exception can even be used to pinpoint a precise declaration when overloading is used. For example:
提供类前缀时，异常处理程序将应用于指定类中的相应声明，以及派生类中出现的名称相同的函数。
使用重载时，甚至可使用
%exception来精肯定位声明。例如：
%exception Object::allocate(int) {
try {
$action
}
catch (MemoryError) {
croak("Out of memory");
}
}
Attaching exceptions to specific declarations is a good way to reduce code bloat. It can also be a useful way to attach exceptions to specific parts of a header file. For example:
将异常附加到特定声明是减小代码膨胀的好方法。将异常附加到头文件的特定部分也是一种有用的方法。例如：
%module example
%{
#include "someheader.h"
%}
// Define a few exception handlers for specific declarations
%exception Object::allocate(int) {
try {
$action
}
catch (MemoryError) {
croak("Out of memory");
}
}
%exception Object::getitem {
try {
$action
}
catch (RangeError) {
croak("Index out of range");
}
}
...
// Read a raw header file
%include "someheader.h"
Compatibility note: The %exception directive replaces the functionality provided by the deprecated except typemap. The typemap would allow exceptions to be thrown in the target language based on the return type of a function and was intended to be a mechanism for pinpointing specific declarations. However, it never really worked that well and the new %exception directive is much better.
注意兼容性：
%exception指令替换了不推荐使用的except类型映射提供的功能。类型映射将容许根据函数的返回类型以目标语言抛出异常，而且该映射旨在成为一种精肯定位特定声明的机制。可是，它历来没有真正奏效过，新的%exception指令要好得多。
%exception 的特殊变量The %exception directive supports a few special variables which are placeholders for code substitution. The following table shows the available special variables and details what the special variables are replaced with.
%exception指令支持一些特殊变量，它们是代码替换的占位符。下表显示了可用的特殊变量，并详细说明了用哪些特殊变量替换的变量。
$action |
The actual operation to be performed (a function call, method invocation, variable access, etc.) |
|---|---|
$name |
The C/C++ symbol name for the function. |
$symname |
The symbol name used internally by SWIG |
$overname |
The extra mangling used in the symbol name for overloaded method. Expands to nothing if the wrapped method is not overloaded. |
$wrapname |
The language specific wrapper name (usually a C function name exported from the shared object/dll) |
$decl |
The fully qualified C/C++ declaration of the method being wrapped without the return type |
$fulldecl |
The fully qualified C/C++ declaration of the method being wrapped including the return type |
$parentclassname |
The parent class name (if any) for a method. |
$parentclasssymname |
The target language parent class name (if any) for a method. |
The special variables are often used in situations where method calls are logged. Exactly which form of the method call needs logging is up to individual requirements, but the example code below shows all the possible expansions, plus how an exception message could be tailored to show the C++ method declaration:
特殊变量一般用于记录方法调用的状况。究竟哪一种形式的方法调用须要记录取决于我的要求，可是下面的示例代码显示了全部可能的扩展，以及如何定制异常消息以显示 C++ 方法声明：
%exception Special::something {
log("symname: $symname");
log("overname: $overname");
log("wrapname: $wrapname");
log("decl: $decl");
log("fulldecl: $fulldecl");
try {
$action
}
catch (MemoryError) {
croak("Out of memory in $decl");
}
}
void log(const char *message);
struct Special {
void something(const char *c);
void something(int i);
};
Below shows the expansions for the 1st of the overloaded something wrapper methods for Perl:
下面显示了 Perl 重载的
something包装器方法的第一种扩展：
log("symname: Special_something");
log("overname: __SWIG_0");
log("wrapname: _wrap_Special_something__SWIG_0");
log("decl: Special::something(char const *)");
log("fulldecl: void Special::something(char const *)");
try {
(arg1)->something((char const *)arg2);
}
catch (MemoryError) {
croak("Out of memory in Special::something(char const *)");
}
The exception.i library file provides support for creating language independent exceptions in your interfaces. To use it, simply put an "%include exception.i" in your interface file. This provides a function SWIG_exception() that can be used to raise common scripting language exceptions in a portable manner. For example :
exception.i库文件支持在接口文件中建立独立于语言的异常。要使用它，只需在接口文件中引入%include exception.i。这提供了一个函数SWIG_exception()，该函数可用于以可移植的方式引起常见的脚本语言异常。例如 ：
// Language independent exception handler
%include exception.i
%exception {
try {
$action
} catch(RangeError) {
SWIG_exception(SWIG_ValueError, "Range Error");
} catch(DivisionByZero) {
SWIG_exception(SWIG_DivisionByZero, "Division by zero");
} catch(OutOfMemory) {
SWIG_exception(SWIG_MemoryError, "Out of memory");
} catch(...) {
SWIG_exception(SWIG_RuntimeError, "Unknown exception");
}
}
As arguments, SWIG_exception() takes an error type code (an integer) and an error message string. The currently supported error types are :
做为参数，
SWIG_exception()采用错误类型代码（整数）和错误消息字符串。当前支持的错误类型是：
SWIG_UnknownError SWIG_IOError SWIG_RuntimeError SWIG_IndexError SWIG_TypeError SWIG_DivisionByZero SWIG_OverflowError SWIG_SyntaxError SWIG_ValueError SWIG_SystemError SWIG_AttributeError SWIG_MemoryError SWIG_NullReferenceError
The SWIG_exception() function can also be used in typemaps.
SWIG_exception()函数也能够用于类型映射。
%newobjectA common problem in some applications is managing proper ownership of objects. For example, consider a function like this:
在某些应用程序中，一个常见的问题是正确地管理对象的全部权。例如，考虑以下函数：
Foo *blah() {
Foo *f = new Foo();
return f;
}
If you wrap the function blah(), SWIG has no idea that the return value is a newly allocated object. As a result, the resulting extension module may produce a memory leak (SWIG is conservative and will never delete objects unless it knows for certain that the returned object was newly created).
To fix this, you can provide an extra hint to the code generator using the %newobject directive. For example:
若是包装函数
blah()，SWIG 不知道返回值是新分配的对象。结果，生成的扩展模块可能会产生内存泄漏（SWIG 是保守的，除非肯定能够确定返回的对象是新建立的，不然从不删除对象）。为了解决这个问题，你可使用
%newobject指令为代码生成器提供额外的提示。例如：
%newobject blah; Foo *blah();
%newobject works exactly like %rename and %exception. In other words, you can attach it to class members and parameterized declarations as before. For example:
%newobject的工做方式与%rename和%exception彻底相同。换句话说，你能够像之前同样将其附加到类成员和参数化声明中。例如：
%newobject ::blah(); // Only applies to global blah %newobject Object::blah(int, double); // Only blah(int, double) in Object %newobject *::copy; // Copy method in all classes ...
When %newobject is supplied, many language modules will arrange to take ownership of the return value. This allows the value to be automatically garbage-collected when it is no longer in use. However, this depends entirely on the target language (a language module may also choose to ignore the %newobject directive).
Closely related to %newobject is a special typemap. The newfree typemap can be used to deallocate a newly allocated return value. It is only available on methods for which %newobject has been applied and is commonly used to clean-up string results. For example:
当提供
%newobject时，许多语言模块将安排获取返回值的全部权。这样就能够在再也不使用该值时自动对其进行垃圾回收。可是，这彻底取决于目标语言（语言模块也能够选择忽略%newobject指令）。与
%newobject密切相关的是一个特殊的类型映射。newfree类型映射可用于释放新分配的返回值。它仅在应用了%newobject的方法上可用，而且一般用于清理字符串结果。例如：
%typemap(newfree) char * "free($1);"; ... %newobject strdup; ... char *strdup(const char *s);
In this case, the result of the function is a string in the target language. Since this string is a copy of the original result, the data returned by strdup() is no longer needed. The "newfree" typemap in the example simply releases this memory.
As a complement to the %newobject, from SWIG 1.3.28, you can use the %delobject directive. For example, if you have two methods, one to create objects and one to destroy them, you can use:
在这种状况下，函数的结果是目标语言中的字符串。因为该字符串是原始结果的副本，所以再也不须要
strdup()返回的数据。示例中的newfree类型映射仅释放该内存。做为对 SWIG 1.3.28 中
%newobject的补充，你可使用%delobject指令。例如，若是你有两种方法，一种用于建立对象，另外一种用于销毁它们，则可使用：
%newobject create_foo; %delobject destroy_foo; ... Foo *create_foo(); void destroy_foo(Foo *foo);
or in a member method as:
或者在成员方法中做为：
%delobject Foo::destroy;
class Foo {
public:
void destroy() { delete this;}
private:
~Foo();
};
%delobject instructs SWIG that the first argument passed to the method will be destroyed, and therefore, the target language should not attempt to deallocate it twice. This is similar to use the DISOWN typemap in the first method argument, and in fact, it also depends on the target language on implementing the 'disown' mechanism properly.
The use of %newobject is also integrated with reference counting and is covered in the C++ reference counted objects section.
Compatibility note: Previous versions of SWIG had a special %new directive. However, unlike %newobject, it only applied to the next declaration. For example:
%delobject指示 SWIG 传递给该方法的第一个参数将被销毁，所以，目标语言不该尝试对其进行两次分配。这相似于在第一个方法参数中使用DISOWN类型映射，实际上，它还取决于目标语言是否正确实现了disown机制。
%newobject的使用也与引用计数集成在一块儿，并在 C++ 引用计数对象章节中进行了介绍。注意兼容性：早期版本的 SWIG 具备特殊的
%new指令。可是，与%newobject不一样，它仅适用于下一个声明。例如：
%new char *strdup(const char *s);
For now this is still supported but is deprecated.
How to shoot yourself in the foot: The %newobject directive is not a declaration modifier like the old%new directive. Don't write code like this:
目前，仍支持此功能，但已弃用。
如何射击本身的脚：
%newobject指令与旧的%new指令不一样，它不是一个声明修饰符。不要写这样的代码：
%newobject char *strdup(const char *s);
The results might not be what you expect.
结果可能不是你所指望的。
%feature 指令Both %exception and %newobject are examples of a more general purpose customization mechanism known as "features." A feature is simply a user-definable property that is attached to specific declarations. Features are attached using the %feature directive. For example:
%exception和%newobject都是更通用的自定义机制（称为“功能”）的示例。功能只是附加到特定声明的用户可定义的属性。功能使用%feature指令附加。例如：
%feature("except") Object::allocate {
try {
$action
}
catch (MemoryError) {
croak("Out of memory");
}
}
%feature("new", "1") *::copy;
In fact, the %exception and %newobject directives are really nothing more than macros involving %feature:
实际上
%exception和%newobject就是包含%feature的宏：
#define %exception %feature("except")
#define %newobject %feature("new", "1")
The name matching rules outlined in the Ambiguity resolution and renaming section applies to all %feature directives. In fact the %rename directive is just a special form of %feature. The matching rules mean that features are very flexible and can be applied with pinpoint accuracy to specific declarations if needed. Additionally, if no declaration name is given, a global feature is said to be defined. This feature is then attached to every declaration that follows. This is how global exception handlers are defined. For example:
消歧义析和重命名章节中概述的名称匹配规则适用于全部
%feature指令。实际上，%rename指令只是%feature的一种特殊形式。匹配规则意味着功能很是灵活，若是须要，能够精确地将其应用于特定声明。此外，若是未给出声明名称，则称已定义了全局功能。而后，此功能将附加到随后的每一个声明。这就是定义全局异常处理程序的方式。例如：
/* Define a global exception handler */
%feature("except") {
try {
$action
}
...
}
... bunch of declarations ...
The %feature directive can be used with different syntax. The following are all equivalent:
%feature指令有不一样的语法。如下都是等价的：
%feature("except") Object::method { $action };
%feature("except") Object::method %{ $action %};
%feature("except") Object::method " $action ";
%feature("except", "$action") Object::method;
The syntax in the first variation will generate the { } delimiters used whereas the other variations will not.
第一个变体中的语法将生成使用的
{ }分隔符，而其余变体则不。
The %feature directive also accepts XML style attributes in the same way that typemaps do. Any number of attributes can be specified. The following is the generic syntax for features:
%feature指令也以与类型映射相同的方式接受 XML 样式的属性。能够指定任意数量的属性。如下是功能的通用语法：
%feature("name", "value", attribute1="AttributeValue1") symbol;
%feature("name", attribute1="AttributeValue1") symbol {value};
%feature("name", attribute1="AttributeValue1") symbol %{value%};
%feature("name", attribute1="AttributeValue1") symbol "value";
More than one attribute can be specified using a comma separated list. The Java module is an example that uses attributes in %feature("except"). The throws attribute specifies the name of a Java class to add to a proxy method's throws clause. In the following example, MyExceptionClass is the name of the Java class for adding to the throws clause.
可使用逗号分隔的列表来指定多个属性。Java 模块是使用
%feature("except")中的属性的示例。throws属性指定要添加到代理方法throw子句中 Java 类的名称。在下面的示例中，MyExceptionClass是要添加到throw子句中的 Java 类的名称。
%feature("except", throws="MyExceptionClass") Object::method {
try {
$action
} catch (...) {
... code to throw a MyExceptionClass Java exception ...
}
};
Further details can be obtained from the Java exception handling section.
更多细节能够从 Java 异常处理章节得到。
Feature flags are used to enable or disable a particular feature. Feature flags are a common but simple usage of %feature and the feature value should be either 1 to enable or 0 to disable the feature.
功能标志用于启用或禁用特定功能。功能标志是
%feature常见但简单的用法，值应为1则启用，为0则禁用功能。
%feature("featurename") // enables feature
%feature("featurename", "1") // enables feature
%feature("featurename", "x") // enables feature
%feature("featurename", "0") // disables feature
%feature("featurename", "") // clears feature
Actually any value other than zero will enable the feature. Note that if the value is omitted completely, the default value becomes 1, thereby enabling the feature. A feature is cleared by specifying no value, see Clearing features. The %immutable directive described in the Creating read-only variables section, is just a macro for %feature("immutable"), and can be used to demonstrates feature flags:
实际上，除
0之外的任何值都将启用该功能。请注意，若是该值被彻底省略，则默认值为1，从而启用该功能。经过不指定任何值来清除功能，请参阅清除功能章节。在建立只读变量章节中描述的%immutable指令只是%feature("immutable")的宏，能够用来演示功能标记：
// features are disabled by default
int red; // mutable
%feature("immutable"); // global enable
int orange; // immutable
%feature("immutable", "0"); // global disable
int yellow; // mutable
%feature("immutable", "1"); // another form of global enable
int green; // immutable
%feature("immutable", ""); // clears the global feature
int blue; // mutable
Note that features are disabled by default and must be explicitly enabled either globally or by specifying a targeted declaration. The above intersperses SWIG directives with C code. Of course you can target features explicitly, so the above could also be rewritten as:
请注意，默认状况下禁用功能，必须在全局范围内或经过指定目标声明来显式启用功能。上面的代码将 SWIG 指令插入 C 代码中。固然，你能够明确地定位功能，所以上面的内容也能够重写为：
%feature("immutable", "1") orange;
%feature("immutable", "1") green;
int red; // mutable
int orange; // immutable
int yellow; // mutable
int green; // immutable
int blue; // mutable
The above approach allows for the C declarations to be separated from the SWIG directives for when the C declarations are parsed from a C header file. The logic above can of course be inverted and rewritten as:
当从 C 头文件解析 C 声明时，上述方法容许将 C 声明与 SWIG 指令分开。上面的逻辑固然能够颠倒并重写为：
%feature("immutable", "1");
%feature("immutable", "0") red;
%feature("immutable", "0") yellow;
%feature("immutable", "0") blue;
int red; // mutable
int orange; // immutable
int yellow; // mutable
int green; // immutable
int blue; // mutable
As hinted above for %immutable, most feature flags can also be specified via alternative syntax. The alternative syntax is just a macro in the swig.swg Library file. The following shows the alternative syntax for the imaginary featurename feature:
就像上面对
%immutable的提示同样，大多数功能标志也能够经过其余语法来指定。替代语法只是swig.swg库文件中的宏。下面显示了虚构的featurename功能的替代语法：
%featurename // equivalent to %feature("featurename", "1") ie enables feature
%nofeaturename // equivalent to %feature("featurename", "0") ie disables feature
%clearfeaturename // equivalent to %feature("featurename", "") ie clears feature
The concept of clearing features is discussed next.
接下来介绍清除功能的概念。
A feature stays in effect until it is explicitly cleared. A feature is cleared by supplying a %feature directive with no value. For example %feature("name", ""). A cleared feature means that any feature exactly matching any previously defined feature is no longer used in the name matching rules. So if a feature is cleared, it might mean that another name matching rule will apply. To clarify, let's consider the except feature again (%exception):
在明确将其清除以前，功能一直有效。经过提供无值的
%feature指令能够清除功能。例如%feature("name", "")。清除的功能意味着名称匹配规则中再也不使用与先前定义的功能彻底匹配的任何功能。所以，若是一项功能被清除，则可能意味着将应用另外一个名称匹配规则。为了澄清，让咱们再次考虑except功能（%exception）：
// Define global exception handler
%feature("except") {
try {
$action
} catch (...) {
croak("Unknown C++ exception");
}
}
// Define exception handler for all clone methods to log the method calls
%feature("except") *::clone() {
try {
logger.info("$action");
$action
} catch (...) {
croak("Unknown C++ exception");
}
}
... initial set of class declarations with clone methods ...
// clear the previously defined feature
%feature("except", "") *::clone();
... final set of class declarations with clone methods ...
In the above scenario, the initial set of clone methods will log all method invocations from the target language. This specific feature is cleared for the final set of clone methods. However, these clone methods will still have an exception handler (without logging) as the next best feature match for them is the global exception handler.
Note that clearing a feature is not always the same as disabling it. Clearing the feature above with %feature("except", "") *::clone() is not the same as specifying %feature("except", "0") *::clone(). The former will disable the feature for clone methods - the feature is still a better match than the global feature. If on the other hand, no global exception handler had been defined at all, then clearing the feature would be the same as disabling it as no other feature would have matched.
Note that the feature must match exactly for it to be cleared by any previously defined feature. For example the following attempt to clear the initial feature will not work:
在上述状况下，初始的克隆方法将记录来自目标语言的全部方法调用。最后一组克隆方法将清除此特定功能。可是，这些克隆方法仍将具备异常处理程序（不进行日志记录），由于它们的下一个最佳功能匹配是全局异常处理程序。
请注意，清除功能并不老是与禁用功能相同。用
%feature("except", "0") *::clone()清除上面的功能与指定%feature("except", "0") *::clone()不一样。前者将禁用克隆方法的功能，该功能仍然比全局功能更好。另外一方面，若是根本没有定义全局异常处理程序，则清除该功能与禁用该功能相同，由于没有其余功能能够匹配。请注意，该功能必须彻底匹配才能被任何先前定义的功能清除。例如，如下清除初始功能的尝试将无效：
%feature("except") clone() { logger.info("$action"); $action }
%feature("except", "") *::clone();
but this will:
可是这能够：
%feature("except") clone() { logger.info("$action"); $action }
%feature("except", "") clone();
SWIG provides macros for disabling and clearing features. Many of these can be found in the swig.swglibrary file. The typical pattern is to define three macros; one to define the feature itself, one to disable the feature and one to clear the feature. The three macros below show this for the "except" feature:
SWIG 提供了用于禁用和清除功能的宏。其中许多能够在
swig.swg库文件中找到。典型的模式是定义三个宏。一种是定义功能自己，一种是禁用功能，另外一种是清除功能。下面的三个宏针对except功能显示了这一点：
#define %exception %feature("except")
#define %noexception %feature("except", "0")
#define %clearexception %feature("except", "")
SWIG treats methods with default arguments as separate overloaded methods as detailed in the default arguments section. Any %feature targeting a method with default arguments will apply to all the extra overloaded methods that SWIG generates if the default arguments are specified in the feature. If the default arguments are not specified in the feature, then the feature will match that exact wrapper method only and not the extra overloaded methods that SWIG generates. For example:
SWIG 将具备默认参数的方法视为单独的重载方法，如默认参数章节中所述。若是在功能中指定了默认参数，则以默认参数为目标的任何
%feature都将应用于 SWIG 生成的全部额外重载方法。若是未在功能中指定默认参数，则功能将仅与该彻底包装方法匹配，而不与 SWIG 生成的额外重载方法匹配。例如：
%feature("except") hello(int i=0, double d=0.0) { ... }
void hello(int i=0, double d=0.0);
will apply the feature to all three wrapper methods, that is:
将把功能应用于全部三个包装器方法，也就是：
void hello(int i, double d); void hello(int i); void hello();
If the default arguments are not specified in the feature:
若是功能中没有指定默认参数：
%feature("except") hello(int i, double d) { ... }
void hello(int i=0, double d=0.0);
then the feature will only apply to this wrapper method:
那么功能只应用这个包装器方法：
void hello(int i, double d);
and not these wrapper methods:
而不是这些方法：
void hello(int i); void hello();
If compactdefaultargs are being used, then the difference between specifying or not specifying default arguments in a feature is not applicable as just one wrapper is generated.
Compatibility note: The different behaviour of features specified with or without default arguments was introduced in SWIG-1.3.23 when the approach to wrapping methods with default arguments was changed.
若是使用
compactdefaultargs，则仅在生成一个包装器时，在功能中指定或不指定默认参数之间的区别不适用。注意兼容性：当更改使用默认参数包装方法的方法时，在 SWIG-1.3.23 中引入了使用或不使用默认参数指定的功能的不一样行为。
As has been shown earlier, the intended use for the %feature directive is as a highly flexible customization mechanism that can be used to annotate declarations with additional information for use by specific target language modules. Another example is in the Python module. You might use %featureto rewrite proxy/shadow class code as follows:
如前所述，
%feature指令的预期用途是一种高度灵活的自定义机制，可用于为声明加上附加信息以供特定目标语言模块使用。另外一个示例在 Python 模块中。你可使用%feature来重写代理/影子类代码，以下所示：
%module example
%rename(bar_id) bar(int, double);
// Rewrite bar() to allow some nice overloading
%feature("shadow") Foo::bar(int) %{
def bar(*args):
if len(args) == 3:
return apply(examplec.Foo_bar_id, args)
return apply(examplec.Foo_bar, args)
%}
class Foo {
public:
int bar(int x);
int bar(int x, double y);
}
Further details of %feature usage is described in the documentation for specific language modules.
%feature用法的更多详细信息在特定语言模块的文档中进行了描述。