From 562effb50fe4ad7b954f2205d3879678a4edf235 Mon Sep 17 00:00:00 2001 From: Corey Minyard Date: Fri, 28 Jan 2022 08:59:08 -0600 Subject: [PATCH] Move the attribute.i docs into Library.html Per comments on the merge request, this is the appropriate place for it, and add a reference to it from the structures and unions section so someone looking there will see it. Also remove the changes in Contents.html, since that is regenerated and those changes are just noise in the commit. Signed-off-by: Corey Minyard --- Doc/Manual/Contents.html | 1 - Doc/Manual/Library.html | 208 ++++++++++++++++++++++++++++++++++++ Doc/Manual/SWIG.html | 221 ++------------------------------------- 3 files changed, 218 insertions(+), 212 deletions(-) diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 3e620375c..cf72febef 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -184,7 +184,6 @@
  • Typedef and structures
  • Character strings and structures
  • Array members -
  • Attributes and the %attribute directive
  • Structure data members
  • C constructors and destructors
  • Adding member functions to C structures diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html index 5f72b557d..2cf2f97a0 100644 --- a/Doc/Manual/Library.html +++ b/Doc/Manual/Library.html @@ -44,6 +44,7 @@
  • Utility Libraries @@ -2108,5 +2109,212 @@ For example: +

    12.5.2 attribute.i

    + + +

    +Use %attribute when you have a pair of get/set methods to a +primitive type like: +

    + +
    +
    +%include "attribute.i"
+%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: +

    + +
    +
    +%attribute(A, int, c, get_c);
+
    +
    + +

    +Use %attributeref when you have const/non-const reference +access methods for primitive types or class/structs, like: +

    + +
    +
    +%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. +

    + + diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index 2404df8db..6743328bb 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -59,7 +59,6 @@
  • Typedef and structures
  • Character strings and structures
  • Array members -
  • Attributes and the %attribute directive
  • Structure data members
  • C constructors and destructors
  • Adding member functions to C structures @@ -2636,212 +2635,7 @@ discussed in a later chapter. In many cases, the warning message is harmless.

    -

    5.5.4 Attributes and the %attribute directive

    - - -

    -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. -

    - -

    5.5.5 Structure data members

    +

    5.5.4 Structure data members

    @@ -2939,6 +2733,11 @@ void Foo_w_set(FOO *f, WORD value) { +

    +If you have accessor methods that you want to use as attributes in the +target language, you can make them appear as data members using +attributes.i. +

    Compatibility Note: SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes @@ -2947,7 +2746,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;".

    -

    5.5.6 C constructors and destructors

    +

    5.5.5 C constructors and destructors

    @@ -3036,7 +2835,7 @@ the target languages, and it is highly recommended you don't use them.

    -

    5.5.7 Adding member functions to C structures

    +

    5.5.6 Adding member functions to C structures

    @@ -3309,7 +3108,7 @@ be used to extend a structure with more than just methods, a more suitable directive name has been chosen.

    -

    5.5.8 Nested structures

    +

    5.5.7 Nested structures

    @@ -3393,7 +3192,7 @@ Finally, note that nesting is handled differently in C++ mode, see Nested classes.

    -

    5.5.9 Other things to note about structure wrapping

    +

    5.5.8 Other things to note about structure wrapping