diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html index ed5591da5..78c7036f2 100644 --- a/Doc/Manual/Typemaps.html +++ b/Doc/Manual/Typemaps.html @@ -364,7 +364,7 @@ int spam(foo::Number a, foo::Number b);

In this case, the typemap is still applied to the proper arguments even though typenames don't always match the text "int". This ability to track types is a critical part of SWIG--in fact, all -of the target language modules work merely define a set of typemaps for the basic types. Yet, it +of the target language modules work merely define a family of typemaps for the basic types. Yet, it is never necessary to write new typemaps for typenames introduced by typedef.

@@ -431,7 +431,8 @@ be copied and reused. One way to do this is to use assignment like this:

-A more general form of copying is found in the %apply directive like this: +There is a more powerful way to copy a family of typemaps though. +Consider the following family of two typemap methods, "in" and "out" for type int:

@@ -444,8 +445,29 @@ A more general form of copying is found in the %apply directive like th /* Return an integer value */ ... } + +
-/* Apply all of the integer typemaps to size_t */ +

+Each of the two typemap methods could be copied individually for type size_t as follows: +

+ +
+
+/* Apply all of the int typemaps to size_t */
+%typemap(in) size_t = int;   
+%typemap(out) size_t = int;   
+
+
+ +

+A more powerful form of copying is available from the %apply directive. +The code below is identical to the above: +

+ +
+
+/* Apply all of the int typemaps to size_t */
 %apply int { size_t };
@@ -916,32 +938,33 @@ The patterns for %apply follow the same rules as for %typemap.

-A typemap can be deleted by simply defining no code. For example: +A particular typemap can be deleted / cleared by simply defining no code. For example: 

-%typemap(in) int;               // Clears typemap for int
-%typemap(in) int, long, short;  // Clears typemap for int, long, short
+%typemap(in) int;                 // Clears the "in" typemap for int
+%typemap(in) int, long, short;    // Clears the "in" typemap for int, long, short
 %typemap(in) int *output;

-The %clear directive clears all typemaps for a given type. +The above syntax deletes a typemap for just one typemap method - the "in" method in each of the examples above. +The %clear directive is more powerful and will delete / clear a family of typemaps, that is, all the typemap methods for a given type. For example: 

-%clear int;                     // Removes all types for int
+%clear int;                       // Delete all typemaps ("in", "out", "varin", ...) for int
 %clear int *output, long *output;

Note: Since SWIG's default behavior is defined by typemaps, clearing a fundamental type like -int will make that type unusable unless you also define a new set of typemaps immediately +int will make that type unusable unless you also define a new family of typemaps immediately after the clear operation.

@@ -2506,7 +2529,7 @@ which then expands to:

-The set of typemaps recognized by a language module may vary. However, +The family of typemaps recognized by a language module may vary. However, the following typemap methods are nearly universal:

@@ -3284,7 +3307,7 @@ The example above also shows a common approach of issuing a warning for an as ye

The "out" typemap is the main typemap for return types. -This typemap supports an optional attribute flag called "optimal", which is for reducing +This typemap supports an optional attribute flag called "optimal", which is for reducing the number of temporary variables and the amount of generated code, thereby giving the compiler the opportunity to use return value optimization for generating faster executing code. It only really makes a difference when returning objects by value and has some limitations on usage, @@ -4899,8 +4922,8 @@ The 'equivalent' attribute is used in the implementation for the @@ -4916,7 +4939,7 @@ a set of typemaps like this:

To make it easier to apply the typemap to different argument types and names, the %apply directive -performs a copy of all typemaps from one type to another. For example, if you specify this, +performs a copy of all typemaps from a source type to one or more set of target types. For example, if you specify this,

@@ -4926,12 +4949,14 @@ performs a copy of all typemaps from one type to another. For example, if you s

-then all of the int *OUTPUT typemaps are copied to int *retvalue and int32 *output. +then all of the int *OUTPUT (source) typemap methods are copied to int *retvalue and int32 *output (the targets).

-However, there is a subtle aspect of %apply that needs more description. Namely, %apply does not -overwrite a typemap rule if it is already defined for the target datatype. This behavior allows you to do two things: +However, there is a subtle aspect of %apply that needs clarification. +Namely, if a target contains a typemap method that the source does not, +the target typemap method is not overwritten / deleted. +This behavior allows you to do two things:

@@ -4961,6 +4986,10 @@ For example: } } +%typemap(arginit) int *invalue %{ + $1 = NULL; +%} + ... %apply int *INPUT { int *invalue }; %apply int *POSITIVE { int *invalue }; @@ -4968,9 +4997,11 @@ For example:

-Since %apply does not overwrite or replace any existing rules, the only way to reset behavior is to -use the %clear directive. %clear removes all typemap rules defined for a specific datatype. For -example: +In this example, neither of the two %apply directives will overwrite / delete the "arginit" typemap as neither has an "arginit" typemap. +The result is a family of three relevant typemaps for int *invalue. +Since %apply does not overwrite / delete any existing rules, the only way to reset behavior is to +delete them, such as with the %clear directive. +For example:

@@ -4979,6 +5010,17 @@ example:
+

+will delete the typemaps for all the typemap methods; namely "in", "check" and "arginit". Alternatively delete each one individually: +

+ +
+
+%typemap(in) int *invalue;
+%typemap(check) int *invalue;
+%typemap(arginit) int *invalue;
+
+

12.15 Passing data between typemaps