2.3 Constructors

2.3.1 Default constructor

Array();
Array(GeneralArrayStorage<N_rank> storage)

The default constructor creates a C-style array of zero size. Any attempt to access data in the array may result in a run-time error, because there isn’t any data to access!

An optional argument specifies a storage order for the array.

Arrays created using the default constructor can subsequently be given data by the resize(), resizeAndPreserve(), or reference() member functions.

2.3.2 Creating an array from an expression

Array(expression...)

You may create an array from an array expression. For example,

Array<float,2> A(4,3), B(4,3);   // ...
Array<float,2> C(A*2.0+B);

This is an explicit constructor (it will not be used to perform implicit type conversions). The newly constructed array will have the same storage format as the arrays in the expression. If arrays with different storage formats appear in the expression, an error will result. (In this case, you must first construct the array, then assign the expression to it).

2.3.3 Constructors which take extent parameters

Array(int extent1);
Array(int extent1, int extent2);
Array(int extent1, int extent2, int extent3);
...
Array(int extent1, int extent2, int extent3, ..., int extent11)

These constructors take arguments which specify the size of the array to be constructed. You should provide as many arguments as there are dimensions in the array.¹

An optional last parameter specifies a storage format:

Array(int extent1, GeneralArrayStorage<N_rank> storage);
Array(int extent1, int extent2, GeneralArrayStorage<N_rank> storage);
...

For high-rank arrays, it may be convenient to use this constructor:

Array(const TinyVector<int, N_rank>& extent);
Array(const TinyVector<int, N_rank>& extent, 
      GeneralArrayStorage<N_rank> storage);

The argument extent is a vector containing the extent (length) of the array in each dimension. The optional second parameter indicates a storage format. Note that you can construct TinyVector<int,N> objects on the fly with the shape(i1,i2,...) global function. For example, Array<int,2> A(shape(3,5)) will create a 3x5 array.

A similar constructor lets you provide both a vector of base index values (lbounds) and extents:

Array(const TinyVector<int, N_rank>& lbound, 
      const TinyVector<int, N_rank>& extent);
Array(const TinyVector<int, N_rank>& lbound,
      const TinyVector<int, N_rank>& extent,
      GeneralArrayStorage<N_rank> storage);

The argument lbound is a vector containing the base index value (or lbound) of the array in each dimension. The argument extent is a vector containing the extent (length) of the array in each dimension. The optional third parameter indicates a storage format. As with the above constructor, you can use the shape(i1,i2,...) global function to create the lbound and extent parameters.

2.3.4 Constructors with Range arguments

These constructors allow arbitrary bases (starting indices) to be set:

Array(Range r1);
Array(Range r1, Range r2);
Array(Range r1, Range r2, Range r3);
...
Array(Range r1, Range r2, Range r3, ..., Range r11);

For example, this code:

Array<int,2> A(Range(10,20), Range(20,30));

will create an 11x11 array whose indices are 10..20 and 20..30. An optional last parameter provides a storage order:

Array(Range r1, GeneralArrayStorage<N_rank> storage);
Array(Range r1, Range r2, GeneralArrayStorage<N_rank> storage);
...

2.3.5 Referencing another array

This constructor makes a shared view of another array’s data:

Array(Array<T_numtype, N_rank>& array);

After this constructor is used, both Array objects refer to the same data. 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 copy() member function.

2.3.6 Constructing an array from an expression

Arrays may be constructed from expressions, which are described in Array Expressions. The syntax is:

Array(...array expression...);

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

Array<float,2> A(N,N);   // ...
Array<float,2> B(sqrt(A));

2.3.7 Creating an array from pre-existing data

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 preexistingMemoryPolicy:

enum preexistingMemoryPolicy { 
  duplicateData, 
  deleteDataWhenDone, 
  neverDeleteData 
};

If you choose duplicateData, Blitz++ will create an array object using a copy of the data you provide. If you choose deleteDataWhenDone, 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 delete []. Note that to use deleteDataWhenDone, your array data must have been allocated using the C++ new operator – for example, you cannot allocate array data using Fortran or malloc, then create a Blitz++ array from it using the deleteDataWhenDone flag. The third option is neverDeleteData, 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++ new operator.

These constructors create array objects from pre-existing data:

Array(T_numtype* dataFirst, TinyVector<int, N_rank> shape,
      preexistingMemoryPolicy deletePolicy);
Array(T_numtype* dataFirst, TinyVector<int, N_rank> shape,
      preexistingMemoryPolicy deletePolicy, 
      GeneralArrayStorage<N_rank> storage);

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 shape() function. For example:

double data[] = { 1, 2, 3, 4 };
Array<double,2> A(data, shape(2,2), neverDeleteData);   // Make a 2x2 array

The shape() function takes N integer arguments and returns a TinyVector<int,N>.

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:

Array<double,2> B(data, shape(2,2), neverDeleteData,
                  FortranArray<2>());

This is a tad awkward, so Blitz++ provides the global object fortranArray which will convert to an instance of GeneralArrayStorage<N_rank>:

Array<double,2> B(data, shape(2,2), neverDeleteData, fortranArray);

Another version of this constructor allows you to pass an arbitrary vector of strides:

Array(T_numtype* _bz_restrict dataFirst, TinyVector<int, N_rank> shape,
      TinyVector<int, N_rank> stride, 
      preexistingMemoryPolicy deletePolicy,
      GeneralArrayStorage<N_rank> storage = GeneralArrayStorage<N_rank>())

2.3.8 Interlacing arrays

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 interlaceArrays() and allocateArrays(). An example:

Array<int,2> A, B;
interlaceArrays(shape(10,10), A, B);

The first parameter of interlaceArrays() 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 A(0,0) is followed immediately by B(0,0) in memory, which is folloed by A(0,1) and B(0,1), and so on.

A related routine is allocateArrays(), which has identical syntax:

Array<int,2> A, B;
allocateArrays(shape(10,10), A, B);

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

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 interlaceArrays() after running some benchmarks to determine whether interlacing is beneficial for your particular algorithm and architecture.

2.3.9 A note about reference counting

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