blitz_2.html

A C++ class library for scientific computing

         << A(Range(fromStart,toEnd,2)) << endl;    // [ 0 2 4 6 ]

    return 0;
}
</FONT></pre></td></tr></table></P><P>

The optional third constructor argument specifies a stride.  For example,
<CODE>Range(1,5,2)</CODE> refers to elements [1 3 5].  Strides can also be
negative: <CODE>Range(5,1,-2)</CODE> refers to elements [5 3 1].
</P><P>

Note that if you use the same Range frequently, you can just construct one
object and use it multiple times.  For example:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>Range all = Range::all();
A(0,all,all) = A(N-1,all,all);
A(all,0,all) = A(all,N-1,all);
A(all,all,0) = A(all,all,N-1);
</pre></td></tr></table></P><P>

Here's an example of using strides with a two-dimensional
array:
</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,2&#62; A(8,8);
    A = 0;

    Array&#60;int,2&#62; B = A(Range(1,7,3), Range(1,5,2));
    B = 1;

    cout &#60;&#60; "A = " &#60;&#60; A &#60;&#60; endl;
    return 0;
}

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

Here's an illustration of the <CODE>B</CODE> subarray:
</P><P>

<center>
 <CENTER><IMG SRC="strideslice.gif" ALT="strideslice"></CENTER>
</center>
<center>
 Using strides to create non-contiguous subarrays.
</center>
</P><P>

And the program output:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>A = 8 x 8
[         0         0         0         0         0         0         0 
          0 
          0         1         0         1         0         1         0 
          0 
          0         0         0         0         0         0         0 
          0 
          0         0         0         0         0         0         0 
          0 
          0         1         0         1         0         1         0 
          0 
          0         0         0         0         0         0         0 
          0 
          0         0         0         0         0         0         0 
          0 
          0         1         0         1         0         1         0 
          0 ]

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

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

The assignment operator (<CODE>=</CODE>) always results in the expression on the
right-hand side (rhs) being <EM>copied</EM> to the lhs (i.e. the data on the
lhs is overwritten with the result from the rhs).  This is different from
some array packages in which the assignment operator makes the lhs a
reference (or alias) to the rhs.  To further confuse the issue, the copy
constructor for arrays <EM>does</EM> have reference semantics.  Here's an
example which should clarify things:
</P><P>

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

Statement 1 results in a portion of <CODE>B</CODE>'s data being copied into
<CODE>A</CODE>.  After Statement 1, both <CODE>A</CODE> and <CODE>B</CODE> have their own
(nonoverlapping) blocks of data.  Contrast this behaviour with that of
Statement 2, which is <STRONG>not</STRONG> an assignment (it uses the copy
constructor).  After Statement 2 is executed, the array <CODE>C</CODE> is a
reference (or alias) to <CODE>B</CODE>'s data.
</P><P>

So to summarize: If you want to copy the rhs, use an assignment operator.
If you want to reference (or alias) the rhs, use the copy constructor (or
alternately, the <CODE>reference()</CODE> member function in <A HREF="blitz_2.html#SEC60">2.6 Member functions</A>).
</P><P>

<STRONG>Very important:</STRONG> whenever you have an assignment operator (<CODE>=</CODE>,
<CODE>+=</CODE>, <CODE>-=</CODE>, etc.) the lhs <STRONG>must</STRONG> have the same shape as the
<STRONG>rhs</STRONG>.  If you want the array on the left hand side to be resized to
the proper shape, you must do so by calling the <CODE>resize</CODE> method, for
example:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>A.resize(B.shape());    // Make A the same size as B
A = B;
</pre></td></tr></table></P><P>

<HR SIZE="6">
<A NAME="SEC58"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC57"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC59"> &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.7 An example </H3>
<!--docid::SEC58::-->
<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,2&#62; A(6,6), B(3,3);
  
    // Set the upper left quadrant of A to 5 
    A(Range(0,2), Range(0,2)) = 5; 

    // Set the upper right quadrant of A to an identity matrix
    B = 1, 0, 0,
        0, 1, 0,
        0, 0, 1;
    A(Range(0,2), Range(3,5)) = B;

    // Set the fourth row to 1
    A(3, Range::all()) = 1;

    // Set the last two rows to 0
    A(Range(4, Range::toEnd), Range::all()) = 0;

    // Set the bottom right element to 8
    A(5,5) = 8;

    cout &#60;&#60; "A = " &#60;&#60; A &#60;&#60; endl;

    return 0;
}

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

The output:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>A = 6 x 6
[         5         5         5         1         0         0 
          5         5         5         0         1         0 
          5         5         5         0         0         1 
          1         1         1         1         1         1 
          0         0         0         0         0         0 
          0         0         0         0         0         8 ]

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

<A NAME="Array debug"></A>
<HR SIZE="6">
<A NAME="SEC59"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC58"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC60"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC60"> &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>
<H2> 2.5 Debug mode </H2>
<!--docid::SEC59::-->
<P>

The Blitz++ library has a debugging mode which is enabled by defining the
preprocessor symbol <CODE>BZ_DEBUG</CODE>.  For most compilers, the command line
argument <CODE>-DBZ_DEBUG</CODE> should work.
</P><P>

In debugging mode, your programs will run <EM>very slowly</EM>.  This is
because Blitz++ is doing lots of precondition checking and bounds checking.
When it detects something fishy, it will likely halt your program and
display an error message.
</P><P>

For example, this program attempts to access an element of a 4x4 array which
doesn't exist:
</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;complex&#60;float&#62;, 2&#62; Z(4,4);

    Z = complex&#60;float&#62;(0.0, 1.0);

    Z(4,4) = complex&#60;float&#62;(1.0, 0.0);

    return 0;
}

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

When compiled with <CODE>-DBZ_DEBUG</CODE>, the out of bounds indices are detected
and an error message results:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>[Blitz++] Precondition failure: Module ../../blitz/array-impl.h line 1282
Array index out of range: (4, 4)
Lower bounds: 2 [          0         0 ]
Length:       2 [          4         4 ]

debug: ../../blitz/array-impl.h:1282: bool blitz::Array&#60;T, 
N&#62;::assertInRange(int, int) const [with P_numtype = std::complex&#60;float&#62;, int 
N_rank = 2]: Assertion `0' failed.
</FONT></pre></td></tr></table></P><P>

Precondition failures send their error messages to the standard error stream
(<CODE>cerr</CODE>).  After displaying the error message, <CODE>assert(0)</CODE> is
invoked.  
</P><P>

<A NAME="Array members"></A>
<HR SIZE="6">
<A NAME="SEC60"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC59"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC61"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC64"> &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#SEC64"> &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.6 Member functions </H2>
<!--docid::SEC60::-->
<P>

<HR SIZE="6">
<A NAME="SEC61"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="blitz_2.html#SEC60"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A H