From 1e8a9db226d9ca6bd3df78ab136b69be43eed0d8 Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Sun, 25 Nov 2007 18:38:02 +0000 Subject: [PATCH] Full merge from trunk at revision 41356 of entire boost-root tree. [SVN r41370] --- doc/reference.html | 49 ++++++++++++++--------------- doc/test_cases.html | 15 +++++++++ doc/user.html | 44 ++++++++++++++------------ doc/xml/MultiArray.xml | 7 +++++ doc/xml/const_multi_array_ref.xml | 10 +++--- doc/xml/multi_array_ref.xml | 21 ++++++------- test/Jamfile.v2 | 2 ++ test/assert.cpp | 51 +++++++++++++++++++++++++++++++ test/concept_checks.cpp | 4 +-- test/resize.cpp | 8 +++++ test/slice.cpp | 22 +++++++++++++ test/storage_order_convert.cpp | 6 ++-- 12 files changed, 175 insertions(+), 64 deletions(-) create mode 100644 test/assert.cpp diff --git a/doc/reference.html b/doc/reference.html index 7cee519..a26a556 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -1,4 +1,4 @@ -Boost.MultiArray Reference Manual

Boost.MultiArray Reference Manual

Ronald Garcia

Indiana University
Open Systems Lab

Boost.MultiArray is composed of several components. +Boost.MultiArray Reference Manual

Boost.MultiArray Reference Manual

Ronald Garcia

Indiana University
Open Systems Lab

Boost.MultiArray is composed of several components. The MultiArray concept defines a generic interface to multidimensional containers. multi_array is a general purpose container class @@ -150,8 +150,8 @@ number of possible element layouts. For example, the elements of a 2 dimensional array can be stored by row (i.e., the elements of each row are stored contiguously) or by column (i.e., the elements of each column are stored contiguously). -

Notation

What follows are the descriptions of symbols that will be used -to describe the MultiArray interface.

Table 1. Notation

AA type that is a model of MultiArray +

Notation

What follows are the descriptions of symbols that will be used +to describe the MultiArray interface.

Table 1. Notation

AA type that is a model of MultiArray
a,bObjects of type A
NumDimsThe numeric dimension parameter associated with A.
DimsSome numeric dimension parameter such that 0<Dims<NumDims. @@ -159,8 +159,8 @@ to describe the MultiArray interface.

index_listAn object whose type models Collection
idxA signed integral value.
tmpAn object of type - boost::array<index,NumDims>

Associated Types

-

Table 2. Associated Types

TypeDescription
value_typeThis is the value type of the container. + boost::array<index,NumDims>

Associated Types

+

Table 2. Associated Types

TypeDescription
value_typeThis is the value type of the container. If NumDims == 1, then this is element. Otherwise, this is the value type of the immediately nested containers. @@ -260,7 +260,9 @@ It models MultiArray. const_array_view<Dims>::type This is the const view type with Dims dimensions. -

Valid expressions

Table 3. Valid Expressions

ExpressionReturn typeSemantics
a.shape()const size_type* +

Valid expressions

Table 3. Valid Expressions

ExpressionReturn typeSemantics
A::dimensionalitysize_typeThis compile-time constant represents the number of +dimensions of the array (note that +A::dimensionality == NumDims).
a.shape()const size_type* This returns a list of NumDims elements specifying the extent of each array dimension.
a.strides()const index* @@ -358,11 +360,11 @@ type must model
a >= bboolThis performs a lexicographical comparison of the values of a and b. The element type must model LessThanComparable for this -expression to be valid.

Complexity guarantees

begin() and end() execute in amortized +expression to be valid.

Complexity guarantees

begin() and end() execute in amortized constant time. size() executes in at most linear time in the MultiArray's size. -

Invariants

Table 4. Invariants

Valid range[a.begin(),a.end()) is a valid range. +

Invariants

Table 4. Invariants

Valid range[a.begin(),a.end()) is a valid range.
Range size a.size() == std::distance(a.begin(),a.end());.
Completeness @@ -374,7 +376,7 @@ Calling a[a1][a2]...[aN] where a(index_list), where index_list is a Collection containing the values a1...aN. -

Associated Types for Views

The following MultiArray associated +


Associated Types for Views

The following MultiArray associated types define the interface for creating views of existing MultiArrays. Their interfaces and roles in the concept are described below.

index_range

index_range objects represent half-open @@ -401,10 +403,10 @@ operators, a half open range [5,10) can be specified as follows: The following describes the index_range interface. -

