XS-MLVP
/
swig
mirror of https://github.com/swig/swig
5
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation for using SWIG_ConvertPtr example usage 

Add a test case to test the example documentation typemaps
This commit is contained in:
William S Fulton 2016-10-22 20:55:37 +01:00
parent 268b942865
commit 96015de0dd
8 changed files with 125 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/Manual/Lua.html
View File

@ -1740,7 +1740,7 @@ ptr=nil -- the iMath* will be GC'ed as normal
<div class="indent">
This is the standard function used for converting a Lua userdata to a void*. It takes the value at the given index in the Lua state and converts it to a userdata. It will then provide the necessary type checks, confirming that the pointer is compatible with the type given in 'type'. Then finally setting '*ptr' to the pointer.
If flags is set to SWIG_POINTER_DISOWN, this is will clear any ownership flag set on the object.<br>
The returns a value which can be checked with the macro SWIG_IsOK()
This returns a value which can be checked with the macro SWIG_IsOK()
</div>
<p><tt>void SWIG_NewPointerObj(lua_State* L,void* ptr,swig_type_info *type,int own);</tt></p>

12
Doc/Manual/Perl5.html
View File

@ -2477,7 +2477,9 @@ is usually accessed as follows:
<div class="code">
<pre>
Foo *f;
if (SWIG_ConvertPtr($input, (void **) &amp;f, SWIGTYPE_p_Foo, 0) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;f, SWIGTYPE_p_Foo, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
SV *sv = sv_newmortal();
SWIG_MakePtr(sv, f, SWIGTYPE_p_Foo, 0);
@ -2492,7 +2494,9 @@ variable <tt>$1_descriptor</tt>. For example:
<div class="code">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input,(void **) &amp;$1, $1_descriptor,0)) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>
@ -2505,7 +2509,9 @@ For example:
<div class="code">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input,(void **) &amp;$1, $descriptor(Foo *), 0)) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $descriptor(Foo *), 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>

16
Doc/Manual/Python.html
View File

@ -5208,8 +5208,9 @@ is usually accessed as follows:
<div class="code">
<pre>
Foo *f;
if (SWIG_ConvertPtr($input, (void **) &amp;f, SWIGTYPE_p_Foo, SWIG_POINTER_EXCEPTION) == -1)
return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;f, SWIGTYPE_p_Foo, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
PyObject *obj;
obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
@ -5224,8 +5225,9 @@ variable <tt>$1_descriptor</tt>. For example:
<div class="code">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input,(void **) &amp;$1, $1_descriptor,SWIG_POINTER_EXCEPTION)) == -1)
return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>
@ -5238,9 +5240,9 @@ For example:
<div class="code">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input,(void **) &amp;$1, $descriptor(Foo *),
SWIG_POINTER_EXCEPTION)) == -1)
return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $descriptor(Foo *), 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>

12
Doc/Manual/Tcl.html
View File

@ -3088,7 +3088,9 @@ is usually accessed as follows:
<div class="indent">
<pre>
Foo *f;
if (SWIG_ConvertPtr($input, (void **) &amp;f, SWIGTYPE_p_Foo, 0) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;f, SWIGTYPE_p_Foo, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
Tcl_Obj *;
obj = SWIG_NewPointerObj(f, SWIGTYPE_p_Foo, 0);
@ -3103,7 +3105,9 @@ variable <tt>$1_descriptor</tt>. For example:
<div class="indent">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input,(void **) &amp;$1, $1_descriptor,0)) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>
@ -3116,7 +3120,9 @@ For example:
<div class="indent">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input,(void **) &amp;$1, $descriptor(Foo *), 0)) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $descriptor(Foo *), 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>

66
Doc/Manual/Typemaps.html
View File

