Adding member functions to C structures
@@ -2635,7 +2636,212 @@ discussed in a later chapter. In many cases, the warning message is
harmless.
-
+
+
+
+
+Use %attribute when you have a pair of get/set methods to a
+primitive type like in:
+
+
+
+
+%attribute(A, int, a, get_a, set_a);
+
+struct A
+{
+ int get_a() const;
+ void set_a(int aa);
+};
+
+
+and you want to provide that variable as an attribute in the target
+langage. This examples only works for primitive types, not derived
+types. If you don't provide a 'set' method, a 'read-only' attribute
+is generated, ie, like in:
+
+
+
+
+%attribute(A, int, c, get_c);
+
+
+Use %attributeref when you have const/non-const reference
+access methods for primitive types or class/structs, like in:
+
+
+
+
+%attributeref(A, int, b);
+
+struct A
+{
+ const int& b() const;
+ int& b();
+};
+
+%attributeref(B, int, c);
+
+struct B
+{
+ int& c();
+};
+
+
+You can also use
+
+
+
+
+%attributeref(Class, AttributeType, AttributeName, AccessorMethod)
+
+
+if the internal C++ reference methods have a different name from the
+attribute you want, so
+
+
+
+
+%attributeref(B, int, d, c);
+
+
+is the same as the last example, but instead of the attribute 'c' being
+called 'c', it is called 'd'.
+
+
+
+Now you can use the attributes like so:
+
+
+
+
+x = A()
+x.a = 3 # calls A::set_a
+print x.a # calls A::get_a
+
+x.b = 3 # calls A::b()
+print x.b # calls A::b() const
+
+
+Use %attribute2 instead of %attribute to indicate
+that reference-pointer translation is required. You
+use %attribute2 instead of %attribute in cases like
+this:
+
+
+
+
+%attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
+%inline %{
+ struct MyFoo {
+ int x;
+ };
+ class MyClass {
+ MyFoo foo;
+ public:
+ MyFoo& GetFoo() { return foo; }
+ void SetFoo(const MyFoo& other) { foo = other; }
+ };
+%}
+
+
+Here, the data type of the property is a wrapped type (MyFoo) and on
+the C++ side it is passed by reference. The problem is that the SWIG
+wrapper will pass around a pointer (MyFoo *) which is not compatible
+with the reference type of the accessors (MyFoo &). Therefore, if you
+use %attribute, you'll get an error from your C/C++
+compiler. %attribute2 translates between a pointer and a
+reference to eliminate the error. In case you're confused, let's make
+it simple: just use %attribute at first, but if the C/C++
+compiler gives an error while compiling the wrapper,
+try %attribute2 instead.
+
+
+
+NOTE: remember that if the type contains commas, such as
+'std::pair', you need to use the macro like:
+
+
+
+
+%attributeref(A, %arg(std::pair), pval);
+
+
+where %arg() 'normalizes' the type to be understood as a single
+argument, otherwise the macro will get confused by the comma.
+
+
+
+The %attributeval is the same as %attribute, but
+should be used when the type is a class/struct (ie a non-primitive
+type) and when the get and set methods return/pass by value. The
+following is very similar to the above example, but note that the
+access is by value rather than reference.
+
+
+
+
+%attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
+%attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
+%inline %{
+ class MyClassVal {
+ MyFoo foo;
+ public:
+ MyFoo GetFoo() { return foo; }
+ void SetFoo(MyFoo other) { foo = other; }
+ };
+%}
+
+
+The %attributestring is the same as %attributeval,
+but should be used for string class types, which are unusual as they
+are a class on the C++ side, but normally an immutable/primitive type
+in the target language. Example usage for std::string:
+
+
+
+
+%include
+%attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
+%attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
+%inline %{
+ class MyStringyClass {
+ std::string str;
+ public:
+ MyStringyClass(const std::string &val) : str(val) {}
+ std::string GetString() { return str; }
+ void SetString(std::string other) { str = other; }
+ };
+%}
+
+
+The %attributestring also works for class types that
+have %naturalvar turned on and so is also useful for
+shared_ptr which has %naturalvar turned on in
+%shared_ptr.
+
+
+
@@ -2741,7 +2947,7 @@ class, or union. This is unlikely to break existing code. However, if you need
datatype is really a struct, simply use a forward struct declaration such as "struct Foo;".
-
+
@@ -2830,7 +3036,7 @@ the target languages, and it is highly recommended you don't use them.
-
+
@@ -3103,7 +3309,7 @@ be used to extend a structure with more than just methods, a more suitable
directive name has been chosen.
-
+
@@ -3187,7 +3393,7 @@ Finally, note that nesting is handled differently in C++ mode,
see Nested classes.
-
+
diff --git a/Lib/typemaps/attribute.swg b/Lib/typemaps/attribute.swg
index 37c3340cf..7d4767f52 100644
--- a/Lib/typemaps/attribute.swg
+++ b/Lib/typemaps/attribute.swg
@@ -7,132 +7,6 @@
/*
The following macros convert a pair of set/get methods
into a "native" attribute.
-
- Use %attribute when you have a pair of get/set methods to a primitive type
- like in:
-
- %attribute(A, int, a, get_a, set_a);
-
- struct A
- {
- int get_a() const;
- void set_a(int aa);
- };
-
- If you don't provide a 'set' method, a 'read-only' attribute
- is generated, ie, like in:
-
- %attribute(A, int, c, get_c);
-
- Use %attributeref when you have const/non-const reference access methods
- for primitive types or class/structs, like in:
-
- %attributeref(A, int, b);
-
- struct A
- {
- const int& b() const;
- int& b();
- };
-
- %attributeref(B, int, c);
-
- struct B
- {
- int& c();
- };
-
- You can also use
-
- %attributeref(Class, AttributeType, AttributeName, AccessorMethod)
-
- if the internal C++ reference methods have a different name from the
- attribute you want, so
-
- %attributeref(B, int, d, c);
-
- is the same as the last example, but instead of the attribute 'c' being
- called 'c', it is called 'd'.
-
- Now you can use the attributes like so:
-
- x = A()
- x.a = 3 # calls A::set_a
- print x.a # calls A::get_a
-
- x.b = 3 # calls A::b()
- print x.b # calls A::b() const
-
- Use %attribute2 instead of %attribute to indicate that reference-pointer
- translation is required. You use %attribute2 instead of %attribute in
- cases like this:
-
- %attribute2(MyClass, MyFoo, Foo, GetFoo, SetFoo);
- %inline %{
- struct MyFoo {
- int x;
- };
- class MyClass {
- MyFoo foo;
- public:
- MyFoo& GetFoo() { return foo; }
- void SetFoo(const MyFoo& other) { foo = other; }
- };
- %}
-
- Here, the data type of the property is a wrapped type (MyFoo) and on the
- C++ side it is passed by reference. The problem is that the SWIG wrapper will
- pass around a pointer (MyFoo *) which is not compatible with the reference
- type of the accessors (MyFoo &). Therefore, if you use %attribute, you'll get
- an error from your C/C++ compiler. %attribute2 translates between a pointer
- and a reference to eliminate the error. In case you're confused, let's make it
- simple: just use %attribute at first, but if the C/C++ compiler gives an error
- while compiling the wrapper, try %attribute2 instead.
-
- NOTE: remember that if the type contains commas, such as 'std::pair',
- you need to use the macro like:
-
- %attributeref(A, %arg(std::pair), pval);
-
- where %arg() 'normalizes' the type to be understood as a single
- argument, otherwise the macro will get confused by the comma.
-
- The %attributeval is the same as %attribute, but should be used when the type
- is a class/struct (ie a non-primitive type) and when the get and set methods
- return/pass by value. The following is very similar to the above example, but
- note that the access is by value rather than reference.
-
- %attributeval(MyClassVal, MyFoo, ReadWriteFoo, GetFoo, SetFoo);
- %attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo);
- %inline %{
- class MyClassVal {
- MyFoo foo;
- public:
- MyFoo GetFoo() { return foo; }
- void SetFoo(MyFoo other) { foo = other; }
- };
- %}
-
- The %attributestring is the same as %attributeval, but should be used for string
- class types, which are unusual as they are a class on the C++ side, but normally an
- immutable/primitive type in the target language. Example usage for std::string:
-
- %include
- %attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
- %attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
- %inline %{
- class MyStringyClass {
- std::string str;
- public:
- MyStringyClass(const std::string &val) : str(val) {}
- std::string GetString() { return str; }
- void SetString(std::string other) { str = other; }
- };
- %}
-
- The %attributestring also works for class types that have %naturalvar turned
- on and so is also useful for shared_ptr which has %naturalvar turned on in %shared_ptr.
-
*/
//