Boost.MultiArray 參考手冊

以下是將用於 MultiArray 接口說明的符號描述。

以下 MultiArray 相關類型定義了創建已有 MultiArray 的視圖的接口。以下描述其接口及規則。

5 <= index_range() < 10;

4 < index_range() <= 9;

multi_array 是一個支持隨機訪問迭代的多維容器。它的維數在編譯期是固定的，但它的形狀和所包含的元素數量可以在構造時指定。元素的數量在 multi_array 的生命週期內是固定的，但容器的形狀可以改變。multi_array 用一個可替換的分配器(allocator)來管理其數據元素。

符合的概念：MultiArray, 可複製構造。根據其元素類型，也可能符合 相等性可比較 和 小於關係可比較。

摘要：

namespace boost {

template <typename ValueType, 
          std::size_t NumDims, 
          typename Allocator = std::allocator<ValueType> >
class multi_array {
public:
// types:
  typedef ValueType                             element;
  typedef *unspecified*                         value_type;
  typedef *unspecified*                         reference;
  typedef *unspecified*                         const_reference;
  typedef *unspecified*                         difference_type;
  typedef *unspecified*                         iterator;
  typedef *unspecified*                         const_iterator;
  typedef *unspecified*                         reverse_iterator;
  typedef *unspecified*                         const_reverse_iterator;
  typedef multi_array_types::size_type          size_type;
  typedef multi_array_types::index              index;
  typedef multi_array_types::index_gen          index_gen;
  typedef multi_array_types::index_range        index_range;
  typedef multi_array_types::extent_gen         extent_gen;
  typedef multi_array_types::extent_range       extent_range;
  typedef *unspecified*                         storage_order_type;
  

  // template typedefs
  template <std::size_t Dims> struct            subarray;
  template <std::size_t Dims> struct            const_subarray;
  template <std::size_t Dims> struct            array_view;
  template <std::size_t Dims> struct            const_array_view;
  

  // constructors and destructors

  multi_array();

  template <typename ExtentList>
  explicit multi_array(const ExtentList& sizes,
                       const storage_order_type& store = c_storage_order(),
                       const Allocator& alloc = Allocator());
  explicit multi_array(const extents_tuple& ranges,
                       const storage_order_type& store = c_storage_order(),
	               const Allocator& alloc = Allocator());
  multi_array(const multi_array& x);
  multi_array(const const_multi_array_ref<ValueType,NumDims>& x);
  multi_array(const const_subarray<NumDims>::type& x);
  multi_array(const const_array_view<NumDims>::type& x);

  multi_array(const multi_array_ref<ValueType,NumDims>& x);
  multi_array(const subarray<NumDims>::type& x);
  multi_array(const array_view<NumDims>::type& x);

  ~multi_array();

  // modifiers

  multi_array& operator=(const multi_array& x);
  template <class Array> multi_array& operator=(const Array& x);

  // iterators:
  iterator				begin();
  iterator				end();
  const_iterator			begin() const;
  const_iterator			end() const;
  reverse_iterator			rbegin();
  reverse_iterator			rend();
  const_reverse_iterator		rbegin() const;
  const_reverse_iterator		rend() const;

  // capacity:
  size_type				size() const;
  size_type				num_elements() const;
  size_type				num_dimensions() const;
 
  // element access:
  template <typename IndexList> 
    element&			operator()(const IndexList& indices);
  template <typename IndexList>
    const element&		operator()(const IndexList& indices) const;
  reference			operator[](index i);
  const_reference		operator[](index i) const;
  array_view<Dims>::type	operator[](const indices_tuple& r);
  const_array_view<Dims>::type	operator[](const indices_tuple& r) const;

  // queries
  element*			data();
  const element*		data() const;
  element*			origin();
  const element*		origin() const;
  const size_type*		shape() const;
  const index*			strides() const;
  const index*			index_bases() const;
  const storage_order_type&     storage_order() const;

  // comparators
  bool operator==(const multi_array& rhs);
  bool operator!=(const multi_array& rhs);
  bool operator<(const multi_array& rhs);
  bool operator>(const multi_array& rhs);
  bool operator>=(const multi_array& rhs);
  bool operator<=(const multi_array& rhs);

  // modifiers:
  template <typename InputIterator>
    void			assign(InputIterator begin, InputIterator end);
  template <typename SizeList>
    void			reshape(const SizeList& sizes)
  template <typename BaseList>	void reindex(const BaseList& values);
    void			reindex(index value);
  template <typename ExtentList>
    multi_array&		resize(const ExtentList& extents);
  multi_array&                  resize(extents_tuple& extents);
};

構造函數

關於構造函數的補充說明：multi_array 構造表達式

