blitz_2.html

A C++ class library for scientific computing

</UL>
<P>

Indexing, subarrays and slicing all use the overloaded parenthesis
<CODE>operator()</CODE>.
</P><P>

As a running example, we'll consider the three dimensional array pictured
below, which has index ranges (0..7, 0..7, 0..7).  Shaded portions of the
array show regions which have been obtained by indexing, creating a
subarray, and slicing.
</P><P>

<center>
 <CENTER><IMG SRC="slice.gif" ALT="slice"></CENTER>
</center>
<center>
 Examples of array indexing, subarrays, and slicing.
</center>
</P><P>

<HR SIZE="6">
<A NAME="SEC52"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC51"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC53"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC34"> &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_3.html#SEC80"> &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.4.1 Indexing </H3>
<!--docid::SEC52::-->
<P>

There are two ways to get a single element from an array.  The simplest is
to provide a set of integer operands to <CODE>operator()</CODE>:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>A(7,0,0) = 5;    
cout &#60;&#60; "A(7,0,0) = " &#60;&#60; A(7,0,0) &#60;&#60; endl;
</pre></td></tr></table></P><P>

This version of indexing is available for arrays of rank one through eleven.
If the array object isn't <CODE>const</CODE>, the return type of
<CODE>operator()</CODE> is a reference; if the array object is <CODE>const</CODE>, the
return type is a value.
</P><P>

You can also get an element by providing an operand of type
<CODE>TinyVector&#60;int,N_rank&#62;</CODE> where <CODE>N_rank</CODE> is the rank of the array
object:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>TinyVector&#60;int,3&#62; index;
index = 7, 0, 0;
A(index) = 5;
cout &#60;&#60; "A(7,0,0) = " &#60;&#60; A(index) &#60;&#60; endl;
</pre></td></tr></table></P><P>

This version of <CODE>operator()</CODE> is also available in a const-overloaded
version.
</P><P>

It's possible to use fewer than <CODE>N_rank</CODE> indices.  However, missing
indices are <STRONG>assumed to be zero</STRONG>, which will cause bounds errors if
the valid index range does not include zero (e.g. Fortran arrays).  For this
reason, and for code clarity, it's a bad idea to omit indices.
</P><P>

<HR SIZE="6">
<A NAME="SEC53"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC52"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC54"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC54"> &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_3.html#SEC80"> &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.4.2 Subarrays </H3>
<!--docid::SEC53::-->
<P>

You can obtain a subarray by providing <CODE>Range</CODE> operands to
<CODE>operator()</CODE>.  A <CODE>Range</CODE> object represents a set of regularly
spaced index values.  For example,
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,3&#62; B = A(Range(5,7), Range(5,7), Range(0,2));
</pre></td></tr></table></P><P>

The object B now refers to elements (5..7,5..7,0..2) of the array A.
</P><P>

The returned subarray is of type <CODE>Array&#60;T_numtype,N_rank&#62;</CODE>. This means
that subarrays can be used wherever arrays can be: in expressions, as
lvalues, etc.  Some examples:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>// A three-dimensional stencil (used in solving PDEs)
Range I(1,6), J(1,6), K(1,6);
B = (A(I,J,K) + A(I+1,J,K) + A(I-1,J,K) + A(I,J+1,K)
 + A(I,J-1,K) + A(I,J+1,K) + A(I,J,K+1) + A(I,J,K-1)) / 7.0;

// Set a subarray of A to zero
A(Range(5,7), Range(5,7), Range(5,7)) = 0.;
</pre></td></tr></table></P><P>

The bases of the subarray are equal to the bases of the original array:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,2&#62; D(Range(1,5), Range(1,5));     // 1..5, 1..5
Array&#60;int,2&#62; E = D(Range(2,3), Range(2,3)); // 1..2, 1..2
</pre></td></tr></table></P><P>

An array can be used on both sides of an expression only if the subarrays
don't overlap.  If the arrays overlap, the result may depend on the order in
which the array is traversed.  
</P><P>

<HR SIZE="6">
<A NAME="SEC54"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC53"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC55"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC55"> &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_3.html#SEC80"> &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.4.3 RectDomain and StridedDomain </H3>
<!--docid::SEC54::-->
<P>

The classes <CODE>RectDomain</CODE> and <CODE>StridedDomain</CODE>, defined in
<CODE>blitz/domain.h</CODE>, offer a dimension-independent notation for subarrays.
</P><P>

<CODE>RectDomain</CODE> and <CODE>StridedDomain</CODE> can be thought of as a
<CODE>TinyVector&#60;Range,N&#62;</CODE>.  Both have a vector of lower- and upper-bounds;
<CODE>StridedDomain</CODE> has a stride vector.  For example, the subarray:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,2&#62; B = A(Range(4,7), Range(8,11));  // 4..7, 8..11
</pre></td></tr></table></P><P>

