1 New Features and Important Changes, v1.3
3 Author(s) : David Beazley
9 This document briefly explains some of the most important changes made
10 since the release of SWIG1.1. The goal is to provide information for
11 people who want to upgrade an older SWIG interface to the new version.
13 Most changes pertain to the internal implementation of SWIG and the
14 organization of the core, parser, and language modules. As a SWIG
15 user, almost all of these changes are hidden from view except for a
16 few important cases where changes to the core have dramatically
17 altered SWIG's old behavior.
21 2.1 Variables of the form 'const type *' are no longer wrapped as
22 constants, but as C global variables. The earlier SWIG behavior
23 was incorrect due to Dave's misinterpretation of 'const' in the C
24 language specification.
26 If you have written an interface that expects to create
27 constants using 'const type *' you will need to rewrite those
28 specifications using a new %constant directive like this:
30 %constant(type *) name = value;
32 2.2 SWIG generally has better support for pointers, 'const',
33 arrays, and pointers to functions.
35 2.3 Typemaps are now applied to a more precisely defined set
36 of datatypes. For example, consider the following
43 In SWIG1.1, this typemap would get applied to 'foo *',
44 'foo &', 'foo []', 'foo[][]', and so forth.
46 In SWIG1.3, this typemap *only* gets applied to 'foo *' and
47 'const foo *'. It does *NOT* get mapped to the other
48 variants listed above.
50 2.4 Bug fix. SWIG now correctly handles typemaps of the form
56 2.5 The memberout typemap is no longer available and is withdrawn.
57 The old implementation was essentially useless because of the
58 way in which code was generated.
60 2.6 The memberin typemap is now inserted inline in the generated
61 wrapper code. This provides access to scripting-specific
62 variables in the wrapper function.
64 2.7 SWIG-1.3.10 features a total rewrite of the typemap system.
65 Typemaps now use a different variable naming scheme. Typemaps
66 for arguments look like this:
68 %typemap(in) sometype {
69 $1 = convert value ($input);
72 The variable $1 replaces $target and the variable $input replaces
75 For output values, typemaps look like this:
77 %typemap(out) sometype {
78 $result = create result ($1);
81 The variable $1 replaces $source and the variable $result replaces
84 See Doc/Manual/Typemaps.html for a full description of the new
87 2.8 Multi-argument typemaps are now supported. This solves a common
88 problem that occurs with functions like this
90 void foo(char *buffer, int len);
92 where you would like to make the two arguments operate as a single
93 object in the target language.
95 2.9 Types such as 'const int &', 'const double &', are passed as
96 values instead of pointers.
98 2.10 C++ namespaces are now supported.
103 SWIG no longer uses the functions SWIG_GetPtr() and SWIG_MakePtr() to
104 parse datatypes in wrapper code. This is because the type of a
105 pointer is no longer associated with a string, but with a special
106 "swig_type_info *" object. If you are not using typemaps, this change
107 should cause no noticable effects. However, if you have written
108 typemaps to handle pointers, here are the essential details:
110 3.1 Type name mangling is different in SWIG1.3. For a type of
111 "int **", SWIG1.1 used to produce a name of the form
112 "_int_pp". SWIG1.3 on the other hand, produces a name
113 of the form "_p_p_int". There are a number of reasons for
114 changing the format, but I'd rather not go into it here. You'll
115 just have to learn to live with it :-).
117 3.2 Types are described by a special "swig_type_info *" object. Everywhere
118 a string was used before, an object of this type will be used.
119 The "swig_type_info *" for a given type can always be obtained
120 using macros involving the mangled typename in 3.1. For example,
121 the type object of of 'int **' is 'SWIGTYPE_p_p_int'.
123 3.3 Instead of SWIG_GetPtr, a function of the following form is used:
125 int SWIG_ConvertPtr(ScriptObj *o, void **ptr, swig_type_info *ty, int flags);
127 Note: the function name may differ in certain implementations (read
128 the source). For example:
130 int SWIG_ConvertPtr(ScriptObj *o, void **ptr, SWIGTYPE_p_p_int,0);
132 Passing a value of '0' for the type will accept any pointer. This
133 works kind of like 'void *'. The flags argument is reserved for
136 3.4. To create a pointer object, one uses a function similar to
138 ScriptObj *SWIG_NewPointer(void *ptr, swig_type_info *ty, int flags);
140 It works in a similar manner:
142 p = SWIG_NewPointer(ptr, SWIGTYPE_p_p_int, 0);
144 You will have to read the source to get the exact function name
145 used. The flags argument is implementation specific and reserved
146 for future expansion.
148 3.5. If, for whatever reason, you need to obtain the 'swig_type_info *'
149 outside the context of a wrapper file, you can use the
150 SWIG_TypeQuery() function. For example:
152 swig_type_info *ty = SWIG_TypeQuery("int **");
154 this function returns an appropriate type_info structure or NULL
155 if no such type is registered.
157 3.6 SWIG does not generate swig_type_info structures for types that are
158 not actually used in an interface file. As a result, the type
159 checking tables for SWIG1.3 tend to be much smaller than for SWIG1.1.
161 *** Note: The old string-based type checking scheme is not going to
162 return to SWIG so do not ask for backwards compatibility. The new
163 scheme is substantially faster, it is less error-prone, it requires no
164 dynamic memory allocation, it works better with the runtime libraries,
165 and it is simpler to implement than the old string based approach.
167 4. Deprecated Features (incomplete list)
168 ----------------------------------------
170 4.1 Documentation system. The old documentation system has been removed
171 entirely. I expect it to return someday, but it will have a much
172 different form (probably influenced by XML).
174 4.2 The %val and %out directives. These directives used to attach
175 properties to function parameters such as
177 void foo(%val int *ptr);
179 The same effect can now be achieved with typemaps:
181 void foo(int *INPUT);
184 4.3 Extensions to the %module and %init directive are no longer
185 supported. For example:
187 %module example, foo, bar
189 This used to perform a special kind of multi-module
190 initialization for static linking. If you really
191 need to do this, you will have to manually insert
192 code into the module initialization function.
194 4.4 %ifdef, %ifndef, %endif, %if, %elif, %else directives are
195 withdrawn. SWIG now has a real preprocessor.
197 4.5 %checkout directive removed.
199 4.6 %except and %new are deprecated.
201 4.7 %readonly and %readwrite are deprecated. Use %immutable instead.
203 4.8 The %addmethods directive has been renamed to %extend.
205 5. Language specific changes
206 ----------------------------
208 5.1 Python shadow classes are much more efficient and pass the shadow objects
209 directly to the C wrappers.
211 5.2 Tcl code generation is substantially improved--especially for C++.
213 5.3 Tcl module can now link to global variables of any type.
215 5.4 Perl shadow classes improved and optimized somewhat.
217 5.5 The Guile module represents pointers as smobs. (They used to be
218 mangled into strings.) Memory leaks and type conversion bugs have been
219 fixed. The Guile module system, including dynamic loading, and
220 exceptions are supported. A typemap-driven procedure-documentation
221 system has been added (requires Guile 1.4). Procedures-with-setters
224 5.6 The Python module now automatically creates shadow class objects from the
225 C wrappers. This fixes a bunch of hard problems related to typemaps,
226 exception handling, and more.
231 6.1 Java module added
233 6.2 Ruby module added
235 6.3 Mzscheme module added.
237 6.4 Integrated preprocessor. You can now use C macros in SWIG interface files.
239 6.5 PHP module added.
241 6.6 %rename directive is greatly enhanced to deal with overloaded functions.
243 6.7 Support for simple templates
245 6.8 Support for overloaded operators.
247 6.9 %feature directive.
249 6.10 Ocaml module added.
251 6.11 XML module added.
253 6.12 CHICKEN module added.
255 6.13 C# module added.