The Boost Multidimensional Array Library
(Boost.MultiArray)
Synopsis
Библиотека многомерных массивов Boost предоставляет шаблон класса для многомерных массивов, а также семантически эквивалентные адаптеры для массивов смежных данных. Классы в этой библиотеке реализуют общий интерфейс, формализованный как общая концепция программирования. Дизайн интерфейса соответствует прецеденту, установленному контейнерами стандартной библиотеки C++. Boost MultiArray является более эффективным и удобным способом выражения N-мерных массивов, чем существующие альтернативы (особенноstd::vector>формулировка N-мерных массивов). Доступ к массивам, предоставляемым библиотекой, может осуществляться с использованием знакомого синтаксиса нативных массивов C++. Доступны дополнительные функции, такие как изменение размера, изменение формы и создание просмотров (и описаны ниже).
Стандартная библиотека C++ предоставляет несколько общих контейнеров, но не предоставляет многомерных типов массивов.std::vectorшаблон класса может быть использован для реализации N-мерных массивов, например, для выражения 2-мерного массивадвойныхэлементов с использованием типаstd::vector>, но полученный интерфейс громоздкий и объем памяти может быть довольно высоким. Native C++ arrays (т.е.int arr
;
Не очень хорошо взаимодействовать с C++. Стандартная библиотека, и они также теряют информацию на границах вызовов функций (в частности, степень последнего измерения). Наконец, динамически выделенный смежный блок элементов можно рассматривать как массив, хотя этот метод требует ручной бухгалтерии, которая подвержена ошибкам и запутывает намерение программиста.
Библиотека Boost MultiArray улучшает стандартные контейнеры C++ с универсальными многомерными абстракциями массивов. Он включает в себя общий шаблон класса массивов и нативные адаптеры массивов, которые поддерживают идиоматические операции массивов и взаимодействуют с контейнерами и алгоритмами стандартной библиотеки C++. Массивы имеют общий интерфейс, выраженный как общее программирование, с точки зрения которого могут быть реализованы общие алгоритмы массивов.
Этот документ предназначен для предоставления вводного руководства и руководства пользователя для самых основных и распространенных моделей использования компонентов MultiArray. Справочное руководствообеспечивает более полную и формальную документацию библиотечных функций.
Short Example
What follows is a brief example of the use of multi_array:
#include "boost/multi_array.hpp"
#include <cassert>
int
main () {
// Create a 3D array that is 3 x 4 x 2
typedef boost::multi_array<double, 3> array_type;
typedef array_type::index index;
array_type A(boost::extents[3][4][2]);
// Assign values to the elements
int values = 0;
for(index i = 0; i != 3; ++i)
for(index j = 0; j != 4; ++j)
for(index k = 0; k != 2; ++k)
A[i][j][k] = values++;
// Verify values
int verify = 0;
for(index i = 0; i != 3; ++i)
for(index j = 0; j != 4; ++j)
for(index k = 0; k != 2; ++k)
assert(A[i][j][k] == verify++);
return 0;
}
MultiArray Components
Boost.MultiArray's implementation (boost/multi_array.hpp) provides three user-level class templates:
multi_array is a container template. When instantiated, it
allocates space for the number of elements corresponding to the
dimensions specified at construction time. A multi_array may
also be default constructed and resized as needed.
multi_array_ref adapts an existing array of data to provide
the multi_array interface. multi_array_ref does not own the
data passed to it.
const_multi_array_ref is similar to multi_array_ref
but guarantees that the contents of the array are immutable. It can
thus wrap pointers of type T const*.
The three components exhibit very similar behavior. Aside from
constructor parameters, multi_array and
multi_array_ref export the same interface.
const_multi_array_ref provides only the constness-preserving
portions of the multi_array_ref interface.
All of the non-const array types in this library provide assignment
operatorsoperator=(). Each of the array types multi_array,
multi_array_ref, subarray, and
array_view can be assigned from any
of the others, so long as their shapes match. The
const variants, const_multi_array_ref,
const_subarray, and const_array_view, can be the
source of a copy to an array with matching shape.
Assignment results in a deep (element by element) copy of the data
contained within an array.
Array View and Subarray Type Generators
In some situations, the use of nested generators for array_view and
subarray types is inconvenient. For example, inside a
function template parameterized upon array type, the extra
"template" keywords can be obfuscating. More likely though, some
compilers cannot handle templates nested within template parameters.
For this reason the type generators, subarray_gen,
const_subarray_gen, array_view_gen, and
const_array_view_gen are provided. Thus, the two typedefs
in the following example result in the same type:
When creating most of the Boost.MultiArray components, it is necessary
to specify both the number of dimensions and the extent of each
(boost::multi_array also provides a default constructor).
Though the number of dimensions is always specified as a template
parameter, two separate mechanisms have been provided to specify the
extent of each.
The first method involves passing a
Collection of extents to a
constructor, most commonly a boost::array. The constructor
will retrieve the beginning iterator from the container and retrieve N
elements, corresponding to extents for the N dimensions. This is
useful for writing dimension-independent code.
The second method involves passing the constructor an extent_gen
object, specifying the matrix dimensions. The extent_gen type
is defined in the multi_array_types namespace and as a
member of every array type, but by default, the library constructs a
global extent_gen object boost::extents. In case of
concern about memory used by these objects, defining
BOOST_MULTI_ARRAY_NO_GENERATORS before including the library
header inhibits its construction.
The Boost.MultiArray components provide two ways of accessing
specific elements within a container. The first uses the traditional
C array notation, provided by operator[].
The second method involves passing a
Collection of indices to operator(). N indices will be retrieved
from the Collection for the N dimensions of the container.
This can be useful for writing dimension-independent code, and under
some compilers may yield higher performance than operator[].
By default, both of the above element access methods perform range
checking. If a supplied index is out of the range defined for an
array, an assertion will abort the program. To disable range
checking (for performance reasons in production releases), define
the BOOST_DISABLE_ASSERTS preprocessor macro prior to
including multi_array.hpp in your application.
Creating Views
Boost.MultiArray provides the facilities for creating a sub-view of an
already existing array component. It allows you to create a sub-view that
retains the same number of dimensions as the original array or one
that has less dimensions than the original as well.
Sub-view creation occurs by placing a call to operator[], passing
it an index_gen type. The index_gen is populated by
passing index_range objects to its operator[].
The index_range and index_gen types are defined in
the multi_array_types namespace and as nested members of
every array type. Similar to boost::extents, the library by
default constructs the object boost::indices. You can
suppress this object by
defining BOOST_MULTI_ARRAY_NO_GENERATORS before including the
library header. A simple sub-view creation example follows.
Example
// myarray = 2 x 3 x 4
//
// array_view dims: [base,bound) (dimension striding default = 1)
// dim 0: [0,2)
// dim 1: [1,3)
// dim 2: [0,4) (strided by 2),
//
typedef boost::multi_array_types::index_range range;
// OR typedef array_type::index_range range;
array_type::array_view<3>::type myview =
myarray[ boost::indices[range(0,2)][range(1,3)][range(0,4,2)] ];
for (array_type::index i = 0; i != 2; ++i)
for (array_type::index j = 0; j != 2; ++j)
for (array_type::index k = 0; k != 2; ++k)
assert(myview[i][j][k] == myarray[i][j+1][k*2]);
By passing an integral value to the index_gen, one may create a
subview with fewer dimensions than the original array component (also
called slicing).
Example
// myarray = 2 x 3 x 4
//
// array_view dims:
// [base,stride,bound)
// [0,1,2), 1, [0,2,4)
//
typedef boost::multi_array_types::index_range range;
array_type::index_gen indices;
array_type::array_view<2>::type myview =
myarray[ indices[range(0,2)][1][range(0,4,2)] ];
for (array_type::index i = 0; i != 2; ++i)
for (array_type::index j = 0; j != 2; ++j)
assert(myview[i][j] == myarray[i][1][j*2]);
More on index_range
The index_range type provides several methods of specifying
ranges for subview generation. Here are a few range instantiations
that specify the same range.
An index_range object passed to a slicing operation will
inherit its start and/or finish value from the array being sliced if
you do not supply one. This conveniently prevents you from having to
know the bounds of the array dimension in certain cases. For example,
the default-constructed range will take the full extent of the
dimension it is used to specify.
Example
typedef boost::multi_array_types::index_range range;
range a_range;
// All elements in this dimension
a_range = range();
// indices i where 3 <= i
a_range = range().start(3)
a_range = 3 <= range();
a_range = 2 < range();
// indices i where i < 7
a_range = range().finish(7)
a_range = range() < 7;
a_range = range() <= 6;
The following example slicing operations exhibit some of the
alternatives shown above
// take all of dimension 1
// take i < 5 for dimension 2
// take 4 <= j <= 7 for dimension 3 with stride 2
myarray[ boost::indices[range()][range() < 5 ][4 <= range().stride(2) <= 7] ];
Storage Ordering
Each array class provides constructors that accept a storage ordering
parameter. This is most
useful when interfacing with legacy codes that require an ordering
different from standard C, such as FORTRAN. The possibilities are
c_storage_order, fortran_storage_order, and
general_storage_order.
c_storage_order, which is the default, will store elements
in memory in the same order as a C array would, that is, the
dimensions are stored from last to first.
fortran_storage_order will store elements in memory in the same order
as FORTRAN would: from the first dimension to
the last. Note that with use of this parameter, the array
indices will remain zero-based.
general_storage_order allows one to customize both the order in
which dimensions are stored in memory and whether dimensions are
stored in ascending or descending order.
Example
typedef boost::general_storage_order<3> storage;
typedef boost::multi_array<int,3> array_type;
// Store last dimension, then first, then middle
array_type::size_type ordering[] = {2,0,1};
// Store the first dimension(dimension 0) in descending order
bool ascending[] = {false,true,true};
array_type A(extents[3][4][2],storage(ordering,ascending));
Setting The Array Base
In some situations, it may be inconvenient or awkward to use an
array that is zero-based.
the Boost.MultiArray components provide two facilities for changing the
bases of an array. One may specify a pair of range values, with
the extent_range type, to
the extent_gen constructor in order to set the base value.
An alternative is to first construct the array normally then
reset the bases. To set all bases to the same value, use the
reindex member function, passing it a single new index value.
The Boost.MultiArray arrays provide a reshape operation. While the
number of dimensions must remain the same, the shape of the array may
change so long as the total number of
elements contained remains the same.
Note that reshaping an array does not affect the indexing.
Resizing an Array
The boost::multi_array class provides an element-preserving
resize operation. The number of dimensions must remain the same, but
the extent of each dimension may be increased and decreased as
desired. When an array is made strictly larger, the existing elements
will be preserved by copying them into the new underlying memory and
subsequently destructing the elements in the old underlying memory.
Any new elements in the array are default constructed. However, if
the new array size shrinks some of the dimensions, some elements will
no longer be available.
Boost.MultiArray defines and uses the
MultiArray
concept. It specifies an interface for N-dimensional containers.
Test Cases
Boost.MultiArray comes with a suite of test cases meant to exercise
the features and semantics of the library. A description of the test
cases can be found here.
Related Work
boost::array
and std::vector are
one-dimensional containers of user data. Both manage their own
memory. std::valarray is a low-level
C++ Standard Library component
meant to provide portable high performance for numerical applications.
Blitz++ is
an array library developed by Todd
Veldhuizen. It uses
advanced C++ techniques to provide near-Fortran performance for
array-based numerical applications.
array_traits is a beta library, formerly distributed with
Boost, that provides a means to create iterators over native C++
arrays.
This library is analogous to
boost::array in that it augments C style N-dimensional
arrays, as boost::array does for C one-dimensional arrays.
Jeremy Siek
helped with the library and provided a sounding board for ideas,
advice, and assistance porting to Microsoft Visual C++.
Giovanni Bavestrelli
provided an early implementation of an
N-dimensional array which inspired feedback from the
Boost mailing list
members. Some design decisions in this work were based upon this
implementation and the comments it elicited.
Todd Veldhuizen wrote
Blitz++, which
inspired some aspects of this design. In addition, he supplied
feedback on the design and implementation of the library.
Jeremiah Willcock
provided feedback on the implementation and design of the
library and some suggestions for features.
Beman Dawes
helped immensely with porting the library to Microsoft Windows
compilers.
Ronald Garcia
Last modified: Tue Feb 7 17:15:50 EST 2006
Статья The Boost Multidimensional Array Library (Boost.MultiArray) раздела может быть полезна для разработчиков на c++ и boost.