@ -489,7 +489,7 @@ int foo(<b>int x, double y, char *s</b>);
<ul>
<li>Input argument conversion ("in" typemap).</li>
<li>Input argument type checking ("typecheck" typemap).</li>
<li>Input argument type checking for types used in overloaded methods ("typecheck" typemap).</li>
<li>Output argument handling ("argout" typemap).</li>
<li>Input argument value checking ("check" typemap).</li>
<li>Input argument initialization ("arginit" typemap).</li>
@ -2586,6 +2586,7 @@ to see whether or not it matches a specific type. For example:
<p>
For typechecking, the $1 variable is always a simple integer that is set to 1 or 0 depending on whether or not
the input argument is the correct type.
Set to 1 if the input argument is the correct type otherwise set to 0.
</p>
<p>
@ -4138,14 +4139,17 @@ For example:
<div class="code">
<pre>
class Foo {
public:
int x;
};
class Bar {
public:
int y;
};
class FooBar : public Foo, public Bar {
public:
int z;
};
</pre>
@ -4180,12 +4184,15 @@ handling of pointer values (and to make adjustments when needed).
<p>
In the wrapper code generated for each language, pointers are handled through
the use of special type descriptors and conversion functions. For example,
if you look at the wrapper code for Python, you will see code like this:
if you look at the wrapper code for Python, you will see code similar to the following
(simplified for brevity):
</p>
<div class="code">
<pre>
if ((SWIG_ConvertPtr(obj0,(void **) &amp;arg1, SWIGTYPE_p_Foo,1)) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr(obj0, (void **) &amp;arg1, SWIGTYPE_p_Foo, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method 'GrabVal', expecting type Foo");
}
</pre>
</div>
@ -4197,8 +4204,10 @@ target language, a list of equivalent typenames (via typedef or
inheritance), and pointer value handling information (if applicable).
The <tt>SWIG_ConvertPtr()</tt> function is simply a utility function
that takes a pointer object in the target language and a
type-descriptor objects and uses this information to generate a C++
pointer. However, the exact name and calling conventions of the conversion
type-descriptor object and uses this information to generate a C++ pointer.
The <tt>SWIG_IsOK</tt> macro checks the return value for errors and
<tt>SWIG_exception_fail</tt> can be called to raise an exception in the target language.
However, the exact name and calling conventions of the conversion
function depends on the target language (see language specific chapters for details).
</p>
@ -4304,7 +4313,9 @@ similar to this:
<div class="code">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor)) == -1) return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
</pre>
</div>
@ -4337,12 +4348,12 @@ descriptor name for any C datatype. For example:
<div class="code">
<pre>
%typemap(in) Foo * {
if ((SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor)) == -1) {
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;$1, $1_descriptor, 0))) {
Bar *temp;
if ((SWIG_ConvertPtr($input, (void **) &amp;temp, <b>$descriptor(Bar *)</b>) == -1) {
return NULL;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &amp;temp, $descriptor(Bar *), 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo or Bar");
}
$1 = (Foo *) temp;
$1 = (Foo *)temp;
}
}
</pre>
@ -4588,38 +4599,13 @@ The following excerpt from the Python module illustrates this:
$1 = PyString_Check($input) ? 1 : 0;
}
%typecheck(SWIG_TYPECHECK_POINTER) SWIGTYPE *, SWIGTYPE &amp;, SWIGTYPE [] {
void *ptr;
if (SWIG_ConvertPtr($input, (void **) &amp;ptr, $1_descriptor, 0) == -1) {
$1 = 0;
PyErr_Clear();
} else {
$1 = 1;
}
%typemap(typecheck,precedence=SWIG_TYPECHECK_POINTER,noblock=1) SWIGTYPE * {
void *vptr = 0;
int res = SWIG_ConvertPtr($input, &amp;vptr, $1_descriptor, 0);
$1 = SWIG_IsOK(res) ? 1 : 0;
}
%typecheck(SWIG_TYPECHECK_POINTER) SWIGTYPE {
void *ptr;
if (SWIG_ConvertPtr($input, (void **) &amp;ptr, $&amp;1_descriptor, 0) == -1) {
$1 = 0;
PyErr_Clear();
} else {
$1 = 1;
}
}
%typecheck(SWIG_TYPECHECK_VOIDPTR) void * {
void *ptr;
if (SWIG_ConvertPtr($input, (void **) &amp;ptr, 0, 0) == -1) {
$1 = 0;
PyErr_Clear();
} else {
$1 = 1;
}
}
%typecheck(SWIG_TYPECHECK_POINTER) PyObject *
{
%typecheck(SWIG_TYPECHECK_POINTER) PyObject * {
$1 = ($input != 0);
}
</pre>

1
Examples/test-suite/common.mk
View File

@ -487,6 +487,7 @@ CPP_TEST_CASES += \
typemap_array_qualifiers \
typemap_delete \
typemap_directorout \
typemap_documentation \
typemap_global_scope \
typemap_manyargs \
typemap_namespace \

20
Examples/test-suite/python/typemap_documentation_runme.py Normal file
View File

@ -0,0 +1,20 @@
import typemap_documentation
f = typemap_documentation.Foo()
f.x = 55
b = typemap_documentation.Bar()
b.y = 44
if 55 != typemap_documentation.GrabVal(f):
raise RuntimeError("bad value")
try:
typemap_documentation.GrabVal(b)
raise RuntimeError("unexpected exception")
except TypeError:
pass
if 55 != typemap_documentation.GrabValFooBar(f):
raise RuntimeError("bad f value")
if 44 != typemap_documentation.GrabValFooBar(b):
raise RuntimeError("bad b value")

50
Examples/test-suite/typemap_documentation.i Normal file
View File

@ -0,0 +1,50 @@
%module typemap_documentation
// A place for checking that documented typemaps are working.
// The UTL languages are the only ones that are consistent enough to support these generic typemap functions.
// These are in the Typemaps.html chapter.
%inline %{
class Foo {
public:
int x;
};
class Bar {
public:
int y;
};
%}
#if defined(SWIGUTL)
%typemap(in) Foo * {
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo");
}
}
#endif
%inline %{
int GrabVal(Foo *f) {
return f->x;
}
%}
#if defined(SWIGUTL)
%typemap(in) Foo * {
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 0))) {
Bar *temp;
if (!SWIG_IsOK(SWIG_ConvertPtr($input, (void **) &temp, $descriptor(Bar *), 0))) {
SWIG_exception_fail(SWIG_TypeError, "in method '$symname', expecting type Foo or Bar");
}
$1 = (Foo *)temp;
}
}
#endif
%inline %{
int GrabValFooBar(Foo *f) {
return f->x;
}
%}