blitz_2.html

A C++ class library for scientific computing

...
</pre></td></tr></table></P><P>

<HR SIZE="6">
<A NAME="SEC46"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC45"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC47"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC47"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC41"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.5 Referencing another array </H3>
<!--docid::SEC46::-->
<P>

This constructor makes a shared view of another array's data:
<A NAME="IDX25"></A>
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array(Array&#60;T_numtype, N_rank&#62;&#38; array);
</pre></td></tr></table></P><P>

After this constructor is used, both <CODE>Array</CODE> objects refer to the
<EM>same data</EM>.  Any changes made to one array will appear in the other
array.  If you want to make a duplicate copy of an array, use the
<CODE>copy()</CODE> member function.
</P><P>

<HR SIZE="6">
<A NAME="SEC47"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC46"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC48"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC48"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC41"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.6 Constructing an array from an expression </H3>
<!--docid::SEC47::-->
<P>

Arrays may be constructed from expressions, which are described in
<A HREF="blitz_3.html#SEC81">3.1 Expression evaluation order</A>.  The syntax is:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array(...array expression...);
</pre></td></tr></table></P><P>

For example, this code creates an array B which contains the square roots of
the elements in A:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;float,2&#62; A(N,N);   // ...
Array&#60;float,2&#62; B(sqrt(A));
</pre></td></tr></table></P><P>

<HR SIZE="6">
<A NAME="SEC48"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC47"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC49"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC49"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC41"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.7 Creating an array from pre-existing data </H3>
<!--docid::SEC48::-->
<P>

When creating an array using a pointer to already existing data, you have
three choices for how Blitz++ will handle the data.  These choices are
enumerated by the enum type <CODE>preexistingMemoryPolicy</CODE>:
<A NAME="IDX26"></A>
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>enum preexistingMemoryPolicy { 
  duplicateData, 
  deleteDataWhenDone, 
  neverDeleteData 
};
</pre></td></tr></table><A NAME="IDX27"></A>
<A NAME="IDX28"></A>
<A NAME="IDX29"></A>
<A NAME="IDX30"></A>
</P><P>

If you choose <CODE>duplicateData</CODE>, Blitz++ will create an array object
using a copy of the data you provide.  If you choose
<CODE>deleteDataWhenDone</CODE>, Blitz++ will not create a copy of the data; and
when no array objects refer to the data anymore, it will deallocate the data
using <CODE>delete []</CODE>.  Note that to use <CODE>deleteDataWhenDone</CODE>, your
array data must have been allocated using the C++ <CODE>new</CODE> operator -- for
example, you cannot allocate array data using Fortran or <CODE>malloc</CODE>, then
create a Blitz++ array from it using the <CODE>deleteDataWhenDone</CODE> flag.
The third option is <CODE>neverDeleteData</CODE>, which means that Blitz++ will
not never deallocate the array data.  This means it is your responsibility
to determine when the array data is no longer needed, and deallocate it.
You should use this option for memory which has not been allocated using the
C++ <CODE>new</CODE> operator.
</P><P>

These constructors create array objects from pre-existing data:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array(T_numtype* dataFirst, TinyVector&#60;int, N_rank&#62; shape,
      preexistingMemoryPolicy deletePolicy);
Array(T_numtype* dataFirst, TinyVector&#60;int, N_rank&#62; shape,
      preexistingMemoryPolicy deletePolicy, 
      GeneralArrayStorage&#60;N_rank&#62; storage);
</pre></td></tr></table></P><P>

The first argument is a pointer to the array data.  It should point to the
element of the array which is stored first in memory.  The second argument
indicates the shape of the array.  You can create this argument using the
<CODE>shape()</CODE> function.  For example:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>double data[] = { 1, 2, 3, 4 };
Array&#60;double,2&#62; A(data, shape(2,2), neverDeleteData);   // Make a 2x2 array
</pre></td></tr></table></P><P>

<A NAME="IDX31"></A>
</P><P>

The <CODE>shape()</CODE> function takes N integer arguments and returns a
<CODE>TinyVector&#60;int,N&#62;</CODE>.
</P><P>

By default, Blitz++ arrays are row-major.  If you want to work with data
which is stored in column-major order (e.g. a Fortran array), use the second
version of the constructor: 
</P><P>

<A NAME="IDX32"></A>
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;double,2&#62; B(data, shape(2,2), neverDeleteData,
                  FortranArray&#60;2&#62;());
</pre></td></tr></table></P><P>

This is a tad awkward, so Blitz++ provides the global object
<CODE>fortranArray</CODE> which will convert to an instance of
<CODE>GeneralArrayStorage&#60;N_rank&#62;</CODE>:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;double,2&#62; B(data, shape(2,2), neverDeleteData, fortranArray);
</pre></td></tr></table></P><P>

Another version of this constructor allows you to pass an arbitrary
vector of strides:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array(T_numtype* _bz_restrict dataFirst, TinyVector&#60;int, N_rank&#62; shape,
      TinyVector&#60;int, N_rank&#62; stride, 
      preexistingMemoryPolicy deletePolicy,
      GeneralArrayStorage&#60;N_rank&#62; storage = GeneralArrayStorage&#60;N_rank&#62;())
</pre></td></tr></table></P><P>

<HR SIZE="6">
<A NAME="SEC49"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC48"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC50"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC50"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC41"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.8 Interlacing arrays </H3>
<!--docid::SEC49::-->
<P>

For some platforms, it can be advantageous to store a set of arrays
interlaced together in memory.  Blitz++ provides support for this through
the routines <CODE>interlaceArrays()</CODE> and <CODE>allocateArrays()</CODE>.  An
example:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,2&#62; A, B;
interlaceArrays(shape(10,10), A, B);
</pre></td></tr></table></P><P>

The first parameter of <CODE>interlaceArrays()</CODE> is the shape for the arrays
(10x10).  The subsequent arguments are the set of arrays to be interlaced
together.  Up to 11 arrays may be interlaced.  All arrays must store the
same data type and be of the same rank.  In the above example, storage is
allocated so that <CODE>A(0,0)</CODE> is followed immediately by <CODE>B(0,0)</CODE> in
memory, which is folloed by <CODE>A(0,1)</CODE> and <CODE>B(0,1)</CODE>, and so on.
</P><P>

A related routine is <CODE>allocateArrays()</CODE>, which has identical syntax:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,2&#62; A, B;
allocateArrays(shape(10,10), A, B);
</pre></td></tr></table></P><P>

Unlike <CODE>interlaceArrays()</CODE>, which always interlaces the arrays, the
routine <CODE>allocateArrays()</CODE> may or may not interlace them, depending on
whether interlacing is considered advantageous for your platform.  If the
tuning flag <CODE>BZ_INTERLACE_ARRAYS</CODE> is defined in
<CODE>&#60;blitz/tuning.h&#62;</CODE>, then the arrays are interlaced.
</P><P>

Note that the performance effects of interlacing are unpredictable: in some
situations it can be a benefit, and in most others it can slow your code
down substantially.  You should only use <CODE>interlaceArrays()</CODE> after
running some benchmarks to determine whether interlacing is beneficial for
your particular algorithm and architecture.
</P><P>

<HR SIZE="6">
<A NAME="SEC50"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC49"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC41"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.9 A note about reference counting </H3>
<!--docid::SEC50::-->
<P>

Blitz++ arrays use reference counting.  When you create a new array, a
memory block is allocated.  The <CODE>Array</CODE> object acts like a handle for
this memory block.  A memory block can be shared among multiple <CODE>Array</CODE>
objects -- for example, when you take subarrays and slices.  The memory
block keeps track of how many <CODE>Array</CODE> objects are referring to it.
When a memory block is orphaned -- when no <CODE>Array</CODE> objects are
referring to it -- it automatically deletes itself and frees the allocated
memory.
</P><P>

<A NAME="Array slicing"></A>
<HR SIZE="6">
<A NAME="SEC51"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC50"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC52"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC41"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC34"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC55"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 2.4 Indexing, subarrays, and slicing </H2>
<!--docid::SEC51::-->
<P>

This section describes how to access the elements of an array.  There are
three main ways:
</P><P>

<UL>

<LI><STRONG>Indexing</STRONG> obtains a single element
<P>

<LI>Creating a <STRONG>subarray</STRONG> which refers to a smaller portion of
an array 
<P>

<LI><STRONG>Slicing</STRONG> to produce a smaller-dimensional view of a portion
of an array 
<P>