Update documentation for using SWIG_ConvertPtr example usage

Add a test case to test the example documentation typemaps

8 files changed, 125 insertions, 54 deletions

diff --git a/Doc/Manual/Lua.html b/Doc/Manual/Lua.html
index 032d05dba..131d92825 100644
--- a/Doc/Manual/Lua.html
+++ b/Doc/Manual/Lua.html
@@ -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>
diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html
index 19747c3dc..4722a01ba 100644
--- a/Doc/Manual/Perl5.html
+++ b/Doc/Manual/Perl5.html
@@ -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>
diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html
index 30aa82115..b6df0895f 100644
--- a/Doc/Manual/Python.html
+++ b/Doc/Manual/Python.html
@@ -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>
diff --git a/Doc/Manual/Tcl.html b/Doc/Manual/Tcl.html
index b07f99b69..af4880217 100644
--- a/Doc/Manual/Tcl.html
+++ b/Doc/Manual/Tcl.html
@@ -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>
diff --git a/Doc/Manual/Typemaps.html b/Doc/Manual/Typemaps.html
index f83a26949..8aa5abb3f 100644
--- a/Doc/Manual/Typemaps.html
+++ b/Doc/Manual/Typemaps.html
@@ -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;
-  }
-}
-
-%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;
-  }
+%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) PyObject *
-{
+%typecheck(SWIG_TYPECHECK_POINTER) PyObject * {
   $1 = ($input != 0);
 }
 </pre>
diff --git a/Examples/test-suite/common.mk b/Examples/test-suite/common.mk
index b9ba746bb..c6a02f487 100644
--- a/Examples/test-suite/common.mk
+++ b/Examples/test-suite/common.mk
@@ -487,6 +487,7 @@ CPP_TEST_CASES += \
 	typemap_array_qualifiers \
 	typemap_delete \
 	typemap_directorout \
+	typemap_documentation \
 	typemap_global_scope \
 	typemap_manyargs \
 	typemap_namespace \
diff --git a/Examples/test-suite/python/typemap_documentation_runme.py b/Examples/test-suite/python/typemap_documentation_runme.py
new file mode 100644
index 000000000..3d1c6fa8c
--- /dev/null
+++ b/Examples/test-suite/python/typemap_documentation_runme.py
@@ -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")
diff --git a/Examples/test-suite/typemap_documentation.i b/Examples/test-suite/typemap_documentation.i
new file mode 100644
index 000000000..b7c1ddd22
--- /dev/null
+++ b/Examples/test-suite/typemap_documentation.i
@@ -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;
+}
+%}