C++0x/C++11 support for SWIG
+Summary
+This is a technical overview of the C++0x/C++11 support for the Swig. +This area of Swig is a work in progress. Initial C++0x/C++11 support for +Swig was written during the Google Summer of Code 2009 period by +Matevž Jekovec.
+SVN branch
+branches/gsoc2009-matevz
+New C++11 features status
+Wikipedia article: http://en.wikipedia.org/wiki/C%2B%2B0x +
+Rvalue reference and move semantics [done]
+The Rvalues are used in practice to speed up the move operations +on different containers.
+In the following example, we want to swap the given elements:
+template <class T> swap(T& a, T& b) {
+ T tmp(a); // now we have two copies of a
+ a = b; // now we have two copies of b
+ b = tmp; // now we have two copies of tmp (aka a)
+}+This can now be solved using the new function std::move():
+template <class T> swap(T& a, T& b) {
+ T tmp(std::move(a));
+ a = std::move(b);
+ b = std::move(tmp);
+}+For the move function to take effect, user needs to reimplement the +move constructor (taking ClassType&& as an argument) and +operator=(ClassType&&):
+class MyClass {
+ MyClass(MyClass&& p) : ptr(p.ptr) {p.ptr = 0;}
+ MyClass& operator=(MyClass&& p) {
+ std::swap(ptr, p.ptr);
+ return *this;
+ }
+};+In practice, the Rvalues are used for temporaries (when passing the +result of one function as an argument to another).
+Done: Added type&& to Swig parser. Added testcase +cpp11_rvalue_reference.i. Operator && is treated the same as +operator &. R11450
+Article: +http://www.artima.com/cppsource/rvalue.html
+Generalized constant expressions [done]
+In C++11 you can define functions as constant expressions. +Functions need to return constant value in form "return expr", +where expr is a constant expression. +
+A keyword "constexpr" is introduced for this. eg.: +constexpr int getNumber() { return 5; } const int MY_CONSTANT = +getNumber(); +
+Constants are treated as normal variables in interpreted languages +because they are not compiled into the executable. Java "final" +constants are defined runtime as well. C++ constants need to be +declared in the header file and defined in the implementation file, +so swig doesn't need to know about the constant values when parsing +the header file. +
+Done: Added the “constexpr “ keyword to Swig. Added testcase +cpp11_constexpr. R11322
+Problem: No compilers were known to support constexpr yet, so the +testcase was temporarily commented out in common.mk. +
+Extern template [done]
+Extern template forces the GCC compiler to not instantiate the +template in the translation unit at that time. It's a feature +specifically aimed at compilers to speed up the compilation process. +
+Done: Added support for 'extern template class +std::vector<MyClass>;'. Added testcase cpp11_template_explicit. +R11385 , R11386
+Initializer lists [done]
+Initializer list is a new type in standard library: +std::initializer_list<T>. New symbols {} are introduced for the +initializer lists. +
+One can now use: +
+ class A {
+ public:
+ A( std::initializer_list<int> );
+ };
+ A a1 = {1,2,3,4};+Languages like Java, C# and Python already support direct creation of +lists natively.
+Problem: initializer_list cannot be treated as an ordinary list. +The constructor containing initializer_list can only be accessed by +assigning the value using the {} brackets. I also don't think there +is a simple way to convert an ordinary list or a vector to the +initializer_list.
+Done: Ignored the constructor having initializer_list as its +argument. Show warning to the user. Added testcase +cpp11_initializer_list. R11450
+Article: +http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1919.pdf
+Uniform initialization [done]
+The new C++11 standard will allow the following:
+struct IdString {
+ std::string name;
+ int identifier;
+};
+
+IdString GetString() {
+ return {"SomeName", 4}; //Note the lack of explicit type.
+}+The feature works exactly as it did now for POD types only (eg. int +a[] = {1,2,3};). The following declarations are the same in the new +C++11:
+IdString str1 = {„SomeName“, 4};
+IdString str2{„SomeName“, 4};+The new way of using uniform initialization allows the following:
+struct BasicStruct {
+ int x;
+ double y;
+};
+
+struct AltStruct {
+ AltStruct(int x, double y) : x_{x}, y_{y} {}
+
+private:
+ int x_;
+ double y_;
+};
+
+BasicStruct var1{5, 3.2}; // only fills the struct components
+AltStruct var2{2, 4.3}; // calls the constructor+The new syntax is specific to C++. Java, C# and scripting languages +do not support this behaviour, but always need constructors. They +support {} brackets for declaration of arrays as C does + they add +support for creation of arrays on-the-fly (what C++11 introduced with +this feature and more).
+Done: Added syntax for {} member initialization in class +constructor. Added testcase cpp11_uniform_initialization. R11413
+Type inference [partially done]
+A new keyword 'auto' is introduced in C++11:
+auto a1 = 100; +auto a2 = myFunc();
+The type of a1 and a2 is automatically determined according to the +initialization value during the semantic phase of the compiler.
+Another macro 'decltype()' is introduced. The macro takes the +concrete object as an argument and returns its type. User could use +this as:
+int i = 100; +decltype(i) j = 200; // decltype(i) = int
+Calling operators are allowed as well:
+decltype(i+j) k = 300;
+Done: Added support for decltype() syntax. Test cases for normal +decltype members and alternate function members work fine. Currently +only syntax in form decltype(variable name) work. No support for +custom expresions eg. decltype(i+j) yet. R11525
+TODO: William proposed to support the hidden variables as well +(ones not parsed by Swig and added to symbol table). This also allows +Swig to parse custom expressions like decltype(i+j). The idea is to +introduce a new SwigType for this.
+Range-based for-loop [ignored]
+This feature is always present inside the implementation block +only. +
+Lambda functions and expressions [done]
+C++11 introduces lambda functions defined as:
+[](int x, int y) -> int { return x + y; }+If the lambda function contains a single return statement only or the +function doesn't return any type, the return type '->' can be +omitted. Lambda functions are function objects.
+The following example prints the number of items stored in a list:
+std::vector<int> someList;
+int total = 0;
+std::for_each( someList.begin(), someList.end(), [&total](int x) {total += x} );
+std::cout << total;+Parameters inside the [] are the visible parameters of the lambda +functions. These can be & (references), = (copies), variable name +(variable copy), &variable name (variable reference) or this +(copy of the current object).
+Lambda functions can be stored using:
+auto myLambdaFunc = [this]() { this->SomePrivateMemberFunction() };+Proposal: Lambda functions are most commonly used inside the function +block to quickly define how the sort, find and similar functions +should work (the other way would be overriding a class – the Java +style). The latest GCC does not support lambda functions yet so it is +difficult to test the feature once implemented. I would implement the +syntax support for this feature, but produce no wrapper code. Lambda +functions still work inside the function block though.
+Article: +http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2550.pdf
+Done: Added syntax support for the lambda functions. Added +testcase cpp11_lambda_functions.i. R11491, R11492
+Alternate function syntax [done]
+The problem with decltype() is that the parameters need to be +defined before the decltype. The following syntax is not valid, +because lhs and rhs hasn't been defined at the time of decltype:
+template< typename LHS, typename RHS>
+ decltype(lhs+rhs) AddingFunc(const LHS &lhs, const RHS &rhs) {return lhs + rhs;} //Not legal C++11+The solution C++11 offers is the combination of the 'auto' keyword +before and '-> rettype' after the function declaration:
+template< typename LHS, typename RHS>
+ auto AddingFunc(const LHS &lhs, const RHS &rhs) -> decltype(lhs+rhs) {return lhs + rhs;}+The new syntax only makes the job for the C++ compilers easier when +parsing such functions. The new syntax can be used for ordinary +functions as well:
+struct SomeStruct {
+ auto FuncName(int x, int y) -> int;
+};
+
+auto SomeStruct::FuncName(int x, int y) -> int {
+ return x + y;
+}+Done: Added support for the 'auto' return type. Added support for the +'-> type' after the funtion declaration. Added testcases +cpp11_alternate_function_syntax.i and +cpp11_alternate_function_syntax_runme.py. R11414
+Concepts, Axioms [ignored]
+In C++ there is a common problem when you use a template in the +class which doesn't support all the operations the functions in the +class actually do on the type. Compiler errors are usually very long +and unreadable. C++11 adds support for the "concepts". The +idea is to define what operations and attributes should the template +have. In contrast to class inheritance and polimorphism, all lookups +are done in compile-time. +
+Basic syntax (note LessThanComparable? +instead of "class" or "typename"): +
+template<LessThanComparable? T> + const T& min(const T &x, const T &y) { + return y < x ? y : x; + }
+Extended syntax (requires conditions are separated with &&, +|| or !): +
+template< typename T> requires LessThanComparable?<T> + const T& min(const T &x, const T &y) { + return y < x ? y : x; + }
+Definition of the concepts: +
+concept LessThanComparable?< typename T > { + bool operator<(T,T); + requires GreaterThanComparable?<T>; + typename value_type; + typename reference; + };
+Concept maps allow usage of a specific type: +
+template< typename T> + concept_map InputIterator?<T*> { + typedef T value_type ; + typedef T& reference ; + typedef T* pointer ; + typedef std::ptrdiff_t difference_type ; + };
+Concept maps can act as mini-types, with function definitions and +other constructs commonly associated with classes: +
+ concept Stack< typename X> {
+ typename value_type;
+ void push(X&, const value_type&);
+ void pop(X&);
+ value_type top(const X&);
+ bool empty(const X&);
+ };
+ template< typename T>
+ concept_map Stack<std::vector<T> > {
+ typedef T value_type;
+ void push(std::vector<T>& v, const T& x) { v.push_back(x); }
+ void pop(std::vector<T>& v) { v.pop_back(); }
+ T top(const std::vector<T>& v) { return v.back(); }
+ bool empty(const std::vector<T>& v) { return v.empty(); }
+ };+Axioms are a facility pertaining to concepts supplied by C++11 to +express the semantic properties of concepts. For example, the concept +Semigroup can be defined with an axiom Associativity as: +
+concept Semigroup< typename Op, typename T> : CopyConstructible?<T> { + T operator()(Op, T, T); + axiom Associativity(Op op, T x, T y, T z) { + op(x, op(y, z)) == op(op(x, y), z); + } + };
+Axioms are more like hints to the compiler to speed-up the process of +compilation. +
+Ignored: Concepts and axioms were removed from the C++11 standard. +
+Object construction improvement [done]
+This feature allows classes constructors to call other +constructors with different arguments (similar to Java and C# +behaviour). +
+The syntax is as follows: +
+ class SomeType {
+ int number;
+ public:
+ SomeType(int newNumber) : number(newNumber) {}
+ SomeType() : SomeType(42) {}
+ };+Also when using the inheritance, the feature introduces inheritance +of all superclass constructors without being defined separately in +the inherited class: +
+ class BaseClass {
+ public:
+ BaseClass(int iValue);
+ };
+ class DerivedClass: public BaseClass {
+ public:
+ using BaseClass::BaseClass; // Adds DerivedClass(int) constructor
+ };+Swig already correctly parses and produces the correct wrapper for +the “using” keyword.
+Done: Added testcase cpp11_constructors.i which covers both +constructor delegation and constructor inheritance. R11532
+Problem: Constructor delegation and constructor inheritance is not +supported by any compiler yet, so it's impossible to try and test +this feature.
+Null pointer constant [done]
+nullptr is part of the standard library. +
+It's defined as typedef decltype(nullptr) nullptr_t; +
+nullptr_t is defined in <cstddef>. +
+As far as the C++ is compatible with 0 as the pointer value, swig +values will work for the C++. And the other way around, nullptr +behaves as the ordinary pointer (false, if empty, true, if not +empty), so it's ok for swig to compare it.
+Done: Written a testcase cpp11_null_pointer_constant.i and +cpp11_null_pointer_constant_runme.py to prove the nullptr +functionality. R11484
+Strongly typed enumerations [partially done]
+C++11 introduces a new syntax for strongly typed enum declaration: +
+ enum class Enumeration {
+ Val1,
+ Val2,
+ Val3 = 100,
+ Val4 /* = 101 */
+ };+Typing if (Val4 == 101) will result in compilation error. +
+The enum itself can now be explicitely of type int, long, unsigned +int etc.: +
+ enum class Enum2 : unsigned int {Val1, Val2};+And it can be forward declared as well: +
+enum Enum1; //Illegal in C++ and C++11; no size is explicitly specified. + enum Enum2 : unsigned int; //Legal in C++11. + enum class Enum3; //Legal in C++11, because enum class declarations have a default type of "int". + enum class Enum4: unsigned int; //Legal C++11. + enum Enum2 : unsigned short; //Illegal in C++11, because Enum2 was previously declared with a different type.
+Done: Added syntax 'enum class Name' and forward declarators 'enum +Name : inherited type' or 'enum class Name : inherited type' in +R11449.
+TODO: Add semantic support for enum elements not clashing with +enum elements in other enum classes. See cpp11_strongly_typed_enums.i +warnings.
+Problem: Swig currently doesn't support nested classes. This +feature should be implemented using a new nested class when using +“enum class” with a single anonymous “enum {elements}” +element inside. For example:
+class A { enum class EA { a,b,c,d }; };+should be mapped to
+class A { class EA { enum {a,b,c,d}; }; };+Angle bracket [done]
+Support for right angled brackets was implemented using the +following article as a base: +http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html +
+Done: Added support for angle brackets. Used the preferred +"Approach 1". Added a testcase named +cpp11_template_double_brackets. R11245
+Explicit conversion operators [done]
+This is used when converting one type to another (eg. if +(myObject) {}, where myObject is your custom class converted to +bool). +
+Requires both operator and function overloading which is not +supported in any target language (eg. python, php). +
+Done: Swig already supports the keyword "explicit" for +function types as well. Added test case +cpp11_explicit_conversion_operators. R11323
+Template typedefs [partially done]
+The new C++11 will allow creation of wrapper around the template. +For example, if we want to do this:
+template< typename first, typename second, int third> +class SomeType; + +template< typename second> +typedef SomeType<OtherType, second, 5> TypedefName; //Illegal in C++
+This is still illegal! But we can now use the new syntax for +achieving the same effect:
+template< typename first, typename second, int third> +class SomeType; + +template< typename second> +using TypedefName = SomeType<OtherType, second, 5>;
+Here we created a new wrapper TypedefName taking one template +argument <second> which creates a type SomeType<OtherType, +second, 5>. OtherType and 5 are predefined here and hidden from +the user – the user only uses TypedefName type.
+The same goes for the following example:
+typedef void (*PFD)(double); // Old style +using PF = void (*)(double); // New introduced syntax
+Swig supports parsing typedefs for templates as well for example:
+typedef List<int> intList;
+Done: Expanded support for the new 'using' syntax and template +aliasing. Added testcase cpp11_template_typedefs. R11533
+TODO: Make Swig aware of the newly defined typedef. The TYPEDEF +keyword is part of the storage_class rule and type+declarator (see +c_decl rule) is the right part of the definition – for example void +(*PFD)(double) cannot be transformed to void *(double) easily. To +fully support the new 'using' form, we'll probably have to change the +type, type_right rules and declarator, direct_declarator, +notso_direct_declarator etc., which is PITA.
+Unrestricted unions [done]
+C++ currently offers usage of unions for types with trivial +constructors only. The new C++11 standard allows usage of types with +non-trivial constructors as well:
+ struct point {
+ point() {}
+ point(int x, int y): x_(x), y_(y) {}
+ int x_, y_;
+ };
+ union P {
+ int z;
+ double w;
+ point p; // Illegal in C++; point has a non-trivial constructor. However, this is legal in C++11.
+ } p1;+Swig already parses the given syntax.
+Done: Added testcase cpp11_unrestricted_unions. R11435, R11447
+Problem: GCC doesn't support unrestricted unions yet so there is +no way to actually test, if it works.
+Variadic templates [partially done]
+The new C++11 offers the following syntax:
+template<typename... Values> class tuple;
+This can be used for example:
+class tuple<int, std::vector<int>, std::map<std::string, std::vector<int>>> someInstanceName;
+The ... is used in two cases. One is in the template header where it +marks on the left the keywords 'typename' or 'class' and a type name +on the right. The second case is usually in the function block to +decompose typename on the left of the ... . For example:
+void printf(const char *s) {
+ while (*s) {
+ if (*s == '%' && *(++s) != '%')
+ throw std::runtime_error("invalid format string: missing arguments");
+ std::cout << *s++;
+ }
+}
+
+template<typename T, typename... Args>
+void printf(const char* s, T value, Args... args) { // recursive action – split previous args to value + args
+ while (*s) {
+ if (*s == '%' && *(++s) != '%') {
+ std::cout << value;
+ printf(*s ? ++s : s, args...); // call even when *s == 0 to detect extra arguments
+ return;
+ }
+ std::cout << *s++;
+ }
+ throw std::logic_error("extra arguments provided to printf");
+}+The tricky part is that variadic templates can unpack actually +anywhere – including the class inheritance :(
+template <typename... BaseClasses> class ClassName : public BaseClasses... {
+public:
+
+ ClassName (BaseClasses&&... baseClasses) : BaseClasses(baseClasses)... {}
+}+A new extension to sizeof is also introduced with this feature. The +... after sizeof returns number of arguments:
+template<typename ...Args> struct SomeStruct {
+ static const int size = sizeof...(Args);
+}
+// SomeStruct<Type1, Type2>::size is 2 and SomeStruct<>::size is 0+Done: Added syntax support for 'typename' or 'class' + ... + id. +Added testcase cpp11_variadic_templates. R11458
+Done: Added syntax support for BaseClass + ..., type + ... + id in +parameters and baseclass + ... for intializers after constructor. +Extended Swig syntax to support sizeof...(Args). R11467
+Done: Fixed %template to support variadic number of templates.
+TODO: Only (if present) first variadically defined argument is +currently used in %template directive. The next ones are ignored.
+New string literals [partially done]
+Beside the implementation, the new C++11 Unicode and custom +delimeter constants can occur in templates in the header file. +
+Done: Added symbols 'u', 'u8' and 'U' to mark the beginning of the +UTF string. Also added test case cpp11_raw_string_literals. R11327
+Done: Added R"DELIMITER[, ]DELIMITER" for a custom +delimiter for the beginning/end of the string. R11328
+TODO: Fix the Swig's C++ preprocessor bug when parsing an odd +number of “ inside the string brackets. See +Source/Preprocessor/cpp.c.
+User-defined literals [partially done]
+C++ has different suffix literals. eg. 12.5f marks the number 12.5 +as float. +
+C++11 allows user to define his own suffix for the strings always +starting with the underscore (_). eg. int a = "hello"_mySuffix; +
+The syntax is similar to other operator overloading functions: +
+OutputType operator "" _mySuffix(const char * string_values);
+The null terminated const char* is the string between the "". +The _mySuffix is the name of the suffix operator. And the OutputType +is the outputType the operator returns. +
+Other forms are: +
+OutputType operator "" _mySuffix(const char * string_values, size_t num_chars); + OutputType operator "" _mySuffix(const wchar_t * string_values, size_t num_chars); + OutputType operator "" _mySuffix(const char16_t * string_values, size_t num_chars); + OutputType operator "" _mySuffix(const char32_t * string_values, size_t num_chars); + OutputType operator "" _mySuffix(int value); /* cooked version - ie. atoi() of string */
+Another possibility is to use variadic templates: +
+template<char...> OutputType operator "" _mySuffix(); + OutputType someVariable = "1234"_mySuffix;
+This instantiates the literal processing function as +operator""_Suffix<'1', '2', '3', '4'>. In this form, +there is no terminating null character to the string. The main +purpose to doing this is to use C++11's constexpr keyword and the +compiler to allow the literal to be transformed entirely at compile +time, assuming OutputType is a constexpr-constructable and copyable +type, and the literal processing function is a constexpr function.
+Article: +http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf
+Done: Added syntax support for userdefined literals. Added +testcase cpp11_userdefined_literals.i. R11494
+TODO: %rename doesn't parse operator”” yet.
+Thread-local storage [done] +
+New C++11 introduces keyword "thread_local" which marks +the following variable dynamically located depending on the current +thread when using the address-of (&) operator. +
+Syntax: +
+ struct A {
+ thread_local int val;
+ };+Done: Add "thread_local" keyword to Swig. Added testcase +cpp11_thread_local. R11393
+Defaulting/deleting of standard functions on C++ objects [done]
+C++ automatically creates default constructor with empty +parameters, copy constructor, operator= and destructor for any class. +Sometimes user wants to explicitly remove one of them or enable them +(eg. default constructor with empty parameters doesn't work any more, +if any other constructor is defined). +
+Words "default" and "delete" are introduced. +The syntax is similar to declaration of pure virtual function: +
+ struct NonCopyable {
+ NonCopyable & operator=(const NonCopyable&) = delete; /* Removes operator= */
+ NonCopyable(const NonCopyable&) = delete; /* Removed copy constructor */
+ NonCopyable() = default; /* Explicitly allows the empty constructor */
+ void *operator new(std::size_t) = delete; /* Removes new NonCopyable */
+ };+User has the ability by using keyword delete to disallow calling of +the standard functions brought by C++ itself. +
+ struct A1 {
+ void f(int i);
+ void f(double i) = delete; /* Don't cast double to int. Compiler returns an error */
+ };
+ struct A2 {
+ void f(int i);
+ template<class T> void f(T) = delete; /* Only accept int */
+ };+Ignored: Swig already parses the keywords "= delete" and "= +default". These keywords are used for built-in functions (copy +constructor, operator= etc.), which are ignored by Swig anyway.
+Done: Added testcase cpp11_default_delete. R11535
+Type long long int [done]
+Type long long int is an integer type that has at least 64 useful +bits. C99 added it to its standard, but the C++ didn't adopt it until +C++11. Most C++ compilers supported it though. +
+Done: Swig already parses the C code including the long long type. +
+Static assertions [done]
+static_assert() can be used at class scope as well eg.: +
+ template <typename T>
+ struct Check {
+ static_assert(sizeof(int) <= sizeof(T), "not big enough");
+ };+Done: Added syntax support for "static_assert()". Added +test case cpp11_static_assert. R11369
+Allow sizeof to work on members of classes without an explicit +object [done]
+C++11 allows calls of sizeof to concrete objects as well: +
+ struct A { int member; };
+ sizeof(A::member); //Does not work with C++03. Okay with C++11+This kind of syntax is already supported by Swig.
+Done: Added testcase cpp11_sizeof_objects. R11538 +
+Threading facilities [ignored]
+C++11 will add the following classes to the standard library: +
+* std::thread + * std::mutex, std::recursive_mutex + * std::condition_variable, std::condition_variable_any + * std::lock_guard, std::unique_lock + * std::packaged_task
+Ignored: No changes to the language itself is made. +
+Tuple types [TODO]
+Tuple is array of various types. C++11 introduced this feature +using variadic templates. Tuple is defined as:
+template <class ...Types> class tuple;
+Constructor is automatically generated filling the tuple elements. +get<X> function is introduced to get the Xth element in the +tuple.
+typedef tuple< int, double, long &, const char * > test_tuple ; +long lengthy = 12 ; +test_tuple proof( 18, 6.5, lengthy, "Ciao!" ) ; +lengthy = get<0>(proof) ; // Assign to 'lengthy' the value 18. +get<3>(proof) = " Beautiful!" ; // Modify the tuple’s fourth element.
+Tuples can be copied to each other, if all the elements are copiable:
+typedef tuple< int , double, string > tuple_1 t1 ; +typedef tuple< char, short , const char * > tuple_2 t2( 'X', 2, "Hola!" ) ; +t1 = t2 ; // Ok, first two elements can be converted, + // the third one can be constructed from a 'const char *'.
+TODO: Implement wrappers for the tuplet<> class.
+Hash tables [TODO]
+C++11 introduces the "unordered" version of existing +types, which in practice work faster than the linear types: +
+- unordered set + - unordered multiset + - unordered map + - unordered multimap
+Swig should use the "unordered" types exactly the same as +the original linear types.
+Problem: Unordered types do not contain exactly same members as +ordered ones (eg. _Hashtable_iterator does not offer operator--() and +constructor with compare function which is required). So simply +aliasing unordered classes to ordered ones doesn't work.
+TODO: Implement wrappers for unordered_ types. Initial work is +already done in Lib/std/unordered_*.i files.
+Regular expressions [ignored]
+Two new classes are introduced in C++11: basic_regex and +match_results. Both are defined in regex header file. +
+Ignored: The new feature extends the standardy library only. No +changes to Swig needed. +
+General-purpose smart pointers [done]
+This feature deprecates auto_ptr and adds shared_ptr, weak_ptr and +unique_ptr to the standard library. +
+This feature only adds the smart pointers to the standard library +and doesn't effect the C++ syntax.
+Done: Added test case which uses all three smart pointers in the +class. R11394
+Problem: GCC standard library doesn't contain the new smart +pointers yet. +
+Extensible random number facility [ignored]
+This feature standardize the pseudo random number algorithm +(currently, the random number generator was dependent on the +platform/compiler). It adds functions linear_congruential, +subtract_with_carry and mersenne_twister and symbols +uniform_int_distribution, bernoulli_distribution, +geometric_distribution, poisson_distribution, binomial_distribution, +uniform_real_distribution, exponential_distribution, +normal_distribution and gamma_distribution to the standard library. +
+Ignored: The new feature extends the standardy library only. No +changes to Swig needed. +
+Wrapper reference [ignored]
+This feature adds ref and cref classes to the standard library +(#include <utility>) usually used in tempalte functions. +
+Ignored: The new feature extends the standardy library only. No +changes to Swig needed. +
+Polymorphous wrappers for function objects [done]
+Two features are introduced: +
+-
+
The function template wrapper: +
+
function<int ( int, int )> pF;+
-
+
and the function object: +
+
struct Test {
+ bool operator()( short x, short y );
+ };+Swig already supports the two.
+Done: Added a runtime testcase for function objects +cpp11_function_objects. R11419.
+Type traits for metaprogramming [ignored]
+C++11 adds a new header file <type_traits> which includes +helper functions to determine the template type while initializing +the object at compile time. +
+Swig already supports the following code: +
+ template< int B, int N >
+ struct Pow {
+ // recursive call and recombination.
+ enum{ value = B*Pow< B, N-1 >::value };
+ };
+ template< int B > struct Pow< B, 0 > // N == 0 condition of termination.
+ {
+ enum{ value = 1 };
+ };
+ int quartic_of_three = Pow< 3, 4 >::value ;+Functions is_convertible, is_integral, is_integral_const etc. are +part of the new header: +
+// First way of operating.
+template< bool B > struct algorithm {
+ template< class T1, class T2 > int do_it( T1 &, T2 & ) { /*...*/ }
+};
+// Second way of operating.
+template<> struct algorithm<true> {
+ template< class T1, class T2 > int do_it( T1, T2 ) { /*...*/ }
+};
+// Instantiating 'elaborate' will automatically instantiate the correct way to operate.
+template< class T1, class T2 > int elaborate( T1 A, T2 B ) {
+ // Use the second way only if 'T1' is an integer and if 'T2' is
+ // in floating point, otherwise use the first way.
+ return algorithm< is_integral<T1>::value && is_floating_point<T2>::value >::do_it( A, B );
+}+Swig correctly parses the syntax for template<bool>, +template<class T> and template<>. +
+Ignored: Swig requires explicitly defined template class +(%template directive) to export it to the target language.
+Uniform method for computing return type of function objects +[partially done]
+The template function is introduced: std::result_of() which +depends on decltype: +
+template< class Obj >
+class calculus_ver2 {
+ public:
+ template< class Arg >
+ typename std::result_of<Obj(Arg)>::type operator()( Arg& a ) const {
+ return member(a);
+ }
+ private:
+ Obj member;
+};+Swig correctly parses the result_of class.
+TODO: The return type (the result_of::type member) is not +calculated by Swig. This needs a much more complex semantic parser.
+Done: Added testcase cpp11_result_of. R11534
+ + diff --git a/Doc/Devel/engineering.html b/Doc/Devel/engineering.html index 2e78fbe35..c12eb1328 100644 --- a/Doc/Devel/engineering.html +++ b/Doc/Devel/engineering.html @@ -25,7 +25,7 @@-Each file should include a short abstract, license information and -a SVN revision tag like this: +Each file should include a short abstract and license information +like this:
-The SVN revision tag should be placed into a static string as shown -above mangled with the name of the file. -This adds the revision information to the SWIG executable and -makes it possible to extract version information from a raw binary -(sometimes useful in debugging). -@@ -137,8 +137,6 @@ a SVN revision tag like this: * This file defines ... * ----------------------------------------------------------------------------- */ -static char cvs[] = "$Id$"; - #include "swig.h" /* Declarations */ @@ -159,12 +157,6 @@ static int avariable;
As a general rule, files start to get unmanageable once they exceed
about 2000 lines. Files larger than this should be broken up into
@@ -379,10 +371,10 @@ making your changes.
These are largely covered in the main documentation in the Extending.html file.
-11. SVN Tagging Conventions
+11. Git Tagging Conventions
-Use svn tag to declare some set of file revisions as related in some
+Use git tag to declare some set of file revisions as related in some
symbolic way. This eases reference, retrieval and manipulation of these files
later. At the moment (2001/01/16 14:02:53), the conventions are very simple;
let's hope they stay that way!
@@ -390,10 +382,10 @@ let's hope they stay that way!
There are two types of tags, internal (aka personal) and external. Internal tags are used by SWIG developers primarily, whereas external -tags are used when communicating with people w/ anonymous svn access. +tags are used when communicating with people w/ anonymous git access.
- Internal tags should start with the developer name and a hyphen. -
- External tags should start with "v-". +
- External tags should start with "rel-".
diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html index d24869d10..c9082d3f6 100644 --- a/Doc/Devel/internals.html +++ b/Doc/Devel/internals.html @@ -42,6 +42,7 @@
@@ -843,7 +844,7 @@ Returns a type object corresponding to the type string produced by the Swig_clocchar *Swig_clocal_deref(DataType *t, char *name)
This function is the inverse of the clocal() function. Given a type and a name, it produces a string containing the code needed to cast/convert the type produced by -Swig_clocal() back into it's original type. +Swig_clocal() back into its original type.
char *Swig_clocal_assign(DataType *t, char *name) -
@@ -1179,6 +1180,34 @@ Either
+ +7.2 Debugging DOH memory allocation problems
+ + ++The DOH objects are reference counted and use pools for memory allocation. +The implementation is in memory.c. When there are memory corruption problems, +various memory allocator tools are normally used to diagnose problems. These can be used +on SWIG and can be very useful. However, they won't necessarily find use of stale DOH objects, +that is, DOH objects +that are used after they have been deleted. This is because the DOH memory allocator +grabs a chunk of memory from the C memory allocator and manages the usage internally. +Stale DOH object usage can be checked for by defining DOH_DEBUG_MEMORY_POOLS in +memory.c. If an attempt to use an object is made after the reference count is +zero, an assertion is triggered instead of quietly re-using the stale object... +
+ +++ ++swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed. +++This can be memory intensive as previously used memory in the pool is not re-used so is +only recommended for diagnosing memory corruption problems. +
+
Copyright (C) 1999-2010 SWIG Development Team. diff --git a/Doc/Devel/tree.html b/Doc/Devel/tree.html index db3c6fee4..73a49ed55 100644 --- a/Doc/Devel/tree.html +++ b/Doc/Devel/tree.html @@ -185,7 +185,7 @@ this function merely records that those attributes did not exist in the originalThis function is similar to Swig_save() except that adds additional attribute checking. There are different interpretations of the attribute names. A name of "attr" merely requests that the function check for the presence of an attribute. If the attribute is missing, SWIG will exit with a failed assertion. An attribute name of "?attr" specifies that the attribute "attr" is optional and -that it's old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that +that its old value must be saved (if any). An attribute name of "*attr" specifies that the attribute is required and that its value must be saved. The saving of attributes is performed in the same manner as with Swig_save(). Here is an example:diff --git a/Doc/Manual/Allegrocl.html b/Doc/Manual/Allegrocl.html index 5d00c4cd0..8295bad1c 100644 --- a/Doc/Manual/Allegrocl.html +++ b/Doc/Manual/Allegrocl.html @@ -8,7 +8,7 @@ --17 SWIG and Allegro Common Lisp
+18 SWIG and Allegro Common Lisp
-@@ -135,10 +135,10 @@ be unhappy to see some enterprising folk use this work to add to it. -
17.1 Basics
+18.1 Basics
-17.1.1 Running SWIG
+18.1.1 Running SWIG
@@ -360,7 +360,7 @@ need to link in the Allegro shared library. The library you create from the C++ wrapper will be what you then load into Allegro CL.
-17.1.2 Command Line Options
+18.1.2 Command Line Options
@@ -396,7 +396,7 @@ See Section 17.5 Identifier converter functions for more details.
-17.1.3 Inserting user code into generated files
+18.1.3 Inserting user code into generated files
@@ -436,7 +436,7 @@ Note that the block %{ ... %} is effectively a shortcut for
-17.2 Wrapping Overview
+18.2 Wrapping Overview
@@ -446,7 +446,7 @@ New users to SWIG are encouraged to read interested in generating an interface to C++.
-17.2.1 Function Wrapping
+18.2.1 Function Wrapping
@@ -499,7 +499,7 @@ interested in generating an interface to C++.
17.2.2 Foreign Wrappers
+18.2.2 Foreign Wrappers
@@ -512,7 +512,7 @@ interested in generating an interface to C++. typemap.
-17.2.3 FFI Wrappers
+18.2.3 FFI Wrappers
@@ -593,7 +593,7 @@ char *xxx(); ff:def-foreign-call's.
-17.2.4 Non-overloaded Defuns
+18.2.4 Non-overloaded Defuns
@@ -606,7 +606,7 @@ char *xxx(); this function can be manipulated via the lout typemap.
-17.2.5 Overloaded Defuns
+18.2.5 Overloaded Defuns
@@ -622,7 +622,7 @@ char *xxx(); can be manipulated via the lout typemap.
-17.2.6 What about constant and variable access?
+18.2.6 What about constant and variable access?
@@ -635,7 +635,7 @@ char *xxx(); into the foreign module.
-17.2.7 Object Wrapping
+18.2.7 Object Wrapping
@@ -657,7 +657,7 @@ char *xxx(); foreign function interface.
-17.3 Wrapping Details
+18.3 Wrapping Details
@@ -665,7 +665,7 @@ char *xxx(); translated into lisp.
-17.3.1 Namespaces
+18.3.1 Namespaces
@@ -742,13 +742,13 @@ namespace car { function such as (car '(1 2 3).
-17.3.2 Constants
+18.3.2 Constants
Constants, as declared by the preprocessor #define macro or SWIG - %constant directive, are included in SWIGs parse tree + %constant directive, are included in SWIG's parse tree when it can be determined that they are, or could be reduced to, a literal value. Such values are translated into defconstant forms in the generated lisp wrapper when the -nocwrap command-line @@ -803,7 +803,7 @@ namespace car { not use the -nocwrap command-line option.
-17.3.3 Variables
+18.3.3 Variables
@@ -881,13 +881,13 @@ globalvar> (globalvar.nnn::glob_float)
17.3.4 Enumerations
+18.3.4 Enumerations
In C, an enumeration value is an integer value, while in C++ an enumeration value is implicitly convertible to an integer value, - but can also be distinguished by it's enum type. For each enum + but can also be distinguished by its enum type. For each enum declaration a def-foreign-type is generated, assigning the enum a default type of :int. Users may adjust the foreign type of enums via SWIG typemaps. @@ -901,7 +901,7 @@ globalvar> (globalvar.nnn::glob_float) of it not being necessary to probe into foreign space to retrieve enum values. When generating a .cxx wrapper file, a more general solution is employed. A wrapper variable is created in the module_wrap.cxx file, and - a ff:def-foreign-variable call is generated to retrieve it's value into lisp. + a ff:def-foreign-variable call is generated to retrieve its value into lisp.
For example, the following header file @@ -957,7 +957,7 @@ EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3; -
17.3.5 Arrays
+18.3.5 Arrays
@@ -1105,10 +1105,10 @@ namespace BAR { -
17.3.6 Classes and Structs and Unions (oh my!)
+18.3.6 Classes and Structs and Unions (oh my!)
-17.3.6.1 CLOS wrapping of
+18.3.6.1 CLOS wrapping of
@@ -1118,12 +1118,12 @@ namespace BAR { function that returns an object (or pointer/reference) of C/C++ type X, the wrapping defun (or defmethod) on the Lisp side will automatically wrap the pointer returned in an instance - of the apropriate class. This makes it much easier to write and + of the appropriate class. This makes it much easier to write and debug code than if pointers were passed around as a jumble of integer values.
-17.3.6.2 CLOS Inheritance
+18.3.6.2 CLOS Inheritance
@@ -1131,12 +1131,12 @@ namespace BAR { inheritance of the classes in foreign code, with the ff:foreign-pointer class at its root. ff:foreign-pointer is a thin wrapper for pointers that is made available by the foreign function - interface. It's key benefit is that it may be passed as an argument + interface. Its key benefit is that it may be passed as an argument to any ff:def-foreign-call that is expecting a pointer as the parameter.
-17.3.6.3 Member fields and functions
+18.3.6.3 Member fields and functions
@@ -1152,7 +1152,7 @@ namespace BAR { the interface does nothing for friend directives,
-17.3.6.4 Why not directly access C++ classes using foreign types?
+18.3.6.4 Why not directly access C++ classes using foreign types?
@@ -1170,11 +1170,11 @@ namespace BAR { use the more robust wrapper functions.
-17.3.7 Templates
+18.3.7 Templates
-17.3.7.1 Generating wrapper code for templates
+18.3.7.1 Generating wrapper code for templates
@@ -1187,7 +1187,7 @@ namespace BAR { directive.
-17.3.7.2 Implicit Template instantiation
+18.3.7.2 Implicit Template instantiation
@@ -1197,7 +1197,7 @@ namespace BAR { class schema.
-17.3.8 Typedef, Templates, and Synonym Types
+18.3.8 Typedef, Templates, and Synonym Types
@@ -1277,7 +1277,7 @@ synonym> -
17.3.8.1 Choosing a primary type
+18.3.8.1 Choosing a primary type
@@ -1298,7 +1298,7 @@ synonym>
17.3.9 Function overloading/Parameter defaulting
+18.3.9 Function overloading/Parameter defaulting
@@ -1461,7 +1461,7 @@ overload> -
17.3.10 Operator wrapping and Operator overloading
+18.3.10 Operator wrapping and Operator overloading
@@ -1607,28 +1607,28 @@ opoverload> -
17.3.11 Varargs
+18.3.11 Varargs
Variable length argument lists are not supported, by default. If such a function is encountered, a warning will generated to - stderr. Varargs are supported via the SWIG %vararg + stderr. Varargs are supported via the SWIG %varargs directive. This directive allows you to specify a (finite) argument list which will be inserted into the wrapper in place of the variable length argument indicator. As an example, - consider the function printf(). It's declaration would + consider the function printf(). Its declaration would appear as follows:
See the following section on Variable Length arguments - provides examples on how %vararg can be used, along + provides examples on how %varargs can be used, along with other ways such functions can be wrapped.
-17.3.12 C++ Exceptions
+18.3.12 C++ Exceptions
@@ -1640,7 +1640,7 @@ opoverload> implemented.
-17.3.13 Pass by value, pass by reference
+18.3.13 Pass by value, pass by reference
@@ -1652,7 +1652,7 @@ opoverload> newly defined types.
-17.4 Typemaps
+18.4 Typemaps
@@ -1663,7 +1663,7 @@ opoverload> on Typemaps for more information.
-17.4.1 Code Generation in the C++ Wrapper
+18.4.1 Code Generation in the C++ Wrapper
@@ -1693,7 +1693,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -17.4.1.1 IN Typemap
+18.4.1.1 IN Typemap
@@ -1728,14 +1728,14 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -
17.4.1.2 OUT Typemap
+18.4.1.2 OUT Typemap
The out typemap is used to generate code to form the return value of the wrapper from the return value of the wrapped function. This code is placed in the <convert and bind result to lresult> - section of the above code diagram. It's default mapping is as follows: + section of the above code diagram. Its default mapping is as follows:
@@ -1752,13 +1752,13 @@ return-val wrapper-name(parm0, parm1, ..., parmN)-17.4.1.3 CTYPE Typemap
+18.4.1.3 CTYPE Typemap
This typemap is not used for code generation, but purely for the transformation of types in the parameter list of the wrapper function. - It's primary use is to handle by-value to by-reference conversion in the + Its primary use is to handle by-value to by-reference conversion in the wrappers parameter list. Its default settings are:
@@ -1784,7 +1784,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) these common typemaps here. -17.4.2 Code generation in Lisp wrappers
+18.4.2 Code generation in Lisp wrappers
@@ -1803,7 +1803,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) 16.3.1 Namespaces for details.
-17.4.2.1 LIN Typemap
+18.4.2.1 LIN Typemap
@@ -1846,7 +1846,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -
17.4.2.2 LOUT Typemap
+18.4.2.2 LOUT Typemap
@@ -1889,7 +1889,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -
17.4.2.3 FFITYPE Typemap
+18.4.2.3 FFITYPE Typemap
@@ -1939,7 +1939,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -17.4.2.4 LISPTYPE Typemap
+18.4.2.4 LISPTYPE Typemap
@@ -1959,7 +1959,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -
17.4.2.5 LISPCLASS Typemap
+18.4.2.5 LISPCLASS Typemap
@@ -1983,7 +1983,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -
17.4.3 Modifying SWIG behavior using typemaps
+18.4.3 Modifying SWIG behavior using typemaps
@@ -2017,10 +2017,10 @@ return-val wrapper-name(parm0, parm1, ..., parmN) -
17.5 Identifier Converter functions
+18.5 Identifier Converter functions
-17.5.1 Creating symbols in the lisp environment
+18.5.1 Creating symbols in the lisp environment
@@ -2041,11 +2041,11 @@ return-val wrapper-name(parm0, parm1, ..., parmN) of arguments.
-17.5.2 Existing identifier-converter functions
+18.5.2 Existing identifier-converter functions
Two basic identifier routines have been defined. -
17.5.2.1 identifier-convert-null
+18.5.2.1 identifier-convert-null
@@ -2054,7 +2054,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) strings, from which a symbol will be created.
-17.5.2.2 identifier-convert-lispify
+18.5.2.2 identifier-convert-lispify
@@ -2063,7 +2063,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) same symbol transformations.
-17.5.2.3 Default identifier to symbol conversions
+18.5.2.3 Default identifier to symbol conversions
@@ -2072,7 +2072,7 @@ return-val wrapper-name(parm0, parm1, ..., parmN) default naming conventions.
-17.5.3 Defining your own identifier-converter
+18.5.3 Defining your own identifier-converter
@@ -2093,7 +2093,7 @@ foreign environment.
The :type keyword argument provides more information on the type of -identifier. It's value is a symbol. This allows the +identifier. Its value is a symbol. This allows the identifier-converter to apply different heuristics when mapping different types of identifiers to symbols. SWIG will generate calls to your identifier-converter using the following types. @@ -2123,12 +2123,12 @@ scope in the specified class.
The :arity keyword argument only appears in swig:swig-defmethod forms -generated for overloaded functions. It's value is an integer +generated for overloaded functions. Its value is an integer indicating the number of arguments passed to the routine indicated by this identifier.
-17.5.4 Instructing SWIG to use a particular identifier-converter
+18.5.4 Instructing SWIG to use a particular identifier-converter
diff --git a/Doc/Manual/Android.html b/Doc/Manual/Android.html index 443d77691..e62139797 100644 --- a/Doc/Manual/Android.html +++ b/Doc/Manual/Android.html @@ -5,7 +5,7 @@
-18 SWIG and Android
+19 SWIG and Android
@@ -28,7 +30,7 @@ This chapter describes SWIG's support of Android. -@@ -15,7 +15,9 @@
+- Examples introduction
- Simple C example
- C++ class example +
- Other examples
C++ STL 18.1 Overview
+19.1 Overview
@@ -38,14 +40,14 @@ Everything in the Java chapter applies to generating cod This chapter contains a few Android specific notes and examples.
-18.2 Android examples
+19.2 Android examples
-18.2.1 Examples introduction
+19.2.1 Examples introduction
-The examples require the the Android SDK and Android NDK which can be installed as per instructions in the links. +The examples require the Android SDK and Android NDK which can be installed as per instructions in the links. The Eclipse version is not required for these examples as just the command line tools are used (shown for Linux as the host, but Windows will be very similar, if not identical in most places). Add the SDK tools and NDK tools to your path and create a directory somewhere for your Android projects (adjust PATH as necessary to where you installed the tools):
@@ -74,7 +76,7 @@ $ android list targets The following examples are shipped with SWIG under the Examples/android directory and include a Makefile to build and install each example. -18.2.2 Simple C example
+19.2.2 Simple C example
@@ -396,7 +398,7 @@ Run the app again and this time you will see the output pictured below, showing
- 18.2.3 C++ class example
+19.2.3 C++ class example
@@ -433,11 +435,11 @@ public: } virtual ~Shape() { nshapes--; - }; + } double x, y; void move(double dx, double dy); - virtual double area(void) = 0; - virtual double perimeter(void) = 0; + virtual double area() = 0; + virtual double perimeter() = 0; static int nshapes; }; @@ -445,18 +447,18 @@ class Circle : public Shape { private: double radius; public: - Circle(double r) : radius(r) { }; - virtual double area(void); - virtual double perimeter(void); + Circle(double r) : radius(r) { } + virtual double area(); + virtual double perimeter(); }; class Square : public Shape { private: double width; public: - Square(double w) : width(w) { }; - virtual double area(void); - virtual double perimeter(void); + Square(double w) : width(w) { } + virtual double area(); + virtual double perimeter(); }; @@ -480,19 +482,19 @@ void Shape::move(double dx, double dy) { int Shape::nshapes = 0; -double Circle::area(void) { +double Circle::area() { return M_PI*radius*radius; } -double Circle::perimeter(void) { +double Circle::perimeter() { return 2*M_PI*radius; } -double Square::area(void) { +double Square::area() { return width*width; } -double Square::perimeter(void) { +double Square::perimeter() { return 4*width; } @@ -744,6 +746,36 @@ Run the app to see the result of calling the C++ code from Java:
+ 19.2.4 Other examples
+ + ++The Examples/android directory contains further examples which can be run and installed in a similar manner to the previous two examples. +
+ ++Note that the 'extend' example is demonstrates the directors feature. +Normally C++ exception handling and the STL is not available by default in the version of g++ shipped with Android, but this example turns these features on as described in the next section. +
+ +19.3 C++ STL
+ + ++Should the C++ Standard Template Library (STL) be required, an Application.mk file needs to be created +in the same directory as the Android.mk directory containing information about the STL to use. +See the NDK documentation in the $NDKROOT/docs folder especially CPLUSPLUS-SUPPORT.html. +Below is an example of the Application.mk file to make the STLport static library available for use: +
+ +++ ++# File: Application.mk +APP_STL := gnustl_static ++
