From 34d80dcb8b517caecbcca18460e9820c926d9367 Mon Sep 17 00:00:00 2001 From: William S Fulton Date: Sat, 5 Feb 2022 20:33:16 +0000 Subject: [PATCH] attribute library documentation edits --- Doc/Manual/Contents.html | 1 + Doc/Manual/Library.html | 104 ++++++++++++++++++++++----------------- Doc/Manual/SWIG.html | 2 +- 3 files changed, 60 insertions(+), 47 deletions(-) diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index a3d0dcb4e..b1da2953a 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -449,6 +449,7 @@
  • Utility Libraries diff --git a/Doc/Manual/Library.html b/Doc/Manual/Library.html index 2cf2f97a0..fa1e14fe6 100644 --- a/Doc/Manual/Library.html +++ b/Doc/Manual/Library.html @@ -44,7 +44,7 @@
  • Utility Libraries @@ -2109,9 +2109,14 @@ For example: -

    12.5.2 attribute.i

    +

    12.5.2 attribute.i

    +

    +The attribute library contains a set of macros to convert a pair of set/get methods +into a "native" attribute/property. +

    +

    Use %attribute when you have a pair of get/set methods to a primitive type like: @@ -2122,8 +2127,7 @@ primitive type like: %include "attribute.i" %attribute(A, int, a, get_a, set_a); -struct A -{ +struct A { int get_a() const; void set_a(int aa); }; @@ -2132,8 +2136,21 @@ struct A

    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 +langage. This example only works for primitive types, not derived +types. +Now you can use the attributes like so (in Python): +

    + +
    +
    +x = A()
+x.a = 3        # calls A::set_a(3)
+print(x.a)     # calls A::get_a() const
+
    +
    + +

    +If you don't provide a 'set' method, a 'read-only' attribute is generated, ie, like:

    @@ -2152,21 +2169,31 @@ access methods for primitive types or class/structs, like: 
     %attributeref(A, int, b);
 
-struct A
-{
-  const int& b() const;
-  int& b();
+struct A {
+  const int & b() const;
+  int & b();
 };
 
 %attributeref(B, int, c);
 
-struct B
-{
-  int& c();
+struct B {
+  int & c();
 };
    +

    +Use the attributes like so (in Python): +

    + +
    +
    +x = A()
+x.b = 3        # calls A::b()
+print(x.b)     # calls A::b() const
+
    +
    +

    You can also use

    @@ -2193,25 +2220,10 @@ 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 +that reference-pointer translation is required. +Use %attribute2 instead of %attribute in cases like this:

    @@ -2225,18 +2237,18 @@ this: class MyClass { MyFoo foo; public: - MyFoo& GetFoo() { return foo; } - void SetFoo(const MyFoo& other) { foo = other; } + 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 +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 +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 @@ -2247,12 +2259,12 @@ try %attribute2 instead.

    NOTE: remember that if the type contains commas, such as -'std::pair', you need to use the macro like: +std::pair<int, int>, you need to use the macro like: 

    -%attributeref(A, %arg(std::pair), pval);
+%attributeref(A, %arg(std::pair<int, int>), pval);
    @@ -2275,10 +2287,10 @@ access is by value rather than reference. %attributeval(MyClassVal, MyFoo, ReadOnlyFoo, GetFoo); %inline %{ class MyClassVal { - MyFoo foo; + MyFoo foo; public: - MyFoo GetFoo() { return foo; } - void SetFoo(MyFoo other) { foo = other; } + MyFoo GetFoo() { return foo; } + void SetFoo(MyFoo other) { foo = other; } }; %} @@ -2288,21 +2300,21 @@ access is by value rather than reference. 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: +in the target language. Example usage for std::string: 

    -%include 
+%include <std_string.i>
 %attributestring(MyStringyClass, std::string, ReadWriteString, GetString, SetString);
 %attributestring(MyStringyClass, std::string, ReadOnlyString, GetString);
 %inline %{
   class MyStringyClass {
-	std::string str;
+    std::string str;
   public:
-	MyStringyClass(const std::string &val) : str(val) {}
-	std::string GetString() { return str; }
-	void SetString(std::string other) { str = other; }
+    MyStringyClass(const std::string &val) : str(val) {}
+    std::string GetString() { return str; }
+    void SetString(std::string other) { str = other; }
   };
 %}
    @@ -2312,7 +2324,7 @@ in the target language. Example usage for std::string: 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. +%shared_ptr.

    diff --git a/Doc/Manual/SWIG.html b/Doc/Manual/SWIG.html index f54c6d3cf..6ad6c6770 100644 --- a/Doc/Manual/SWIG.html +++ b/Doc/Manual/SWIG.html @@ -2776,7 +2776,7 @@ 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. +attributes.i.