From 38a335e3e724cff48cf627bf6744017b148b0eb8 Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Wed, 30 Aug 2000 12:44:40 +0000 Subject: [PATCH] Changes reflecting formal review comments [SVN r7689] --- array.hpp.html | 325 +++++++++++++++++++++++++----------------------- array.htm | 310 --------------------------------------------- array.html | 320 +++++++++++++++++++++++++++++++++++++++++++++++ array5.cpp | 11 +- array5.cpp.html | 11 +- print.hpp | 28 +++++ 6 files changed, 526 insertions(+), 479 deletions(-) delete mode 100644 array.htm create mode 100644 array.html create mode 100644 print.hpp diff --git a/array.hpp.html b/array.hpp.html index 94a84f6..830f54a 100644 --- a/array.hpp.html +++ b/array.hpp.html @@ -1,162 +1,169 @@ - - - -array.hpp - - - - - + + +array.hpp + +   - - - - -
 array.hpp
-
-
-
-/* The following code declares class array,
- * an STL container (as wrapper) for arrays of constant size.
- *
- * See
- *      http://www.josuttis.com/cppcode
- * for details and the latest version.
- *
- * (C) Copyright Nicolai M. Josuttis 1999.
- * Permission to copy, use, modify, sell and distribute this software
- * is granted provided this copyright notice appears in all copies.
- * This software is provided "as is" without express or implied
- * warranty, and with no claim as to its suitability for any purpose.
- *
- * Jul 31, 2000
- */
-#ifndef BOOST_ARRAY_HPP
-#define BOOST_ARRAY_HPP
-
-#include <cstddef>
-#include <stdexcept>
-#include <iterator>
-#include <algorithm>
-
-// BUG-FIX for compilers that don't support
-// std::size_t and std::ptrdiff_t yet
-// (such as gcc)
-#include <boost/config.hpp>
-
-namespace boost {
-
-    template<class T, std::size_t N>
-    class array {
-      public:
-        T elems[N];    // fixed-size array of elements of type T
-
-      public:
-        // type definitions
-        typedef T              value_type;
-        typedef T*             iterator;
-        typedef const T*       const_iterator;
-        typedef T&             reference;
-        typedef const T&       const_reference;
-        typedef std::size_t    size_type;
-        typedef std::ptrdiff_t difference_type;
-    
-        // iterator support
-        iterator begin() { return elems; }
-        const_iterator begin() const { return elems; }
-        iterator end() { return elems+N; }
-        const_iterator end() const { return elems+N; }
-    
-        // reverse iterator support
-        typedef std::reverse_iterator<iterator> reverse_iterator;
-        typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
-        reverse_iterator rbegin() { return reverse_iterator(end()); }
-        const_reverse_iterator rbegin() const {
-            return const_reverse_iterator(end());
-        }
-        reverse_iterator rend() { return reverse_iterator(begin()); }
-        const_reverse_iterator rend() const {
-            return const_reverse_iterator(begin());
-        }
-
-        // operator[]
-        reference operator[](size_type i) { return elems[i]; }
-        const_reference operator[](size_type i) const { return elems[i]; }
-
-        // at() with range check
-        // note: rangecheck() is public because we have implemented array
-        //       as aggregate, which forbids non-public members
-        void rangecheck (size_type i) const {
-            if (i >= size()) { throw std::range_error("array"); }
-        }
-        reference at(size_type i) { rangecheck(i); return elems[i]; }
-        const_reference at(size_type i) const { rangecheck(i); return elems[i]; }
-    
-        // front() and back()
-        reference front() { return elems[0]; }
-        const_reference front() const { return elems[0]; }
-        reference back() { return elems[N-1]; }
-        const_reference back() const { return elems[N-1]; }
-
-        // size is constant
-        static size_type size() { return N; }
-        static bool empty() { return false; }
-        static size_type max_size() { return N; }
-        enum { static_size = N };
-
-        // swap (note: linear complexity)
-        void swap (array& y) {
-            std::swap_ranges(begin(),end(),y.begin());
-        }
-
-        // direct access to data
-        const T* data() const { return elems; }
-
-        // assignment with type conversion
-        //template <typename T2>
-        //T& operator= (const array<T2,N>& rhs) {
-        //    std::copy (begin(),end(),rhs.begin());
-        //}
-    };
-
-    // comparisons
-    template<class T, std::size_t N>
-    bool operator== (const array<T,N>& x, const array<T,N>& y) {
-        return std::equal(x.begin(), x.end(), y.begin());
-    }
-    template<class T, std::size_t N>
-    bool operator< (const array<T,N>& x, const array<T,N>& y) {
-        return std::lexicographical_compare(x.begin(),x.end(),y.begin(),y.end());
-    }
-    template<class T, std::size_t N>
-    bool operator!= (const array<T,N>& x, const array<T,N>& y) {
-        return !(x==y);
-    }
-    template<class T, std::size_t N>
-    bool operator> (const array<T,N>& x, const array<T,N>& y) {
-        return y<x;
-    }
-    template<class T, std::size_t N>
-    bool operator<= (const array<T,N>& x, const array<T,N>& y) {
-        return !(y<x);
-    }
-    template<class T, std::size_t N>
-    bool operator>= (const array<T,N>& x, const array<T,N>& y) {
-        return !(x<y);
-    }
-
-    // global swap()
-    template<class T, std::size_t N>
-    inline void swap (const array<T,N>& x, const array<T,N>& y) {
-        x.swap(y);
-    }
-
-} /* namespace boost */
-
-#endif /*BOOST_ARRAY_HPP*/
- + +
+ + array.hpp + +