Table 5. Notation

iAn object of type index_range.
idx,idx1,idx2,idx3Objects of type index.

Table 6. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to +

Table 5. Notation

iAn object of type index_range.
idx,idx1,idx2,idx3Objects of type index.

Table 6. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to specify the start, finish, and stride values.
size_typeThis is an unsigned integral type. It is used to report the size of the range an index_range -represents.

Table 7. Valid Expressions

ExpressionReturn typeSemantics
index_range(idx1,idx2,idx3)index_rangeThis constructs an index_range +represents.

Table 7. Valid Expressions

ExpressionReturn typeSemantics
index_range(idx1,idx2,idx3)index_rangeThis constructs an index_range representing the interval [idx1,idx2) with stride idx3.
index_range(idx1,idx2)index_rangeThis constructs an index_range representing the interval [idx1,idx2) @@ -436,14 +438,14 @@ value. This notation includes of i up by idx. It is equivalent to index_range(r.start()+idx1, r.finish()+idx, r.stride())
i - idxindexThis expression shifts the start and finish values of i up by idx. It is equivalent to -index_range(r.start()-idx1, r.finish()-idx, r.stride())

index_gen

index_gen aggregates +index_range(r.start()-idx1, r.finish()-idx, r.stride())


index_gen

index_gen aggregates index_range objects in order to specify view parameters. Chained calls to operator[] store range and dimension information used to instantiate a new view into a MultiArray. -

Table 8. Notation

Dims,RangesUnsigned integral values.
xAn object of type +

Table 8. Notation

Dims,RangesUnsigned integral values.
xAn object of type template gen_type<Dims,Ranges>::type.
iAn object of type -index_range.
idxObjects of type index.

Table 9. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to +index_range.
idxObjects of type index.

Table 9. Associated Types

TypeDescription
indexThis is a signed integral type. It is used to specify degenerate dimensions.
size_typeThis is an unsigned integral type. It is used to report the size of the range an index_range represents.
@@ -454,7 +456,7 @@ represents.
degenerate ranges specified (i.e. calls to operator[](index)). Note that index_gen and -gen_type<0,0>::type are the same type.

Table 10. Valid Expressions

ExpressionReturn typeSemantics
index_gen()gen_type<0,0>::typeThis constructs an index_gen +gen_type<0,0>::type are the same type.

Table 10. Valid Expressions

ExpressionReturn typeSemantics
index_gen()gen_type<0,0>::typeThis constructs an index_gen object. This object can then be used to generate tuples of index_range values.
x[i]gen_type<Dims+1,Ranges+1>::type Returns a new object containing all previous @@ -468,7 +470,7 @@ range, index_range(idx,idx). Note that this is NOT equivalent to x[index_range(idx,idx)]., which will return an object of type gen_type<Dims+1,Ranges+1>::type. -

Models

  • multi_array
  • multi_array_ref
  • const_multi_array_ref
  • template array_view<Dims>::type
  • template const_array_view<Dims>::type
  • template subarray<Dims>::type
  • template const_subarray<Dims>::type

Array Components

+


Models

  • multi_array
  • multi_array_ref
  • const_multi_array_ref
  • template array_view<Dims>::type
  • template const_array_view<Dims>::type
  • template subarray<Dims>::type
  • template const_subarray<Dims>::type

Array Components