     multi_array<int,3> A(boost::extents[5][4][3]);

和

     boost::array<multi_array_base::index,3> my_extents = {{5, 4, 3}};
     multi_array<int,3> A(my_extents);

是等價的。

修改操作

查詢

multi_array_ref 是一個多維容器適配器。它為任意存儲了某種元素的連續內存塊提供 MultiArray 的接口。multi_array_ref 給出了與 multi_array 相同的接口，除了構造函數以外。

符合的概念：multi_array_ref 符合 MultiArray, 可複製構造，並且依據其元素類型，還可能符合 相等性可比較 和 小於關係可比較。這裡只對在 multi_array 中沒有的操作給出詳細說明。

摘要

namespace boost {

template <typename ValueType, 
          std::size_t NumDims, 
          typename Allocator = std::allocator<ValueType> >
class multi_array_ref {
public:
// types:
  typedef ValueType                             element;
  typedef *unspecified*                         value_type;
  typedef *unspecified*                         reference;
  typedef *unspecified*                         const_reference;
  typedef *unspecified*                         difference_type;
  typedef *unspecified*                         iterator;
  typedef *unspecified*                         const_iterator;
  typedef *unspecified*                         reverse_iterator;
  typedef *unspecified*                         const_reverse_iterator;
  typedef multi_array_types::size_type          size_type;
  typedef multi_array_types::index              index;
  typedef multi_array_types::index_gen          index_gen;
  typedef multi_array_types::index_range        index_range;
  typedef multi_array_types::extent_gen         extent_gen;
  typedef multi_array_types::extent_range       extent_range;
  typedef *unspecified*                         storage_order_type;
  
  // template typedefs
  template <std::size_t Dims> struct            subarray;
  template <std::size_t Dims> struct            const_subarray;
  template <std::size_t Dims> struct            array_view;
  template <std::size_t Dims> struct            const_array_view;
  

  // structors

  template <typename ExtentList>
  explicit multi_array_ref(element* data, const ExtentList& sizes,
                       const storage_order_type& store = c_storage_order());
  explicit multi_array_ref(element* data, const extents_tuple& ranges,
                       const storage_order_type& store = c_storage_order());
  multi_array_ref(const multi_array_ref& x);
  ~multi_array_ref();

  // modifiers

  multi_array_ref& operator=(const multi_array_ref& x);
  template <class Array> multi_array_ref& operator=(const Array& x);

  // iterators:
  iterator				begin();
  iterator				end();
  const_iterator			begin() const;
  const_iterator			end() const;
  reverse_iterator			rbegin();
  reverse_iterator			rend();
  const_reverse_iterator		rbegin() const;
  const_reverse_iterator		rend() const;

  // capacity:
  size_type				size() const;
  size_type				num_elements() const;
  size_type				num_dimensions() const;
 
  // element access:
  template <typename IndexList> 
    element&			operator()(const IndexList& indices);
  template <typename IndexList>
    const element&		operator()(const IndexList& indices) const;
  reference			operator[](index i);
  const_reference		operator[](index i) const;
  array_view<Dims>::type	operator[](const indices_tuple& r);
  const_array_view<Dims>::type	operator[](const indices_tuple& r) const;

  // queries
  element*			data();
  const element*		data() const;
  element*			origin();
  const element*		origin() const;
  const size_type*		shape() const;
  const index*			strides() const;
  const index*			index_bases() const;
  const storage_order_type&     storage_order() const;

  // comparators
  bool operator==(const multi_array_ref& rhs);
  bool operator!=(const multi_array_ref& rhs);
  bool operator<(const multi_array_ref& rhs);
  bool operator>(const multi_array_ref& rhs);
  bool operator>=(const multi_array_ref& rhs);
  bool operator<=(const multi_array_ref& rhs);

  // modifiers:
  template <typename InputIterator>
    void			assign(InputIterator begin, InputIterator end);
  template <typename SizeList>
    void			reshape(const SizeList& sizes)
  template <typename BaseList>	void reindex(const BaseList& values);
  void				reindex(index value);
};

構造函數

修改操作

const_multi_array_ref 是一個多維容器適配器。它為任意存儲了某種元素的連續內存塊提供 MultiArray 的接口。給出了與 multi_array 相同的接口，除了構造函數以外。 

符合的概念：const_multi_array_ref 符合 MultiArray, 可複製構造，並且依據其元素類型，還可能符合 相等性可比較 和 小於關係可比較。這裡只對在 multi_array 中沒有的操作給出詳細說明。

摘要

namespace boost {

template <typename ValueType, 
          std::size_t NumDims, 
          typename Allocator = std::allocator<ValueType> >
class const_multi_array_ref {
public:
// types:
  typedef ValueType                             element;
  typedef *unspecified*                         value_type;
  typedef *unspecified*                         reference;
  typedef *unspecified*                         const_reference;
  typedef *unspecified*                         difference_type;
  typedef *unspecified*                         iterator;
  typedef *unspecified*                         const_iterator;
  typedef *unspecified*                         reverse_iterator;
  typedef *unspecified*                         const_reverse_iterator;
  typedef multi_array_types::size_type          size_type;
  typedef multi_array_types::index              index;
  typedef multi_array_types::index_gen          index_gen;
  typedef multi_array_types::index_range        index_range;
  typedef multi_array_types::extent_gen         extent_gen;
  typedef multi_array_types::extent_range       extent_range;
  typedef *unspecified*                         storage_order_type;
  
