arrays-members.texi

c++经典教材 Blitz++ v0.8

@findex isMajorRank()
@cindex Array member functions @code{isMajorRank()}
@example
bool                              isMajorRank(int dimension) const;
@end example

Returns true if the dimension has the largest stride.  For C-style arrays
(the default), the first dimension always has the largest stride.  For
Fortran-style arrays, the last dimension has the largest stride.  See also
@code{isMinorRank()} below and the note about dimension parameters such as
@code{firstDim} in the previous section.

@findex isMinorRank()
@cindex Array member functions @code{isMinorRank()}
@example
bool                              isMinorRank(int dimension) const;
@end example

Returns true if the dimension @emph{does not} have the largest stride.  See
also @code{isMajorRank()}.

@findex isRankStoredAscending()
@cindex Array member functions @code{isRankStoredAscending()}
@example
bool                              isRankStoredAscending(int dimension) const;
@end example

Returns true if the dimension is stored in ascending order in memory.  This
is the default.  It will only return false if you have reversed a dimension
using @code{reverse()} or have created a custom storage order with a
descending dimension.

@findex isStorageContiguous()
@cindex Array member functions @code{isStorageContiguous()}
@example
bool                              isStorageContiguous() const;
@end example

Returns true if the array data is stored contiguously in memory.  If you
slice the array or work on subarrays, there can be skips -- the array data
is interspersed with other data not part of the array.  See also the various
@code{data..()} functions.  If you need to ensure that the storage is
contiguous, try @code{reference(copy())}.

@findex lbound()
@cindex Array member functions @code{lbound()}
@example
int                               lbound(int dimension) const;
TinyVector<int,N_rank>            lbound() const;
@end example

The first version returns the lower bound of the valid index range for a
dimension.  The second version returns a vector of lower bounds for all
dimensions.  The lower bound is the first valid index value.  If you're
using a C-style array (the default), the lbound will be zero; Fortran-style
arrays have lbound equal to one.  The lbound can be different for each
dimension, but only if you deliberately set them that way using a Range
constructor or a custom storage ordering.  This function is equivalent to
@code{base(dimension)}.  See the note about dimension parameters such as
@code{firstDim} in the previous section.


@findex makeUnique()
@cindex Array member functions @code{makeUnique()}
@cindex Array making unique copy
@example
void                              makeUnique();
@end example

If the array's data is being shared with another Blitz++ array object, this
member function creates a copy so the array object has a unique view of the
data.  

@findex numElements()
@cindex Array member functions @code{numElements()}
@cindex Array number of elements in
@example
int                               numElements() const;
@end example

Returns the total number of elements in the array, calculated by taking the
product of the extent in each dimension.  Same as @code{size()}.

@findex ordering()
@cindex Array member functions @code{ordering()}
@cindex Array storage ordering of
@example
const TinyVector<int, N_rank>&    ordering() const;
int                               ordering(int storageRankIndex) const;
@end example

These member functions return information about how the data is ordered in
memory.  The first version returns the complete ordering vector; the second
version returns a single element from the ordering vector.  The argument for
the second version must be in the range 0 .. @code{N_rank}-1.  The ordering
vector is a list of dimensions in increasing order of stride;
@code{ordering(0)} will return the dimension number with the smallest
stride, and @code{ordering(N_rank-1)} will return the dimension number with
largest stride.  For a C-style array, the ordering vector contains the
elements (@code{N_rank}-1, @code{N_rank}-2, ..., 0).  For a Fortran-style
array, the ordering vector is (0, 1, ..., @code{N_rank}-1).  See also the
description of custom storage orders in section @ref{Array storage}.

@findex rank()
@cindex Array member functions @code{rank()}
@example
int                               rank() const;
@end example

Returns the rank (number of dimensions) of the array.  The return value is
equal to @code{N_rank}.  Equivalent to @code{dimensions()}.

@findex reference()
@cindex Array member functions @code{reference()}
@cindex Array referencing another
@example
void                              reference(Array<T_numtype,N_rank>& A);
@end example

This causes the array to adopt another array's data as its own.  After this
member function is used, the array object and the array @code{A} are
indistinguishable -- they have identical sizes, index ranges, and data.  The
data is shared between the two arrays.

@findex reindex(), reindexSelf()
@cindex Array member functions @code{reindex()}
@cindex Array member functions @code{reindexSelf()}
@cindex Array reindexing
@example
void                              reindexSelf(const TinyVector<int,N_rank>&);
Array<T,N>                        reindex(const TinyVector<int,N_rank>&);
@end example

These methods reindex an array to use a new base vector.  The first version
reindexes the array, and the second just returns a reindexed view of the
array, leaving the original array unmodified.

@findex resize()
@cindex Array member functions @code{resize()}
@cindex Array resizing
@example
void                              resize(int extent1, ...);
void                              resize(const TinyVector<int,N_rank>&);
@end example