Boost.MultiArray defines an array class, multi_array, and two adapter classes, multi_array_ref and @@ -813,8 +815,7 @@ not described in the multi_array reference. namespace boost { template <typename ValueType, - std::size_t NumDims, - typename Allocator = std::allocator<ValueType> > + std::size_t NumDims> class multi_array_ref { public: // types: @@ -973,7 +974,7 @@ namespace boost { template <typename ValueType, std::size_t NumDims, - typename Allocator = std::allocator<ValueType> > + typename TPtr = const T*> class const_multi_array_ref { public: // types: @@ -1004,9 +1005,9 @@ public: // structors template <typename ExtentList> - explicit const_multi_array_ref(const element* data, const ExtentList& sizes, + explicit const_multi_array_ref(TPtr data, const ExtentList& sizes, const storage_order_type& store = c_storage_order()); - explicit const_multi_array_ref(const element* data, const extents_tuple& ranges, + explicit const_multi_array_ref(TPtr 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(); @@ -1054,7 +1055,7 @@ public: };

Constructors. 

template <typename ExtentList>
-explicit const_multi_array_ref(const element* data, 
+explicit const_multi_array_ref(TPtr data, 
                      const ExtentList& sizes,
                      const storage_order& store = c_storage_order());
 

@@ -1066,7 +1067,7 @@ dimensions.

ExtentList Requirements.  ExtentList must model Collection.

Preconditions. sizes.size() == NumDims;

-
explicit const_multi_array_ref(const element* data,
+
explicit const_multi_array_ref(TPtr data,
                      extent_gen::gen_type<NumDims>::type ranges,
                      const storage_order& store = c_storage_order());
 

Effects.  @@ -1171,7 +1172,7 @@ operator[](index idx) const;

This function returns a ne extent_range objects in addition to extent_range(0,idx). This function gives the array constructors a similar syntax to traditional C multidimensional array -declaration.

Global Objects

For syntactic convenience, Boost.MultiArray defines two +declaration.

Global Objects

For syntactic convenience, Boost.MultiArray defines two global objects as part of its interface. These objects play the role of object generators; expressions involving them create other objects of interest. diff --git a/doc/test_cases.html b/doc/test_cases.html index 7cb4ce1..56d9b43 100644 --- a/doc/test_cases.html +++ b/doc/test_cases.html @@ -114,6 +114,13 @@ Test re-indexing functionality for the B.M primary components. + +libs/multi_array/test/storage_order_convert.cpp + +Test out conversions among the storage orders data types. + + + libs/multi_array/test/storage_order.cpp @@ -164,6 +171,14 @@ Ensure that all the array types meet the defined Concepts. + +libs/multi_array/test/assert.cpp + +Ensure that uses of BOOST_ASSERT within the library can be customized +by library users. + + + libs/multi_array/test/generative_tests.hpp diff --git a/doc/user.html b/doc/user.html index e669a85..c63ec23 100644 --- a/doc/user.html +++ b/doc/user.html @@ -255,7 +255,9 @@ useful for writing dimension-independent code.

The second method involves passing the constructor an extent_gen -object, specifying the matrix dimensions. By default, the library constructs a +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 @@ -316,13 +318,17 @@ 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[]. -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. +

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

@@ -335,7 +341,8 @@ including the library header. A simple sub-view creation example follows.
   // dim 2: [0,4) (strided by 2), 
   // 
 
-  typedef array_type::index_range range;
+  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)] ];
 
@@ -361,7 +368,7 @@ called slicing).
   // [0,1,2), 1, [0,2,4) 
   // 
 
-  typedef array_type::index_range range;
+  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)] ];
@@ -382,7 +389,7 @@ that specify the same range.
   // [base,stride,bound)
   // [0,2,4) 
 
-  typedef array_type::index_range range;
+  typedef boost::multi_array_types::index_range range;
   range a_range;
   a_range = range(0,4,2);
   a_range = range().start(0).finish(4).stride(2);
@@ -402,7 +409,7 @@ dimension it is used to specify.
 

Example

-  typedef array_type::index_range range;
+  typedef boost::multi_array_types::index_range range;
   range a_range;
 
   // All elements in this dimension
@@ -482,13 +489,16 @@ stored in ascending or descending order.
 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 to
-the extent_gen constructor in order to set the base value. 
+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. 
+
 

Example

   typedef boost::multi_array<double, 3> array_type;
-  typedef array_type::extent_range range;
+  typedef boost::multi_array_types::extent_range range;
+  // OR typedef array_type::extent_range range;
 
   array_type::extent_gen extents;
  
@@ -507,7 +517,6 @@ reset the bases.  To set all bases to the same value, use the
 
   typedef boost::multi_array<double, 3> array_type;
-  typedef array_type::extent_range range;
 
   array_type::extent_gen extents;
  
@@ -524,7 +533,6 @@ An alternative is to set each base separately using the
 
   typedef boost::multi_array<double, 3> array_type;
-  typedef array_type::extent_range range;
 
   array_type::extent_gen extents;
  
@@ -548,7 +556,6 @@ elements contained remains the same.
 
   typedef boost::multi_array<double, 3> array_type;
-  typedef array_type::extent_range range;
 
   array_type::extent_gen extents;
   array_type A(extents[2][3][4]);
@@ -577,7 +584,6 @@ no longer be available.
 
   typedef boost::multi_array<int, 3> array_type;
-  typedef array_type::extent_range range;
 
   array_type::extent_gen extents;
   array_type A(extents[3][3][3]);