  // template typedefs
  template <std::size_t Dims> struct            subarray;
  template <std::size_t Dims> struct            const_subarray;
  template <std::size_t Dims> struct            array_view;
  template <std::size_t Dims> struct            const_array_view;
  

  // structors

  template <typename ExtentList>
  explicit const_multi_array_ref(const element* data, const ExtentList& sizes,
                       const storage_order_type& store = c_storage_order());
  explicit const_multi_array_ref(const element* data, const extents_tuple& ranges,
                       const storage_order_type& store = c_storage_order());
  const_multi_array_ref(const const_multi_array_ref& x);
  ~const_multi_array_ref();



  // iterators:
  const_iterator			begin() const;
  const_iterator			end() const;
  const_reverse_iterator		rbegin() const;
  const_reverse_iterator		rend() const;

  // capacity:
  size_type				size() const;
  size_type				num_elements() const;
  size_type				num_dimensions() const;
 
  // element access:
  template <typename IndexList>
    const element&		operator()(const IndexList& indices) const;
  const_reference		operator[](index i) const;
  const_array_view<Dims>::type	operator[](const indices_tuple& r) const;

  // queries
  const element*		data() const;
  const element*		origin() const;
  const size_type*		shape() const;
  const index*			strides() const;
  const index*			index_bases() const;
  const storage_order_type&     storage_order() const;

  // comparators
  bool operator==(const const_multi_array_ref& rhs);
  bool operator!=(const const_multi_array_ref& rhs);
  bool operator<(const const_multi_array_ref& rhs);
  bool operator>(const const_multi_array_ref& rhs);
  bool operator>=(const const_multi_array_ref& rhs);
  bool operator<=(const const_multi_array_ref& rhs);

  // modifiers:
  template <typename SizeList>
  void			reshape(const SizeList& sizes)
  template <typename BaseList>	void reindex(const BaseList& values);
  void				reindex(index value);
};

構造函數

namespace multi_array_types {
  typedef *unspecified* index;
  typedef *unspecified* size_type;
  typedef *unspecified* difference_type;
  typedef *unspecified* index_range;
  typedef *unspecified* extent_range;
  typedef *unspecified* index_gen;
  typedef *unspecified* extent_gen;
}

名字空間 multi_array_types 定義了一些與 multi_array, multi_array_ref, 和 const_multi_array_ref 相關的類型，這些類型不依賴於模板參數。這些類型被所有 Boost.Multiarray 組件共同使用。它們被定義在一個可以方便訪問的名字空間中。除了 extent_gen 和 extent_range 以外，這些類型遵循 MultiArray 所要求且在其概念定義中被描述的同名規則。extent_gen 和 extent_range 則描述如下。

extent_range 對像定義了一個半開區間。它為 multi_array, multi_array_ref, 和 const_multi_array_ref 的構造函數提供形狀和索引的信息。多個 extent_range 被聚集起來傳遞給數組的構造函數(詳細說明請見 extent_gen)。

摘要

class extent_range {
public:
  typedef multi_array_types::index      index;
  typedef multi_array_types::size_type  size_type;

  // Structors
  extent_range(index start, index finish);
  extent_range(index finish);
  ~extent_range();

  // Queries
  index start();
  index finish();
  size_type size();
};

符合的概念：可缺省構造，可複製構造

方法與類型

extent_gen 類定義了一個接口，用於聚集數組的形狀和索引信息，以傳遞給 multi_array, multi_array_ref, 或 const_multi_array_ref 的構造函數。該接口模仿了C++中聲明內建數組類型的語法。例如，在C++中，一個3維 int 數組聲明如下：

int A[3][4][5],

類似的 multi_array 則聲明如下：

multi_array<int,3> A(extents[3][4][5]).

摘要

template <std::size_t NumRanges>
class *implementation_defined* {
public:
  typedef multi_array_types::index index;
  typedef multi_array_types::size_type size_type;

  template <std::size_t NumRanges> class gen_type;

