Added typemap signatures where the dimensions come before the data pointer

1 files changed, 39 insertions, 12 deletions

diff --git a/numpy/doc/swig/numpy_swig.html b/numpy/doc/swig/numpy_swig.html
index 73fec1875..393bd6281 100644
--- a/numpy/doc/swig/numpy_swig.html
+++ b/numpy/doc/swig/numpy_swig.html
@@ -351,9 +351,16 @@ named <tt class="docutils literal"><span class="pre">rms.h</span></tt>.  To obta
 <a class="reference" href="http://www.swig.org">SWIG</a> interface file would need the following:</p>
 <pre class="literal-block">
 %{
+#define SWIG_FILE_WITH_INIT
 #include &quot;rms.h&quot;
 %}
+
 %include &quot;numpy.i&quot;
+
+%init %{
+import_array();
+%}
+
 %apply (double* IN_ARRAY1, int DIM1) {(double* seq, int n)};
 %include &quot;rms.h&quot;
 </pre>
@@ -365,19 +372,30 @@ argument names are intended to suggest that the <tt class="docutils literal"><sp
 is an input array of one dimension and that the <tt class="docutils literal"><span class="pre">int</span></tt> represents
 that dimension.  This is precisely the pattern in the <tt class="docutils literal"><span class="pre">rms</span></tt>
 prototype.</p>
-<p>Hopefully, no actual prototypes to be wrapped will have the names
+<p>Most likely, no actual prototypes to be wrapped will have the names
 <tt class="docutils literal"><span class="pre">IN_ARRAY1</span></tt> and <tt class="docutils literal"><span class="pre">DIM1</span></tt>.  We use the <tt class="docutils literal"><span class="pre">%apply</span></tt> directive to apply
 the typemap for one-dimensional input arrays of type <tt class="docutils literal"><span class="pre">double</span></tt> to the
 actual prototype used by <tt class="docutils literal"><span class="pre">rms</span></tt>.  Using <tt class="docutils literal"><span class="pre">numpy.i</span></tt> effectively,
 therefore, requires knowing what typemaps are available and what they
 do.</p>
+<p>Note that if the C function signature was in a different order:</p>
+<pre class="literal-block">
+double rms(int n, double* seq);
+</pre>
+<p>that <a class="reference" href="http://www.swig.org">SWIG</a> would not match the typemap signature given above with
+the argument list for <tt class="docutils literal"><span class="pre">rms</span></tt>.  Fortunately, <tt class="docutils literal"><span class="pre">numpy.i</span></tt> has a set of
+typemaps with the data pointer given last:</p>
+<pre class="literal-block">
+%apply (int DIM1, double* IN_ARRAY1) {(int n, double* seq)};
+</pre>
 </div>
 <div class="section">
 <h1><a id="using-numpy-i" name="using-numpy-i">Using numpy.i</a></h1>
 <p>The <tt class="docutils literal"><span class="pre">numpy.i</span></tt> file is currently located in the <tt class="docutils literal"><span class="pre">numpy/docs/swig</span></tt>
 sub-directory under the <tt class="docutils literal"><span class="pre">numpy</span></tt> installation directory.  Typically,
 you will want to copy it to the directory where you are developing
-your wrappers.</p>
+your wrappers.  If it is ever adopted by <a class="reference" href="http://www.swig.org">SWIG</a> developers, then it
+will be installed in a standard place where <a class="reference" href="http://www.swig.org">SWIG</a> can find it.</p>
 <p>A simple module that only uses a single <a class="reference" href="http://www.swig.org">SWIG</a> interface file should
 include the following:</p>
 <pre class="literal-block">
@@ -389,17 +407,22 @@ include the following:</p>
 import_array();
 %}
 </pre>