- - - +

+ + +/* The following code declares class array,
+ * an STL container (as wrapper) for arrays of constant size.
+ *
+ * See
+ *      http://www.josuttis.com/cppcode
+ * for details and the latest version.
+ *
+ * (C) Copyright Nicolai M. Josuttis 1999.
+ * Permission to copy, use, modify, sell and distribute this software
+ * is granted provided this copyright notice appears in all copies.
+ * This software is provided "as is" without express or implied
+ * warranty, and with no claim as to its suitability for any purpose.
+ *
+ * Jul 31, 2000
+ */
+#ifndef BOOST_ARRAY_HPP
+#define BOOST_ARRAY_HPP
+
+#include <cstddef>
+#include <stdexcept>
+#include <iterator>
+#include <algorithm>
+
+// BUG-FIX for compilers that don't support
+// std::size_t and std::ptrdiff_t yet
+// (such as gcc)
+#include <boost/config.hpp>
+
+namespace boost {
+
+    template<class T, std::size_t N>
+    class array {
+      public:
+        T elems[N];    // fixed-size array of elements of type T
+
+      public:
+        // type definitions
+        typedef T              value_type;
+        typedef T*             iterator;
+        typedef const T*       const_iterator;
+        typedef T&             reference;
+        typedef const T&       const_reference;
+        typedef std::size_t    size_type;
+        typedef std::ptrdiff_t difference_type;
+    
+        // iterator support
+        iterator begin() { return elems; }
+        const_iterator begin() const { return elems; }
+        iterator end() { return elems+N; }
+        const_iterator end() const { return elems+N; }
+
+        // reverse iterator support
+        typedef std::reverse_iterator<iterator> reverse_iterator;
+        typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
+        reverse_iterator rbegin() { return reverse_iterator(end()); }
+        const_reverse_iterator rbegin() const {
+            return const_reverse_iterator(end());
+        }
+        reverse_iterator rend() { return reverse_iterator(begin()); }
+        const_reverse_iterator rend() const {
+            return const_reverse_iterator(begin());
+        }
+
+        // operator[]
+        reference operator[](size_type i) { return elems[i]; }
+        const_reference operator[](size_type i) const { return elems[i]; }
+
+        // at() with range check
+        reference at(size_type i) { rangecheck(i); return elems[i]; }
+        const_reference at(size_type i) const { rangecheck(i); return elems[i]; }
+    
+        // front() and back()
+        reference front() { return elems[0]; }
+        const_reference front() const { return elems[0]; }
+        reference back() { return elems[N-1]; }
+        const_reference back() const { return elems[N-1]; }
+
+        // size is constant
+        static size_type size() { return N; }
+        static bool empty() { return false; }
+        static size_type max_size() { return N; }
+        enum { static_size = N };
+
+  public:
+        // swap (note: linear complexity)
+        void swap (array<T,N>& y) {
+            std::swap_ranges(begin(),end(),y.begin());
+        }
+
+        // direct access to data
+        const T* data() const { return elems; }
+
+        // assignment with type conversion
+        template <typename T2>
+        array<T,N>& operator= (const array<T2,N>& rhs) {
+            std::copy(rhs.begin(),rhs.end(), begin());
+            return *this;
+        }
+
+        // assign one value to all elements
+        void assign (const T& value)
+        {
+            std::fill_n(begin(),size(),value);
+        }
+
+      private:
+        // check range (may be private because it is static)
+        static void rangecheck (size_type i) {
+            if (i >= size()) { throw std::range_error("array"); }
+        }
+
+    };
+
+    // comparisons
+    template<class T, std::size_t N>
+    bool operator== (const array<T,N>& x, const array<T,N>& y) {
+        return std::equal(x.begin(), x.end(), y.begin());
+    }
+    template<class T, std::size_t N>
+    bool operator< (const array<T,N>& x, const array<T,N>& y) {
+        return std::lexicographical_compare(x.begin(),x.end(),y.begin(),y.end());
+    }
+    template<class T, std::size_t N>
+    bool operator!= (const array<T,N>& x, const array<T,N>& y) {
+        return !(x==y);
+    }
+    template<class T, std::size_t N>
+    bool operator> (const array<T,N>& x, const array<T,N>& y) {
+        return y<x;
+    }
+    template<class T, std::size_t N>
+    bool operator<= (const array<T,N>& x, const array<T,N>& y) {
+        return !(y<x);
+    }
+    template<class T, std::size_t N>
+    bool operator>= (const array<T,N>& x, const array<T,N>& y) {
+        return !(x<y);
+    }
+
+    // global swap()
+    template<class T, std::size_t N>
+    inline void swap (array<T,N>& x, array<T,N>& y) {
+        x.swap(y);
+    }
+
+} /* namespace boost */
+
+#endif /*BOOST_ARRAY_HPP*/
+ + + + diff --git a/array.htm b/array.htm deleted file mode 100644 index 7fee4a5..0000000 --- a/array.htm +++ /dev/null @@ -1,310 +0,0 @@ - - - - - - - - - -array.hpp, an STL Array Wrapper - - - - -  - - - - -
Class - array, an STL Container (as - Wrapper) for Arrays of Constant Size
-