These functions resize an array to the specified size.  If the array is
already the size specified, then no memory is allocated.  After resizing,
the contents of the array are garbage.  See also @code{resizeAndPreserve()}.

@findex resizeAndPreserve()
@cindex Array member functions @code{resizeAndPreserve()}
@example
void                              resizeAndPreserve(int extent1, ...);
void                              resizeAndPreserve(const TinyVector<int,N_rank>&);
@end example

These functions resize an array to the specified size.  If the array is
already the size specified, then no change occurs (the array is not
reallocated and copied).  The contents of the array are preserved whenever
possible; if the new array size is smaller, then some data will be lost.
Any new elements created by resizing the array are left uninitialized.

@findex reverse(), reverseSelf()
@cindex Array member functions @code{reverse()}
@cindex Array member functions @code{reverseSelf()}
@cindex Array reversing
@example
Array<T,N>                        reverse(int dimension);
void                              reverseSelf(int dimension);
@end example

This method reverses the array in the specified dimension.  For example, if
@code{reverse(firstDim)} is invoked on a 2-dimensional array, then the
ordering of rows in the array will be reversed; @code{reverse(secondDim)}
would reverse the order of the columns.  Note that this is implemented by
twiddling the strides of the array, and doesn't cause any data copying.  The
first version returns a reversed ``view'' of the array data; the second
version applies the reversal to the array itself.

@findex rows()
@cindex Array member functions @code{rows()}
@example
int                               rows() const;
@end example

Returns the extent (length) of the array in the first dimension.  This
function is equivalent to @code{extent(firstDim)}.  See also
@code{columns()}, and @code{depth()}.

@findex size()
@cindex Array member functions @code{size()}
@example
int                               size() const;
@end example

Returns the total number of elements in the array, calculated by taking the
product of the extent in each dimension.  Same as @code{numElements()}.

@cindex @code{shape()} (Array method)
@cindex Array member functions @code{shape()}
@cindex Array shape of
@example
const TinyVector<int, N_rank>&    shape() const;
@end example

Returns the vector of extents (lengths) of the array.

@findex stride()
@cindex Array member functions @code{stride()}
@cindex Array strides of
@example
const TinyVector<int, N_rank>&    stride() const;
int                               stride(int dimension) const;
@end example

The first version returns the stride vector; the second version returns the
stride associated with a dimension.  A stride is the distance between
pointers to two array elements which are adjacent in a dimension.  For
example, @code{A.stride(firstDim)} is equal to @code{&A(1,0,0) - &A(0,0,0)}.
The stride for the second dimension, @code{A.stride(secondDim)}, is equal to
@code{&A(0,1,0) - &A(0,0,0)}, and so on.  For more information about
strides, see the description of custom storage formats in Section
@ref{Array storage}.  See also the description of parameters like
@code{firstDim} and @code{secondDim} in the previous section.

@cindex Array member functions @code{transpose()}
@cindex Array member functions @code{transposeSelf()}
@cindex Array transposing
@cindex transposing arrays
@findex transpose(), transposeSelf()
@example
Array<T,N>                        transpose(int dimension1, 
                                            int dimension2, ...);
void                              transposeSelf(int dimension1, 
                                                int dimension2, ...);
@end example

These methods permute the dimensions of the array.  The dimensions of the
array are reordered so that the first dimension is @code{dimension1}, the
second is @code{dimension2}, and so on.  The arguments should be a
permutation of the symbols @code{firstDim, secondDim, ...}.  Note that this
is implemented by twiddling the strides of the array, and doesn't cause any
data copying.  The first version returns a transposed ``view'' of the array
data; the second version transposes the array itself.

@cindex Array member functions @code{ubound()}
@findex ubound()
@example
int                               ubound(int dimension) const;
TinyVector<int,N_rank>            ubound() const;
@end example

The first version returns the upper bound of the valid index range for a
dimension.  The second version returns a vector of upper bounds for all
dimensions.  The upper bound is the last valid index value.  If you're using
a C-style array (the default), the ubound will be equal to the
@code{extent(dimension)-1}.  Fortran-style arrays will have ubound equal to
@code{extent(dimension)}.  The ubound can be different for each dimension.
The return value of @code{ubound(dimension)} will always be equal to
@code{lbound(dimension)+extent(dimension)-1}.  See the note about
dimension parameters such as @code{firstDim} in the previous section.

@findex zeroOffset()
@cindex Array member functions @code{zeroOffset()}
@example
int                               zeroOffset() const;
@end example

This function has to do with the storage of arrays in memory.  You may want
to refer to the description of the @code{data..()} member functions and of
custom storage orders in Section @ref{Array storage} for
clarification.  The return value of @code{zeroOffset()} is the distance from
the first element in the array to the (possibly nonexistant) element
@code{(0,0,...,0)}.  In this context, ``first element'' returns to the element
@code{(base(firstDim),base(secondDim),...)}.