-<p>Only one interface file should call <tt class="docutils literal"><span class="pre">import_array()</span></tt>.  If you have
-more than one <a class="reference" href="http://www.swig.org">SWIG</a> interface file, then subsequent files should not
-<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></tt> and should not call
-<tt class="docutils literal"><span class="pre">import_array()</span></tt>.</p>
+<p>Within a compiled python module, <tt class="docutils literal"><span class="pre">import_array()</span></tt> should only get
+called once.  This could be in a C/C++ file that you have written and
+is linked to the module.  If this is the case, then none of your
+interface files should <tt class="docutils literal"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></tt> or call
+<tt class="docutils literal"><span class="pre">import_array()</span></tt>.  Or, this initialization call could be in a
+wrapper file generated by <a class="reference" href="http://www.swig.org">SWIG</a> from an interface file that has the
+<tt class="docutils literal"><span class="pre">%init</span></tt> block as above.  If this is the case, and you have more than
+one <a class="reference" href="http://www.swig.org">SWIG</a> interface file, then only one interface file should
+<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">SWIG_FILE_WITH_INIT</span></tt> and call <tt class="docutils literal"><span class="pre">import_array()</span></tt>.</p>
 </div>
 <div class="section">
 <h1><a id="available-typemaps" name="available-typemaps">Available Typemaps</a></h1>
 <p>The typemap directives provided by <tt class="docutils literal"><span class="pre">numpy.i</span></tt> for arrays of different
 data types, say <tt class="docutils literal"><span class="pre">double</span></tt> and <tt class="docutils literal"><span class="pre">int</span></tt>, are identical to one another
 except for the C and <a class="reference" href="http://numpy.scipy.org">NumPy</a> type specifications.  The typemaps are
-therefore implemented via a macro:</p>
+therefore implemented (typically behind the scenes) via a macro:</p>
 <pre class="literal-block">
 %numpy_typemaps(TYPE, TYPECODE)
 </pre>
@@ -442,7 +465,7 @@ expansion:</p>
 %numpy_typemaps(bool, NPY_UINT)
 </pre>
 <p>to fix the data length problem, and <a class="reference" href="#input-arrays">Input Arrays</a> will work fine,
-but <a class="reference" href="#in-place-arrays">In-place Arrays</a> will fail type-checking.</p>
+but <a class="reference" href="#in-place-arrays">In-place Arrays</a> might fail type-checking.</p>
 <p>In the following descriptions, we reference a generic <tt class="docutils literal"><span class="pre">TYPE</span></tt>, which
 could be any of the C-types listed above.</p>
 <div class="section">
@@ -456,6 +479,8 @@ of array.  The input array signatures are</p>
 <ul class="simple">
 <li><tt class="docutils literal"><span class="pre">(TYPE*</span> <span class="pre">IN_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1)</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(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">TYPE*</span> <span class="pre">IN_ARRAY1)</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">TYPE*</span> <span class="pre">IN_ARRAY2)</span></tt></li>
 </ul>
 </blockquote>
 </div>
@@ -470,6 +495,8 @@ signatures are</p>
 <ul class="simple">
 <li><tt class="docutils literal"><span class="pre">(TYPE*</span> <span class="pre">INPLACE_ARRAY1,</span> <span class="pre">int</span> <span class="pre">DIM1)</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">(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">TYPE*</span> <span class="pre">INPLACE_ARRAY1)</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">TYPE*</span> <span class="pre">INPLACE_ARRAY2)</span></tt></li>
 </ul>
 </blockquote>
 </div>
@@ -481,9 +508,9 @@ more than one output variable and the single return argument is
 therefore not sufficient.  In python, the convential way to return
 multiple arguments is to pack them into a tuple and return the tuple.
 This is what the argout typemaps do.  If a wrapped function that uses
-argout these argout typemaps has more than one return argument, they
-are so packed.  The python user does not pass these arrays in, they
-simply get returned.  The argout signatures are</p>
+these argout typemaps has more than one return argument, they are so
+packed.  The python user does not pass these arrays in, they simply
+get returned.  The argout signatures are</p>
 <blockquote>
 <ul class="simple">
 <li><tt class="docutils literal"><span class="pre">(TYPE</span> <span class="pre">ARGOUT_ARRAY1[ANY])</span></tt></li>
@@ -596,7 +623,7 @@ result possible.</p>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2007-03-14 15:24 UTC.
+Generated on: 2007-03-14 19:50 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>