The C++ Standard Template -Library STL as part of the C++ Standard Library provides a framework for -processing algorithms on different kind of containers. However, ordinary arrays -don't provide the interface of STL containers (although, they provide the -iterator interface of STL containers). -

As replacement for -ordinary arrays, the STL provides class vector<>. -However, vector<> provides -the semantics of dynamic arrays. Thus, it manages data to be able to change the -number of elements. This results in some overhead in case only arrays with -static size are needed. -

In his book, Generic -Programming and the STL, Matthew H. Austern introduces a useful wrapper -class for ordinary arrays with static size, called block. -It is safer and has no worse performance than ordinary arrays. In The C++ -Programming Language, 3rd edition, Bjarne Stroustrup introduces a similar -class, called c_array, -which I (Nicolai Josuttis) present -slightly modified in my book The C++ Standard Library - A Tutorial and -Reference, called carray. -This is the essence of these approaches spiced with many feedback from boost. -

After considering -different names, we decided to name this class simply array. -

The class provides the -following interface: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Types:
value_typetype of the elements
iteratortype of the iterator - (random-access iterator)
const_iteratortype of iterator - that considers elements as being constant
referencetype of element - reference
const_referencetype of element - reference that considers elements as being constant
size_typetype for signed size - values
difference_typetype for unsigned - difference values
Operations:
-

array<type,num>

- 		default constructor, - creates array of num - element of type, see - comment below
array<type,num>(a)copy constructor, - copies all elements of a - (a must have same type - and num)
operator=assignment, assigns - all elements
begin()returns iterator for - the first element
end()returns iterator for - position after the last element
rbegin()returns reverse - iterator for position of first element of reverse iteration
rend()returns reverse - iterator for posistion behind last element of reverese iteration
operator[i]returns element with - index i (no range - checking)
at(i)returns element with - index i (throw - std::range_error if i - is not valid)
front()returns first - element (caller has to ensure that it exists)
back()returns last element - (caller has to ensure that it exists)
data()returns raw element - array for read-only element access
size()returns number of - elements
empty()returns whether - array is empty
max_size()returns maximum - possible number of elements (same as size())
swap(a)swap elements with - array a
==, - !=checks for equality
<, - <=, >, - >=compares array
Values: 
static_sizeyields size at - compile time
-

Class array fulfills most -but not all of the requirements of "reversible containers" (see -Section 23.1, [lib.container.requirements] of the C++ Standard). The reasons -array is not an reversible STL container is because:
-- No constructors are provided
-- Elements may have an indetermined initial value (see below)
-- swap() has no constant complexity
-- size() is always constant, based on the second template argument of the type
-- The container provides no allocator support -

