Updated documentation for 3D typemaps

4 files changed, 71 insertions, 41 deletions

diff --git a/numpy/doc/swig/README b/numpy/doc/swig/README
index 9fd5857b6..c1e1a997c 100644
--- a/numpy/doc/swig/README
+++ b/numpy/doc/swig/README
@@ -21,6 +21,11 @@ to do with numpy.i.  The files related to testing are::
     Matrix.i
     test2D.py
 
+    Tensor.h
+    Tensor.cxx
+    Tensor.i
+    test3D.py
+
 The header files contain prototypes for functions that illustrate the
 wrapping issues we wish to address.  Right now, this consists of
 functions with argument signatures of the following forms.  Vector.h::
@@ -49,8 +54,20 @@ Matrix.h::
 
     (type ARGOUT_ARRAY2[ANY][ANY])
 
+Tensor.h::
+
+    (type IN_ARRAY3[ANY][ANY][ANY])
+    (type* IN_ARRAY3, int DIM1, int DIM2, int DIM3)
+    (int DIM1, int DIM2, int DIM3, type* IN_ARRAY3)
+
+    (type INPLACE_ARRAY3[ANY][ANY][ANY])
+    (type* INPLACE_ARRAY3, int DIM1, int DIM2, int DIM3)
+    (int DIM1, int DIM2, int DIM3, type* INPLACE_ARRAY3)
+
+    (type ARGOUT_ARRAY3[ANY][ANY][ANY])
+
 These function signatures take a pointer to an array of type "type",
-whose length is specified by the integer(s) DIM1 (and DIM2).
+whose length is specified by the integer(s) DIM1 (and DIM2, and DIM3).
 
 The objective for the IN_ARRAY signatures is for SWIG to generate
 python wrappers that take a container that constitutes a valid
@@ -64,23 +81,24 @@ The objective for the INPLACE_ARRAY signatures is for SWIG to generate
 python wrappers that accept a numpy array of any of the above-listed
 types.
 
-The source files Vector.cxx and Matrix.cxx contain the actual
-implementations of the functions described in Vector.h and Matrix.h.
-The python scripts test1D.py and test2D.py test the resulting python
-wrappers using the unittest module.
+The source files Vector.cxx, Matrix.cxx and Tensor.cxx contain the
+actual implementations of the functions described in Vector.h,
+Matrix.h and Tensor.h.  The python scripts test1D.py, test2D.py and
+test3D.py test the resulting python wrappers using the unittest
+module.
 
-The SWIG interface files Vector.i and Matrix.i are used to generate
-the wrapper code.  The SWIG_FILE_WITH_INIT macro allows numpy.i to be
-used with multiple python modules.  If it is specified, then the %init
-block found in Vector.i and Matrix.i are required.  The other things
-done in Vector.i and Matrix.i are the inclusion of the appropriate
-header file and numpy.i file, and the "%apply" directives to force the
-functions to use the typemaps.
+The SWIG interface files Vector.i, Matrix.i and Tensor.i are used to
+generate the wrapper code.  The SWIG_FILE_WITH_INIT macro allows
+numpy.i to be used with multiple python modules.  If it is specified,
+then the %init block found in Vector.i, Matrix.i and Tensor.i are
+required.  The other things done in Vector.i, Matrix.i and Tensor.i
+are the inclusion of the appropriate header file and numpy.i file, and
+the "%apply" directives to force the functions to use the typemaps.
 
 The setup.py script is a standard python distutils script.  It defines
-_Vector and _Matrix extension modules and Vector and Matrix python
-modules.  The Makefile automates everything, setting up the
-dependencies, calling swig to generate the wrappers, and calling
+_Vector, _Matrix and _Tensor extension modules and Vector, Matrix and
+Tensor python modules.  The Makefile automates everything, setting up
+the dependencies, calling swig to generate the wrappers, and calling
 setup.py to compile the wrapper code and generate the shared objects.
 Targets "all" (default), "test", "doc" and "clean" are supported.  The
 "doc" target creates HTML documentation (with make target "html"), and
@@ -96,8 +114,6 @@ To build and run the test code, simply execute from the shell::
 ToDo
 ----
 