could be obtained using <CODE>RectDomain</CODE> this way:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>TinyVector&#60;int,2&#62; lowerBounds(4, 8);
TinyVector&#60;int,2&#62; upperBounds(7, 11);
RectDomain&#60;2&#62; subdomain(lowerBounds, upperBounds);

Array&#60;int,2&#62; B = A(subdomain);
</pre></td></tr></table></P><P>

Here are the prototypes of <CODE>RectDomain</CODE> and <CODE>StridedDomain</CODE>.
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>template&#60;int N_rank&#62;
class RectDomain {

public:
    RectDomain(const TinyVector&#60;int,N_rank&#62;&#38; lbound,
        const TinyVector&#60;int,N_rank&#62;&#38; ubound);

    const TinyVector&#60;int,N_rank&#62;&#38; lbound() const;
    int lbound(int i) const;
    const TinyVector&#60;int,N_rank&#62;&#38; ubound() const;
    int ubound(int i) const;
    Range operator[](int rank) const;
    void shrink(int amount);
    void shrink(int dim, int amount);
    void expand(int amount);
    void expand(int dim, int amount);
};

template&#60;int N_rank&#62;
class StridedDomain {

public:
    StridedDomain(const TinyVector&#60;int,N_rank&#62;&#38; lbound,
        const TinyVector&#60;int,N_rank&#62;&#38; ubound,
        const TinyVector&#60;int,N_rank&#62;&#38; stride);

    const TinyVector&#60;int,N_rank&#62;&#38; lbound() const;
    int lbound(int i) const;
    const TinyVector&#60;int,N_rank&#62;&#38; ubound() const;
    int ubound(int i) const;
    const TinyVector&#60;int,N_rank&#62;&#38; stride() const;
    int stride(int i) const;
    Range operator[](int rank) const;
    void shrink(int amount);
    void shrink(int dim, int amount);
    void expand(int amount);
    void expand(int dim, int amount);
};
</pre></td></tr></table></P><P>

<A NAME="Slicing combo"></A>
<HR SIZE="6">
<A NAME="SEC55"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC54"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC56"> &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#SEC34"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC59"> &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.4.4 Slicing </H3>
<!--docid::SEC55::-->
<P>

A combination of integer and Range operands produces a <STRONG>slice</STRONG>.  Each
integer operand reduces the rank of the array by one.  For example:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,2&#62; F = A(Range::all(), 2, Range::all());
Array&#60;int,1&#62; G = A(2,            7, Range::all());
</pre></td></tr></table></P><P>

Range and integer operands can be used in any combination, for arrays
up to rank 11.
</P><P>

<STRONG>Note:</STRONG> Using a combination of integer and Range operands requires a
newer language feature (partial ordering of member templates) which not all
compilers support.  If your compiler does provide this feature,
<CODE>BZ_PARTIAL_ORDERING</CODE> will be defined in <CODE>&#60;blitz/config.h&#62;</CODE>.  If
not, you can use this workaround:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Array&#60;int,3&#62; F = A(Range::all(), Range(2,2), Range::all());
Array&#60;int,3&#62; G = A(Range(2,2),   Range(7,7), Range::all());
</pre></td></tr></table></P><P>

<HR SIZE="6">
<A NAME="SEC56"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC55"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC57"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC57"> &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_3.html#SEC80"> &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.4.5 More about Range objects </H3>
<!--docid::SEC56::-->
<P>

A <CODE>Range</CODE> object represents an ordered set of uniformly spaced
integers.  Here are some examples of using Range objects to obtain
subarrays:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>#include &#60;blitz/array.h&#62;

using namespace blitz;

int main()
{
    Array&#60;int,1&#62; A(7);
    A = 0, 1, 2, 3, 4, 5, 6;

    cout &#60;&#60; A(Range::all())  &#60;&#60; endl          // [ 0 1 2 3 4 5 6 ]
         &#60;&#60; A(Range(3,5))    &#60;&#60; endl          // [ 3 4 5 ]
         &#60;&#60; A(Range(3,toEnd)) &#60;&#60; endl         // [ 3 4 5 6 ]
         &#60;&#60; A(Range(fromStart,3)) &#60;&#60; endl     // [ 0 1 2 3 ]
         &#60;&#60; A(Range(1,5,2)) &#60;&#60; endl           // [ 1 3 5 ]
         &#60;&#60; A(Range(5,1,-2)) &#60;&#60; endl          // [ 5 3 1 ]