It doesn't fulfill the -requirements of a "sequence" (see Section 23.1.1, [lib.sequence.reqmts] -of the C++ Standard), except that
-- front() and back() are provided
-- operator[] and at() are provided -

Regarding the -constructors there was an important design tradeoff: We could implement array as -an "aggregate" (see Section 8.5.1, [dcl.init.aggr], of the C++ -Standard). This would mean:

- -

The current -implementation useus this approach. However, being able to have indetermined -initial values is a big drawback. So, please give me some feedback, how useful -you consider this feature to be. This leads to the list of Open issues: -

-

I'd appreciate any constructive feedback. -Please note: I don't have time to read all boost mails. Thus, to make sure -that feedback arrives me, please send me a copy of each mail regarding this -class. -

The code is provided "as -is" without expressed or implied warranty. -

array.hpp, the -implementation of array<>: -as -HTML file as -plain file -

Simple Example for using array<>: -as HTML file -as plain file -

Another Example for using array<>: -as HTML file -as plain file -

A third Example for using array<>: -as HTML file -as plain file -

An Example for using arrays -of arrays: -as HTML file -as plain file -

An Example for testing other -operations of array<>: -as HTML file -as plain file -

To find more details about using -ordinary arrays in C++ and the framework of the STL, see e.g.
-     The C++ -Standard Library - A Tutorial and Reference
-     by Nicolai -M. Josuttis
-     Addison Wesley Longman, 1999
-     ISBN 0-201-37926-0
- -

Home -Page of Nicolai Josuttis
-  - - - - diff --git a/array.html b/array.html new file mode 100644 index 0000000..8ddb880 --- /dev/null +++ b/array.html @@ -0,0 +1,320 @@ + + + + + + +array.hpp, an STL Array Wrapper + + +  + + + + +
Class + array, an STL Container (as + Wrapper) for Arrays of Constant Size
+

The C++ Standard Template + Library STL as part of the C++ Standard Library provides a framework for processing + algorithms on different kind of containers. However, ordinary arrays don't provide + the interface of STL containers (although, they provide the iterator interface + of STL containers). +

As replacement for ordinary + arrays, the STL provides class vector<>. + However, vector<> provides + the semantics of dynamic arrays. Thus, it manages data to be able to change + the number of elements. This results in some overhead in case only arrays with + static size are needed. +

In his book, Generic + Programming and the STL, Matthew H. Austern introduces a useful wrapper + class for ordinary arrays with static size, called block. + It is safer and has no worse performance than ordinary arrays. In The C++ + Programming Language, 3rd edition, Bjarne Stroustrup introduces a similar + class, called c_array, + which I (Nicolai Josuttis) present slightly + modified in my book The C++ Standard Library - A Tutorial and Reference, + called carray. This is + the essence of these approaches spiced with many feedback from boost. +

After considering different + names, we decided to name this class simply array. +

The class provides the + following interface: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Types:
value_typetype of the elements
iteratortype of the iterator + (random-access iterator)
const_iteratortype of iterator that + considers elements as being constant
referencetype of element reference
const_referencetype of element reference + that considers elements as being constant
size_typetype for signed size + values
difference_typetype for unsigned + difference values
Operations:
+

array<type,num>

+ 		default constructor, + creates array of num + element of type, see + comment below
array<type,num>(a)copy constructor, + copies all elements of a + (a must have same + type + and num)
operator=assignment, assigns + all elements
assign(val)assigns val + to all elements
begin()returns iterator for + the first element
end()returns iterator for + position after the last element
rbegin()returns reverse iterator + for position of first element of reverse iteration
rend()returns reverse iterator + for posistion behind last element of reverese iteration
operator[i]returns element with + index i (no range + checking)
at(i)returns element with + index i (throw std::range_error + if i is not valid)
front()returns first element + (caller has to ensure that it exists)
back()returns last element + (caller has to ensure that it exists)
data()returns raw element + array for read-only element access
size()returns number of + elements
empty()returns whether array + is empty
max_size()returns maximum possible + number of elements (same as size())
swap(a)swap elements with + array a
==, + !=checks for equality
<, + <=, >, + >=compares array
Values: 
static_sizeyields size at compile + time
+

Class array fulfills most + but not all of the requirements of "reversible containers" (see Section + 23.1, [lib.container.requirements] of the C++ Standard). The reasons array is + not an reversible STL container is because:
+ - No constructors are provided
+ - Elements may have an indetermined initial value (see below)
+ - swap() has no constant complexity
+ - size() is always constant, based on the second template argument of the type
+ - The container provides no allocator support +

