commit 61378176bee363bd6d3da4339e465ed726c3fd76
author Brian Silverman <bsilver16384@gmail.com> Sat Aug 04 23:37:59 2018 -0700
committer Brian Silverman <bsilver16384@gmail.com> Sat Aug 04 23:37:59 2018 -0700
tree 879a96c8c9a6af3e05b88db5ce635aa10290c3ef

Squashed 'third_party/boostorg/multi_array/' content from commit abcb283

Change-Id: I4b93f75f0b15b00216d918bd6db5fc4fcb9c4cc2
git-subtree-dir: third_party/boostorg/multi_array
git-subtree-split: abcb2839d56669d1b5bb8a240ec644f47c66beb2

doc/xml/multi_array_ref.xml

diff --git a/doc/xml/multi_array_ref.xml b/doc/xml/multi_array_ref.xml
new file mode 100644
index 0000000..3e21b54
--- /dev/null
+++ b/doc/xml/multi_array_ref.xml
@@ -0,0 +1,257 @@
+<sect2 id="multi_array_ref">
+<title><literal>multi_array_ref</literal></title>
+
+<para>
+<literal>multi_array_ref</literal> is a multi-dimensional container
+adaptor.  It provides the MultiArray interface over any contiguous
+block of elements.  <literal>multi_array_ref</literal> exports the
+same interface as <literal>multi_array</literal>, with the exception
+of the constructors.
+</para>
+
+
+<formalpara>
+      <title>Model Of.</title>
+<para>
+<literal>multi_array_ref</literal> models 
+<link linkend="MultiArray">MultiArray</link>,
+<ulink url="../../../libs/utility/CopyConstructible.html">CopyConstructible</ulink>.
+and depending on the element type, it may also model
+<ulink url="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</ulink> and <ulink url="http://www.sgi.com/tech/stl/LessThanComparable.html">LessThanComparable</ulink>. 
+Detailed descriptions are provided here only for operations that are
+not described in the <literal>multi_array</literal> reference.
+</para>
+</formalpara>
+
+<formalpara>
+<title>Synopsis</title>
+
+<programlisting>
+<![CDATA[
+namespace boost {
+
+template <typename ValueType, 
+          std::size_t NumDims>
+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;
+  
+
+  static const std::size_t dimensionality = NumDims;
+
+
+  // constructors and destructors
+
+  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);
+};
+]]>
+</programlisting>
+</formalpara>
+
+<formalpara>
+<title>Constructors</title>
+
+<variablelist>
+<varlistentry>
+<term><programlisting>template &lt;typename ExtentList&gt;
+explicit multi_array_ref(element* data, 
+                     const ExtentList&amp; sizes,
+                     const storage_order&amp; store = c_storage_order(),
+                     const Allocator&amp; alloc = Allocator());
+</programlisting></term>
+<listitem>
+
+<para>
+This constructs a <literal>multi_array_ref</literal> using the specified
+parameters.  <literal>sizes</literal> specifies the shape of the
+constructed <literal>multi_array_ref</literal>.  <literal>store</literal>
+specifies the storage order or layout in memory of the array
+dimensions.  <literal>alloc</literal> is used to
+allocate the contained elements.
+</para>
+
+<formalpara><title><literal>ExtentList</literal> Requirements</title>
+<para>
+<literal>ExtentList</literal> must model <ulink url="../../utility/Collection.html">Collection</ulink>.
+</para>
+</formalpara>
+
+<formalpara><title>Preconditions</title>
+<para><literal>sizes.size() == NumDims;</literal></para>
+</formalpara>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<programlisting><![CDATA[explicit multi_array_ref(element* data,
+                     extent_gen::gen_type<NumDims>::type ranges,
+                     const storage_order& store = c_storage_order());]]>
+</programlisting></term> 
+<listitem>
+<para>
+This constructs a <literal>multi_array_ref</literal> using the specified
+    parameters.  <literal>ranges</literal> specifies the shape and
+index bases of the constructed multi_array_ref. It is the result of 
+<literal>NumDims</literal> chained calls to 
+    <literal>extent_gen::operator[]</literal>. <literal>store</literal>
+specifies the storage order or layout in memory of the array
+dimensions. 
+</para>
+</listitem>
+</varlistentry> 
+
+
+<varlistentry>
+<term><programlisting>
+<![CDATA[multi_array_ref(const multi_array_ref& x);]]>
+</programlisting></term>
+<listitem>
+<para>This constructs a shallow copy of <literal>x</literal>.
+</para>
+
+<formalpara>
+<title>Complexity</title>
+<para> Constant time (for contrast, compare this to
+the <literal>multi_array</literal> class copy constructor.
+</para></formalpara>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</formalpara>
+
+
+<formalpara>
+<title>Modifiers</title>
+
+<variablelist>
+<varlistentry>
+
+<term><programlisting>
+<![CDATA[multi_array_ref& operator=(const multi_array_ref& x);
+template <class Array> multi_array_ref& operator=(const Array& x);]]>
+</programlisting>
+</term>
+
+<listitem>
+<para>This performs an element-wise copy of <literal>x</literal>
+into the current <literal>multi_array_ref</literal>.</para>
+
+<formalpara>
+<title><literal>Array</literal> Requirements</title>
+<para><literal>Array</literal> must model MultiArray. 
+</para></formalpara>
+
+<formalpara>
+<title>Preconditions</title>
+<para>
+<programlisting>std::equal(this->shape(),this->shape()+this->num_dimensions(),
+x.shape());</programlisting></para>
+</formalpara>
+
+
+<formalpara>
+<title>Postconditions</title>
+<para>
+<programlisting>(*.this) == x;</programlisting>
+</para>
+</formalpara>
+
+<formalpara>
+<title>Complexity</title>
+<para>The assignment operators perform 
+O(<literal>x.num_elements()</literal>) calls to <literal>element</literal>'s 
+copy constructor.</para></formalpara>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</formalpara>
+</sect2>