From a921a66a65d02beac345290896695f7c61c01678 Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Thu, 3 Aug 2000 15:26:16 +0000 Subject: [PATCH] 1.17.0 release candidate runup [SVN r7683] --- array.hpp.html | 315 +++++++++++++++++++------------------ array.htm | 420 ++++++++++++++++++++++++------------------------- 2 files changed, 367 insertions(+), 368 deletions(-) diff --git a/array.hpp.html b/array.hpp.html index 1e9f7ea..94a84f6 100644 --- a/array.hpp.html +++ b/array.hpp.html @@ -1,159 +1,162 @@ - - -array.hpp - + + + +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*/
+ -

- - -/* 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*/
- - - - + + + diff --git a/array.htm b/array.htm index 084b246..7fee4a5 100644 --- a/array.htm +++ b/array.htm @@ -1,314 +1,310 @@ + + - + - + + array.hpp, an STL Array Wrapper + -  + +  - - +
Class - array, an STL Container (as +
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: +

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_type type of the elements
iteratortype of the iterator + type 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 + type 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 + type for signed size values
difference_typetype for unsigned + type for unsigned difference values
Operations:
+

array<type,num>

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

+

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: +

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
    -       +

    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
    +      + +