It doesn't fulfill the + requirements of a "sequence" (see Section 23.1.1, [lib.sequence.reqmts] + of the C++ Standard), except that
+ - front() and back() are provided
+ - operator[] and at() are provided +

Regarding the constructors + there was an important design tradeoff: We could implement array as an "aggregate" + (see Section 8.5.1, [dcl.init.aggr], of the C++ Standard). This would mean:

+ +

The current implementation + useus this approach. However, being able to have indetermined initial values + is a big drawback. So, please give me some feedback, how useful you consider + this feature to be. This leads to the list of Open issues: +

+

I'd appreciate any constructive feedback. + Please note: I don't have time to read all boost mails. Thus, to make sure + that feedback arrives me, please send me a copy of each mail regarding this + class. +

The code is provided "as is" without + expressed or implied warranty. +

array.hpp, the implementation + of array<>: +

  • + as HTML file
    • +
  • + as plain file
    • +

    Simple Example for using array<>: +

  • + as HTML file
    • +
  • + as plain file
    • +

    Another Example for using array<>: +

  • + as HTML file
    • +
  • + as plain file
    • +

    A third Example for using array<>: +

  • + as HTML file
    • +
  • + as plain file
    • +

    An Example for using arrays + of arrays: +

  • as HTML + file
    • +
  • as plain file
    • +

    An Example for testing other operations + of array<>: +

  • as HTML + file
    • +
  • as plain file
    • +

    All files +

  • as ZIP file + (24KB)
    • +
  • as TGZ file + (13KB)
    +
    + To find more details about using ordinary arrays in C++ and the framework of + the STL, see e.g.
    +      The C++ + Standard Library - A Tutorial and Reference
    +      by Nicolai + M. Josuttis
    +      Addison Wesley Longman, 1999
    +      ISBN 0-201-37926-0
    +
    • +

    Home + Page of Nicolai Josuttis
    +       + + diff --git a/array5.cpp b/array5.cpp index 0f932c2..f9c1b92 100644 --- a/array5.cpp +++ b/array5.cpp @@ -54,10 +54,11 @@ int main() << std::endl; } - //typedef boost::array DArray; - //typedef boost::array IArray; - //IArray ia = { { 1, 2, 3, 4, 5, 6 } }; - //DArray da; - //da.assign(ia); + typedef boost::array DArray; + typedef boost::array IArray; + IArray ia = { 1, 2, 3, 4, 5, 6 }; + DArray da; + da = ia; + da.assign(42); } diff --git a/array5.cpp.html b/array5.cpp.html index 3428a16..1d89b0a 100644 --- a/array5.cpp.html +++ b/array5.cpp.html @@ -71,11 +71,12 @@ int main()
              << std::endl;
        }

    -    //typedef boost::array<double,6> DArray;
    -    //typedef boost::array<int,6> IArray;
    -    //IArray ia = { { 1, 2, 3, 4, 5, 6 } };
    -    //DArray da;
    -    //da.assign(ia);
    +    typedef boost::array<double,6> DArray;
    +    typedef boost::array<int,6> IArray;
    +    IArray ia = { 1, 2, 3, 4, 5, 6 };
    +    DArray da;
    +    da = ia;
    +    da.assign(42);
    }

    diff --git a/print.hpp b/print.hpp new file mode 100644 index 0000000..4325f47 --- /dev/null +++ b/print.hpp @@ -0,0 +1,28 @@ +/* The following code example is taken from the book + * "The C++ Standard Library - A Tutorial and Reference" + * by Nicolai M. Josuttis, Addison-Wesley, 1999 + * + * (C) Copyright Nicolai M. Josuttis 1999. + * Permission to copy, use, modify, sell and distribute this software + * is granted provided this copyright notice appears in all copies. + * This software is provided "as is" without express or implied + * warranty, and with no claim as to its suitability for any purpose. + */ +#include + +/* PRINT_ELEMENTS() + * - prints optional C-string optcstr followed by + * - all elements of the collection coll + * - separated by spaces + */ +template +inline void PRINT_ELEMENTS (const T& coll, const char* optcstr="") +{ + typename T::const_iterator pos; + + std::cout << optcstr; + for (pos=coll.begin(); pos!=coll.end(); ++pos) { + std::cout << *pos << ' '; + } + std::cout << std::endl; +}