  gen_type<NumRanges+1>::type  operator[](const range& a_range) const;
  gen_type<NumRanges+1>::type  operator[](index idx) const;
};

typedef *implementation_defined*<0> extent_gen;

方法與類型

為了語法上的方便，Boost.MultiArray 定義了兩個全局對像作為其接口的一部分。這些對像扮演了對象生成器的角色；包含它們的表達式可以創建其它所需的對象。

在某些情形下，這兩個全局對象可能被認為開銷太大。可以通過在包含 boost/multi_array.hpp 之前定義預處理符號 BOOST_MULTI_ARRAY_NO_GENERATORS 來禁止它們的構造。

namespace boost {
  multi_array_base::extent_gen extents;
}

multi_array<int,3> A(extents[3][3][3]);

namespace boost {
  multi_array_base::index_gen  indices;
}

A[indices[index_range(0,5)][2][index_range(2,4)]];

Boost.MultiArray 提供了 traits 類 subarray_gen, const_subarray_gen, array_view_gen, 和 const_array_view_gen, 用於在函數模板中表示數組的各個相關類型。通常，沒有比使用嵌套類型生成器更為方便的方法了，不過本庫的作者發現，有些C++編譯器不能正確處理嵌套在函數模板的參數類型中的模板。為此，這些生成器需要另外的解決方法。以下代碼片斷示範了 array_view_gen traits 類和相關數組的 array_view 類型之間的對應關係：

template <typename Array>
void my_function() {
  typedef typename Array::template array_view<3>::type view1_t;
  typedef typename boost::array_view_gen<Array,3>::type view2_t;
  // ...
}

在上例中，view1_t 和 view2_t 具有相同類型。

多維數組表示了由多個元素容器組成的層次結構，而這些元素必須被置於內存中。所以，一個多維數組可以用多種方法在內存中表示。

例如，有以下矩陣所表示的一個2維數組：

這個數組在C++中可以表示為：

int a[3][4] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 };

這是一個行優先存儲的例子，每行的元素被連續存儲。除了讓C++來處理對數組元素的訪問以外，你也可以自己手工管理這個數組以及它的索引。其中一種方法可能是這樣：

int a[] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11 };
int s[] = { 4, 1 };

在聲明了 a 和步幅 s 之後，數組的元素 a(i,j) 可以用以下表達式來訪問：

*a+i*s[0]+j*s[1]

.

同一個2維數組也可以按列存儲如下：

int a[] = { 0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11 };
int s[] = { 3, 1 };

注意，這裡的步幅有所不同。所以，前面給出的訪問元素的表達式必須與該數據和步幅一起使用。

除了維度的順序，還有可能以降序方式保存某個維度。例如，回到第一個例子，數組的第一個維度，即行，可能以相反的順序保存如下：

int data[] = { 8, 9, 10, 11, 4, 5, 6, 7, 0, 1, 2, 3 };
int *a = data + 8;
int s[] = { -4, 1 };

注意，在這個例子中，a 必須顯式地設置為原點。在前面的例子中，保存在內存中的第一個元素即為原點；而這裡不再是如此了。

另外，第二個維度，即列，也可能以相反的順序保存，而行則以升序保存：

int data[] = { 3, 2, 1, 0,  7, 6, 5, 4, 11, 10, 9, 8 };
int *a = data + 3;
int s[] = { 4, -1 };

最後，也可能兩個維度均以降序保存：

int data[] = {11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0};
int *a = data + 11;
int s[] = { -4, -1 };

以上各個數組都是等價的。前面給出的訪問 a(i,j) 的表達式在各種內存佈局下均得到相同的值。Boost.MultiArray 數組可以按以上所說的各種定制的存儲參數來創建。因此，已有的數據可以被適配(通過 multi_array_ref 或 const_multi_array_ref)以適應數組的抽像。該特性的一個常見用法是，包裝一個需要與Fortran程序交互的數組，使它可以被C++和Fortran同時操作。下面幾節將講述用於指定內存佈局的 Boost.MultiArray 組件。

class c_storage_order {
  c_storage_order();
};

class fortran_storage_order {
  fortran_storage_order();
};

template <std::size_t NumDims> 
class general_storage_order {

  template <typename OrderingIter, typename AscendingIter>
  general_storage_order(OrderingIter ordering, AscendingIter ascending);
};

缺省情況下，數組訪問方法 operator() 和 operator[] 都執行範圍檢查。如果給定的索引值超出了數組所定義的範圍，將引發一個斷言並退出程序。要關閉範圍檢查(為了產品發佈版本的性能原因)，請在應用程序包含 multi_array.hpp 之前定義 BOOST_DISABLE_ASSERTS 預處理器宏。