-  * Write tests for 3D typemaps.
-
   * Add ARGOUT typemaps that assume the function allocates the buffers
     internally.
 
diff --git a/numpy/doc/swig/numpy_swig.html b/numpy/doc/swig/numpy_swig.html
index c975ce417..8f292d446 100644
--- a/numpy/doc/swig/numpy_swig.html
+++ b/numpy/doc/swig/numpy_swig.html
@@ -5,7 +5,7 @@
 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
 <title>numpy.i: a SWIG Interface File for NumPy</title>
 <meta name="author" content="Bill Spotz" />
-<meta name="date" content="3 April, 2007" />
+<meta name="date" content="4 April, 2007" />
 <style type="text/css">
 
 /*
@@ -302,7 +302,7 @@ ul.auto-toc {
 <tr class="field"><th class="docinfo-name">Institution:</th><td class="field-body">Sandia National Laboratories</td>
 </tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>3 April, 2007</td></tr>
+<td>4 April, 2007</td></tr>
 </tbody>
 </table>
 <div class="contents topic">
@@ -567,12 +567,15 @@ of array.  The input array signatures are</p>
 <li><tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">IN_ARRAY2[ANY][ANY])</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(DATA_TYPE*</span> <span class="pre">IN_ARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2)</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY2)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">IN_ARRAY3[ANY][ANY][ANY])</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(DATA_TYPE*</span> <span class="pre">IN_ARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">IN_ARRAY3)</span></tt></li>
 </ul>
 </blockquote>
 <p>The first signature listed, <tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">IN_ARRAY[ANY])</span></tt> is for
 one-dimensional arrays with hard-coded dimensions.  Likewise,
 <tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">IN_ARRAY2[ANY][ANY])</span></tt> is for two-dimensional arrays with
-hard-coded dimensions.</p>
+hard-coded dimensions, and similarly for three-dimensional.</p>
 </div>
 <div class="section">
 <h2><a class="toc-backref" href="#id5" id="in-place-arrays" name="in-place-arrays">In-Place Arrays</a></h2>
@@ -589,6 +592,9 @@ signatures are</p>
 <li><tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">INPLACE_ARRAY2[ANY][ANY])</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY2,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2)</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY2)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">INPLACE_ARRAY3[ANY][ANY][ANY])</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY3,</span> <span class="pre">int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3)</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(int</span> <span class="pre">DIM1,</span> <span class="pre">int</span> <span class="pre">DIM2,</span> <span class="pre">int</span> <span class="pre">DIM3,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">INPLACE_ARRAY3)</span></tt></li>
 </ul>
 </blockquote>
 <p>These typemaps now check to make sure that the <tt class="docutils literal"><span class="pre">INPLACE_ARRAY</span></tt>
@@ -612,14 +618,15 @@ arrays in, they simply get returned.  The argout signatures are</p>
 <li><tt class="docutils literal"><span class="pre">(DATA_TYPE*</span> <span class="pre">ARGOUT_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1)</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(int</span> <span class="pre">DIM1,</span> <span class="pre">DATA_TYPE*</span> <span class="pre">ARGOUT_ARRAY1)</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY2[ANY][ANY])</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">(DATA_TYPE</span> <span class="pre">ARGOUT_ARRAY3[ANY][ANY][ANY])</span></tt></li>
 </ul>
 </blockquote>
 <p>These are typically used in situations where in C/C++, you would
 allocate a(n) array(s) on the heap, and call the function to fill the
 array(s) values.  In python, the arrays are allocated for you and
 returned as new array objects.</p>
-<p>Note that we support <tt class="docutils literal"><span class="pre">DATA_TYPE*</span></tt> argout typemaps in 1D, but not
-2D.  This because of a quirk with the <a class="reference" href="http://www.swig.org">SWIG</a> typemap syntax and
+<p>Note that we support <tt class="docutils literal"><span class="pre">DATA_TYPE*</span></tt> argout typemaps in 1D, but not 2D
+or 3D.  This because of a quirk with the <a class="reference" href="http://www.swig.org">SWIG</a> typemap syntax and
 cannot be avoided.  Note that for these types of 1D typemaps, the
 python function will take a single argument representing <tt class="docutils literal"><span class="pre">DIM1</span></tt>.</p>
 </div>
@@ -851,10 +858,10 @@ example):</p>
 </pre>
 </li>
 <li><p class="first">You can use the code in <tt class="docutils literal"><span class="pre">numpy.i</span></tt> to write your own typemaps.
-For example, if you had a three-dimensional array as a function
-argument, you could cut-and-paste the appropriate two-dimensional
-typemap into your interface file.  The modifications for the third
-dimension would be trivial.</p>
+For example, if you had a four-dimensional array as a function
+argument, you could cut-and-paste the appropriate
+three-dimensional typemaps into your interface file.  The
+modifications for the fourth dimension would be trivial.</p>
 </li>
 <li><p class="first">Sometimes, the best approach is to use the <tt class="docutils literal"><span class="pre">%extend</span></tt> directive
 to define new methods for your classes (or overload existing ones)
@@ -899,9 +906,9 @@ between <a class="reference" href="http://numpy.scipy.org">NumPy</a> arrays and
 <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">char</span></tt>, <tt class="docutils literal"><span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">short</span></tt>, <tt class="docutils literal"><span class="pre">int</span></tt>,
 <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">long</span> <span class="pre">long</span></tt>,
 <tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt> and <tt class="docutils literal"><span class="pre">double</span></tt>.</li>
-<li>That support 16 different argument signatures for each data type,
+<li>That support 23 different argument signatures for each data type,
 including:<ul>
-<li>One-dimensional and two-dimensional arrays.</li>
+<li>One-dimensional, two-dimensional and three-dimensional arrays.</li>
 <li>Input-only, in-place, and argout behavior.</li>
 <li>Hard-coded dimensions, data-buffer-then-dimensions
 specification, and dimensions-then-data-buffer specification.</li>
@@ -914,7 +921,7 @@ wrapper developers, including:</p>
 <blockquote>
 <ul class="simple">
 <li>A <a class="reference" href="http://www.swig.org">SWIG</a> macro (<tt class="docutils literal"><span class="pre">%numpy_typemaps</span></tt>) with three arguments for
-implementing the 16 argument signatures for the user's choice of
+implementing the 23 argument signatures for the user's choice of
 (1) C data type, (2) <a class="reference" href="http://numpy.scipy.org">NumPy</a> data type (assuming they match), and
 (3) dimension type.</li>
 <li>Seven C macros and eleven C functions that can be used to write
@@ -938,7 +945,7 @@ possible.</p>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2007-04-04 16:10 UTC.
+Generated on: 2007-04-04 22:57 UTC.
 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 
 </div>
diff --git a/numpy/doc/swig/numpy_swig.pdf b/numpy/doc/swig/numpy_swig.pdf
index 615130c38..bff02a8c4 100644
--- a/numpy/doc/swig/numpy_swig.pdf
+++ b/numpy/doc/swig/numpy_swig.pdf
diff --git a/numpy/doc/swig/numpy_swig.txt b/numpy/doc/swig/numpy_swig.txt
index ce42bbc9e..f3885ddde 100644
--- a/numpy/doc/swig/numpy_swig.txt
+++ b/numpy/doc/swig/numpy_swig.txt
@@ -4,7 +4,7 @@ numpy.i: a SWIG Interface File for NumPy
 
 :Author:      Bill Spotz
 :Institution: Sandia National Laboratories
-:Date:        3 April, 2007
+:Date:        4 April, 2007
 
 .. contents::
 
@@ -252,11 +252,14 @@ of array.  The input array signatures are
   * ``(DATA_TYPE IN_ARRAY2[ANY][ANY])``
   * ``(DATA_TYPE* IN_ARRAY2, int DIM1, int DIM2)``
   * ``(int DIM1, int DIM2, DATA_TYPE* IN_ARRAY2)``
+  * ``(DATA_TYPE IN_ARRAY3[ANY][ANY][ANY])``
+  * ``(DATA_TYPE* IN_ARRAY3, int DIM1, int DIM2, int DIM3)``
+  * ``(int DIM1, int DIM2, int DIM3, DATA_TYPE* IN_ARRAY3)``
 
 The first signature listed, ``(DATA_TYPE IN_ARRAY[ANY])`` is for
 one-dimensional arrays with hard-coded dimensions.  Likewise,
 ``(DATA_TYPE IN_ARRAY2[ANY][ANY])`` is for two-dimensional arrays with
-hard-coded dimensions.
+hard-coded dimensions, and similarly for three-dimensional.
 
 In-Place Arrays
 ---------------
@@ -273,6 +276,9 @@ signatures are
   * ``(DATA_TYPE INPLACE_ARRAY2[ANY][ANY])``
   * ``(DATA_TYPE* INPLACE_ARRAY2, int DIM1, int DIM2)``
   * ``(int DIM1, int DIM2, DATA_TYPE* INPLACE_ARRAY2)``
+  * ``(DATA_TYPE INPLACE_ARRAY3[ANY][ANY][ANY])``
+  * ``(DATA_TYPE* INPLACE_ARRAY3, int DIM1, int DIM2, int DIM3)``
+  * ``(int DIM1, int DIM2, int DIM3, DATA_TYPE* INPLACE_ARRAY3)``
 
 These typemaps now check to make sure that the ``INPLACE_ARRAY``
 arguments use native byte ordering.  If not, an exception is raised.
@@ -295,14 +301,15 @@ arrays in, they simply get returned.  The argout signatures are
   * ``(DATA_TYPE* ARGOUT_ARRAY1, int DIM1)``
   * ``(int DIM1, DATA_TYPE* ARGOUT_ARRAY1)``
   * ``(DATA_TYPE ARGOUT_ARRAY2[ANY][ANY])``
+  * ``(DATA_TYPE ARGOUT_ARRAY3[ANY][ANY][ANY])``
 
 These are typically used in situations where in C/C++, you would
 allocate a(n) array(s) on the heap, and call the function to fill the
 array(s) values.  In python, the arrays are allocated for you and
 returned as new array objects.
 
-Note that we support ``DATA_TYPE*`` argout typemaps in 1D, but not
-2D.  This because of a quirk with the `SWIG`_ typemap syntax and
+Note that we support ``DATA_TYPE*`` argout typemaps in 1D, but not 2D
+or 3D.  This because of a quirk with the `SWIG`_ typemap syntax and
 cannot be avoided.  Note that for these types of 1D typemaps, the
 python function will take a single argument representing ``DIM1``.
 
@@ -561,10 +568,10 @@ helpful when you encounter them.
         %numpy_typemaps(double, NPY_DOUBLE, long)
 
   * You can use the code in ``numpy.i`` to write your own typemaps.
-    For example, if you had a three-dimensional array as a function
-    argument, you could cut-and-paste the appropriate two-dimensional
-    typemap into your interface file.  The modifications for the third
-    dimension would be trivial.
+    For example, if you had a four-dimensional array as a function
+    argument, you could cut-and-paste the appropriate
+    three-dimensional typemaps into your interface file.  The
+    modifications for the fourth dimension would be trivial.
 
   * Sometimes, the best approach is to use the ``%extend`` directive
     to define new methods for your classes (or overload existing ones)
@@ -607,10 +614,10 @@ between `NumPy`_ arrays and C arrays:
     ``unsigned int``, ``long``, ``unsigned long``, ``long long``,
     ``unsigned long long``, ``float`` and ``double``.
 
-  * That support 16 different argument signatures for each data type,
+  * That support 23 different argument signatures for each data type,
     including:
 
-    + One-dimensional and two-dimensional arrays.
+    + One-dimensional, two-dimensional and three-dimensional arrays.
 
     + Input-only, in-place, and argout behavior.
 
@@ -621,7 +628,7 @@ The ``numpy.i`` interface file also provides additional tools for
 wrapper developers, including:
 
   * A `SWIG`_ macro (``%numpy_typemaps``) with three arguments for
-    implementing the 16 argument signatures for the user's choice of
+    implementing the 23 argument signatures for the user's choice of
     (1) C data type, (2) `NumPy`_ data type (assuming they match), and
     (3) dimension type.