jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

%naturalvar documentation added

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@8644 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton 2006-01-30 22:17:42 +00:00
commit 20ac2ec248
3 changed files with 72 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/Manual/Contents.html
View file

@ -160,7 +160,7 @@
<li><a href="SWIG.html#SWIG_nn32">Typedef and structures</a>
<li><a href="SWIG.html#SWIG_nn33">Character strings and structures</a>
<li><a href="SWIG.html#SWIG_nn34">Array members</a>
<li><a href="SWIG.html#SWIG_nn35">Structure data members</a>
<li><a href="SWIG.html#SWIG_structure_data_members">Structure data members</a>
<li><a href="SWIG.html#SWIG_nn36">C constructors and destructors </a>
<li><a href="SWIG.html#SWIG_adding_member_functions">Adding member functions to C structures</a>
<li><a href="SWIG.html#SWIG_nn38">Nested structures</a>
@ -202,7 +202,7 @@
<li><a href="SWIGPlus.html#SWIGPlus_nn10">Copy constructors</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn11">Member functions</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn12">Static members</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn13">Member data</a>
<li><a href="SWIGPlus.html#SWIGPlus_member_data">Member data</a>
</ul>
<li><a href="SWIGPlus.html#SWIGPlus_default_args">Default arguments</a>
<li><a href="SWIGPlus.html#SWIGPlus_nn15">Protection</a>

10
Doc/Manual/SWIG.html
View file

@ -52,7 +52,7 @@
<li><a href="#SWIG_nn32">Typedef and structures</a>
<li><a href="#SWIG_nn33">Character strings and structures</a>
<li><a href="#SWIG_nn34">Array members</a>
<li><a href="#SWIG_nn35">Structure data members</a>
<li><a href="#SWIG_structure_data_members">Structure data members</a>
<li><a href="#SWIG_nn36">C constructors and destructors </a>
<li><a href="#SWIG_adding_member_functions">Adding member functions to C structures</a>
<li><a href="#SWIG_nn38">Nested structures</a>
@ -2114,7 +2114,7 @@ discussed in a later chapter. In many cases, the warning message is
harmless.
</p>
<H3><a name="SWIG_nn35"></a>5.5.4 Structure data members</H3>
<H3><a name="SWIG_structure_data_members"></a>5.5.4 Structure data members</H3>
<p>
@ -2135,8 +2135,9 @@ typedef struct Bar {
</div>
<p>
When a structure member is wrapped, it is always handled as a pointer.
For example:
When a structure member is wrapped, it is handled as a pointer, unless the <tt>%naturalvar</tt> directive
is used where it is handled more like a C++ reference (see <a href="SWIGPlus.html#SWIGPlus_member_data">C++ Member data</a>).
The accessors to the member variable as a pointer is effectively wrapped as follows:
</p>
<div class="code">
@ -2211,6 +2212,7 @@ void Foo_w_set(FOO *f, WORD value) {
</pre>
</div>
<p>
<b>Compatibility Note: </b> SWIG-1.3.11 and earlier releases transformed all non-primitive member datatypes
to pointers. Starting in SWIG-1.3.12, this transformation <em>only</em> occurs if a datatype is known to be a structure,

69
Doc/Manual/SWIGPlus.html
View file

@ -22,7 +22,7 @@
<li><a href="#SWIGPlus_nn10">Copy constructors</a>
<li><a href="#SWIGPlus_nn11">Member functions</a>
<li><a href="#SWIGPlus_nn12">Static members</a>
<li><a href="#SWIGPlus_nn13">Member data</a>
<li><a href="#SWIGPlus_member_data">Member data</a>
</ul>
<li><a href="#SWIGPlus_default_args">Default arguments</a>
<li><a href="#SWIGPlus_nn15">Protection</a>
@ -622,12 +622,12 @@ Usually, static members are accessed as functions with names in which the class
prepended with an underscore. For example, <tt>List_print</tt>.
</p>
<H3><a name="SWIGPlus_nn13"></a>6.5.7 Member data</H3>
<H3><a name="SWIGPlus_member_data"></a>6.5.7 Member data</H3>
<p>
Member data is handled in exactly the same manner as for C
structures. A pair of accessor functions are created. For example
structures. A pair of accessor functions are effectively created. For example
:</p>
<div class="code"><pre>
@ -708,8 +708,67 @@ void Foo_items_set(Foo *self, List *value) {
</div>
<p>
More information about this can be found in the "Structure data
members" section of the <a href="SWIG.html#SWIG">SWIG Basics</a> chapter.
More information about this can be found in the SWIG Basics chapter,
<a href="SWIG.html#SWIG_structure_data_members">Structure data members</a> section.
</p>
<p>
The wrapper code to generate the accessors for classes comes from the pointer typemaps.
This can be somewhat unnatural for some types.
For example, a user would expect the STL std::string class member variables to be wrapped as a string in the target language,
rather than a pointer to this class.
The const reference typemaps offer this type of marshalling, so there is a feature to tell SWIG to use the const reference typemaps rather than the pointer typemaps.
It is the <tt>%naturalvar</tt> feature and is used as follows:
</p>
<div class="code">
<pre>
// All List variables will use const List&amp; typemaps
%naturalvar List;
// Only Foo::myList will use const List&amp; typemaps
%naturalvar Foo::myList;
struct Foo {
List myList;
};
// All variables will use const reference typemaps
%naturalvar;
</pre>
</div>
<p>
The observant reader will notice that <tt>%naturalvar</tt> works like any other <a href="Customization.html#features">feature</a>, except it can also be attached to class types.
The first of the example usages above show <tt>%naturalvar</tt> attaching to the <tt>List</tt> class.
Effectively this feature changes the way accessors are generated to the following:
</p>
<div class="code">
<pre>
const List &amp;Foo_items_get(Foo *self) {
return self-&gt;items;
}
void Foo_items_set(Foo *self, const List &amp;value) {
self-&gt;items = value;
}
</pre>
</div>
<p>
In fact it is generally a good idea to use this feature globally as the reference typemaps have extra NULL checking compared to the pointer typemaps.
A pointer can be NULL, whereas a reference cannot, so the extra checking ensures that the target language user does not pass in a value that translates
to a NULL pointer and thereby preventing any potential NULL pointer dereferences.
The <tt>%naturalvar</tt> feature will also apply to global variables in some language modules, eg C# and Java.
</p>
<p>
Other alternatives for turning this feature on globally are to use the <tt>swig -naturalvar</tt> commandline option
or the module mode option, <tt>%module(naturalvar=1)</tt>
</p>
<p>
<b>Compatibility note:</b> The <tt>%naturalvar</tt> feature was introduced in SWIG-1.3.28, prior to which it was necessary to manually apply the const reference
typemaps, eg <tt>%apply const std::string &amp; { std::string * }</tt>, but this example would also apply the typemaps to methods taking a </tt>std::string</tt> pointer.
</p>
<p>