diff --git a/doc/xml/MultiArray.xml b/doc/xml/MultiArray.xml
index 921f334..755528e 100644
--- a/doc/xml/MultiArray.xml
+++ b/doc/xml/MultiArray.xml
@@ -385,6 +385,13 @@ This is the const view type with Dims dimensions.
 	  
 	
 	
+	  
+	    A::dimensionality
+	    size_type
+	    This compile-time constant represents the number of
+dimensions of the array (note that 
+A::dimensionality == NumDims).
+	  
 	  
 	    a.shape()
 	    const size_type*
diff --git a/doc/xml/const_multi_array_ref.xml b/doc/xml/const_multi_array_ref.xml
index cd845a6..edf43bf 100644
--- a/doc/xml/const_multi_array_ref.xml
+++ b/doc/xml/const_multi_array_ref.xml
@@ -33,7 +33,7 @@ namespace boost {
 
 template  >
+          typename TPtr = const T*>
 class const_multi_array_ref {
 public:
 // types:
@@ -64,9 +64,9 @@ public:
   // structors
 
   template 
-  explicit const_multi_array_ref(const element* data, const ExtentList& sizes,
+  explicit const_multi_array_ref(TPtr data, const ExtentList& sizes,
                        const storage_order_type& store = c_storage_order());
-  explicit const_multi_array_ref(const element* data, const extents_tuple& ranges,
+  explicit const_multi_array_ref(TPtr 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();
@@ -122,7 +122,7 @@ public:
 
 
 template <typename ExtentList>
-explicit const_multi_array_ref(const element* data, 
+explicit const_multi_array_ref(TPtr data, 
                      const ExtentList& sizes,
                      const storage_order& store = c_storage_order());
 
@@ -151,7 +151,7 @@ dimensions.
 
 
 
-::type ranges,
                      const storage_order& store = c_storage_order());]]>
  
diff --git a/doc/xml/multi_array_ref.xml b/doc/xml/multi_array_ref.xml
index a4fb8ef..c11230b 100644
--- a/doc/xml/multi_array_ref.xml
+++ b/doc/xml/multi_array_ref.xml
@@ -31,27 +31,26 @@ not described in the multi_array reference.
 namespace boost {
 
 template  >
+          std::size_t NumDims>
 class multi_array_ref {
 public:
 // types:
   typedef ValueType                             element;
-  typedef *implementation-defined*              value_type;
-  typedef *implementation-defined*              reference;
-  typedef *implementation-defined*              const_reference;
-  typedef *implementation-defined*              difference_type;
-  typedef *implementation-defined*              iterator;
-  typedef *implementation-defined*              const_iterator;
-  typedef *implementation-defined*              reverse_iterator;
-  typedef *implementation-defined*              const_reverse_iterator;
+  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 *implementation-defined*              storage_order_type;
+  typedef *unspecified*                         storage_order_type;
   
   // template typedefs
   template  struct            subarray;
diff --git a/test/Jamfile.v2 b/test/Jamfile.v2
index c9b4e1e..066e724 100644
--- a/test/Jamfile.v2
+++ b/test/Jamfile.v2
@@ -37,11 +37,13 @@ test-suite multi_array
       [ run assign.cpp ../../test/build//boost_test_exec_monitor ]
       [ run assign_to_array.cpp ../../test/build//boost_test_exec_monitor ]
       [ run index_bases.cpp ../../test/build//boost_test_exec_monitor ]
+      [ run storage_order_convert.cpp ../../test/build//boost_test_exec_monitor ]
       [ run storage_order.cpp ../../test/build//boost_test_exec_monitor ]
       [ run reshape.cpp ../../test/build//boost_test_exec_monitor ]
       [ run range1.cpp ../../test/build//boost_test_exec_monitor  ]
       [ run idxgen1.cpp ../../test/build//boost_test_exec_monitor ]
       [ run stl_interaction.cpp ../../test/build//boost_test_exec_monitor ]
       [ run resize.cpp ../../test/build//boost_test_exec_monitor ]
+      [ run assert.cpp ../../test/build//boost_test_exec_monitor ]
       [ compile concept_checks.cpp ]
     ;
diff --git a/test/assert.cpp b/test/assert.cpp
new file mode 100644
index 0000000..da14c54
--- /dev/null
+++ b/test/assert.cpp
@@ -0,0 +1,51 @@
+// Copyright 2007 The Trustees of Indiana University.
+
+// Use, modification and distribution is subject to the Boost Software 
+// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+//  Boost.MultiArray Library
+//  Authors: Ronald Garcia
+//           Jeremy Siek
+//           Andrew Lumsdaine
+//  See http://www.boost.org/libs/multi_array for documentation.
+
+//
+// Using the BOOST.ASSERT mechanism to replace library assertions 
+// with exceptions
+//
+
+#include "boost/test/minimal.hpp"
+
+#define BOOST_ENABLE_ASSERT_HANDLER
+#include "boost/multi_array.hpp" // includes assert.hpp
+
+#include 
+
+namespace boost {
+  void assertion_failed(char const* expr, char const* function,
+                        char const* file, long line) {
+    throw std::runtime_error(expr);
+  }
+} // namespace boost
+
+using namespace boost;
+
+int
+test_main(int,char*[]) {
+
+  typedef multi_array array_t;
+
+  array_t A(extents[2][2]);
+
+  array_t B(extents[3][3]);
+
+  try {
+    A = B;
+    BOOST_ERROR("did not throw an exception");
+  } catch (std::runtime_error&) {
+    //...all good
+  }
+
+  return boost::exit_success;
+}
diff --git a/test/concept_checks.cpp b/test/concept_checks.cpp
index 2a91034..78ec9a8 100644
--- a/test/concept_checks.cpp
+++ b/test/concept_checks.cpp
@@ -20,8 +20,8 @@
 #include "boost/multi_array.hpp"
 
 #include "boost/cstdlib.hpp"
-#define BOOST_INCLUDE_MAIN
-#include "boost/test/test_tools.hpp"
+
+#include "boost/test/minimal.hpp"
 
 #include "boost/array.hpp"
 
diff --git a/test/resize.cpp b/test/resize.cpp
index d200f8b..c00e740 100644
--- a/test/resize.cpp
+++ b/test/resize.cpp
@@ -114,6 +114,14 @@ int test_main(int,char*[]) {
     }
   }
 
+  // Resizing that changes index bases too (impl bug caused an assert)
+  {
+      typedef boost::multi_array ar_t;
+      typedef ar_t::extent_range range;
+      ar_t ar;
+      ar.resize(boost::extents[range(-3, 3)]);
+  }
+
 
   return boost::exit_success;
 }
diff --git a/test/slice.cpp b/test/slice.cpp
index b6ff77a..5406c81 100644
--- a/test/slice.cpp
+++ b/test/slice.cpp
@@ -90,6 +90,28 @@ void test_views(Array& A, const ViewTraits&) {
         BOOST_CHECK(B(elmts) == A[idx0+i][idx1+1][idx2+j*2]);
       }
   }
+
+  // Flip the third dimension
+  {
+    typename ViewTraits::array_view3 B = A[
+      indices[range(idx0+0,idx0+2)]
+             [range(idx1+0,idx1+2)]
+             [range(idx2+2,idx2+0,-1)]
+    ];
+
+    //    typename ViewTraits::array_view3 B =
+    //      A[indices[range(idx0+0,idx0+2)][idx1+1][range(idx2+0,idx2+4,2)]];
+    
+    for (index i = 0; i != 2; ++i)
+      for (index j = 0; j != 2; ++j) 
+        for (index k = 0; k != 2; ++k) {
+        BOOST_CHECK(B[i][j][k] == A[idx0+i][idx1+j][idx2+2-k]);
+        boost::array elmts;
+        elmts[0]=i; elmts[1]=j; elmts[2]=k;
+        BOOST_CHECK(B(elmts) == A[idx0+i][idx1+j][idx2+2-k]);
+      }
+  }
+
   ++tests_run;
 }
 
diff --git a/test/storage_order_convert.cpp b/test/storage_order_convert.cpp
index e5aa34c..5952584 100644
--- a/test/storage_order_convert.cpp
+++ b/test/storage_order_convert.cpp
@@ -31,9 +31,9 @@ test_main(int,char*[]) {
   general_storage_order<5> fortran_storage(fortran_ordering.begin(),
                                            ascending.begin());
  
-  BOOST_TEST(c_storage == (general_storage_order<5>) c_storage_order());
-  BOOST_TEST(fortran_storage ==
+  BOOST_CHECK(c_storage == (general_storage_order<5>) c_storage_order());
+  BOOST_CHECK(fortran_storage ==
              (general_storage_order<5>) fortran_storage_order());
 
-  return boost::report_errors();
+  return boost::exit_success;
 }