diff --git a/doc/array.adoc b/doc/array.adoc index d6292b5..66a90ba 100644 --- a/doc/array.adoc +++ b/doc/array.adoc @@ -6,7 +6,7 @@ Distributed under the Boost Software License, Version 1.0. https://www.boost.org/LICENSE_1_0.txt //// -# Array +# Boost.Array Nicolai M. Josuttis :toc: left :toclevels: 4 @@ -18,7 +18,6 @@ Nicolai M. Josuttis :leveloffset: +1 - include::array/introduction.adoc[] include::array/reference.adoc[] include::array/design_rationale.adoc[] diff --git a/doc/array/copyright.adoc b/doc/array/copyright.adoc index f04e3a8..ca1724c 100644 --- a/doc/array/copyright.adoc +++ b/doc/array/copyright.adoc @@ -12,4 +12,4 @@ Copyright (C) 2001-2004 Nicolai M. Josuttis Copyright (C) 2012 Marshall Clow -Distributed under 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) +Distributed under the https://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0]. diff --git a/doc/array/design_rationale.adoc b/doc/array/design_rationale.adoc index bedc0a0..7a32d28 100644 --- a/doc/array/design_rationale.adoc +++ b/doc/array/design_rationale.adoc @@ -37,7 +37,3 @@ Note that for standard conforming compilers it is possible to use fewer braces ( ```cpp boost::array a = { 1, 2, 3 }; ``` - -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 to me, please send me a copy of each mail regarding this class.** - -The code is provided "as is" without expressed or implied warranty. diff --git a/doc/array/introduction.adoc b/doc/array/introduction.adoc index 9330a8f..a334f0a 100644 --- a/doc/array/introduction.adoc +++ b/doc/array/introduction.adoc @@ -11,11 +11,18 @@ https://www.boost.org/LICENSE_1_0.txt :idprefix: introduction_ :cpp: C++ -The {cpp} Standard Template Library STL as part of the {cpp} 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). +The {cpp} Standard Template Library STL as part of the {cpp} 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 `std::vector`. However, `std::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. +As replacement for ordinary arrays, the STL provides class `std::vector`. +However, `std::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 {cpp} Programming Language_, 3rd edition, Bjarne Stroustrup introduces a similar class, called c_array, which I (http://www.josuttis.com/[Nicolai Josuttis]) present slightly modified in my book _The {cpp} Standard Library - A Tutorial and Reference_, called `carray`. This is the essence of these approaches spiced with many feedback from https://www.boost.org/[boost]. +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 {cpp} Programming Language_, 3rd edition, Bjarne Stroustrup introduces a similar class, called c_array, which I (http://www.josuttis.com/[Nicolai Josuttis]) present slightly modified in my book _The {cpp} Standard Library - A Tutorial and Reference_, called `carray`. +This is the essence of these approaches spiced with many feedback from https://www.boost.org/[Boost]. After considering different names, we decided to name this class simply `array`. diff --git a/doc/array/reference.adoc b/doc/array/reference.adoc index bde9266..5e80a0e 100644 --- a/doc/array/reference.adoc +++ b/doc/array/reference.adoc @@ -15,24 +15,30 @@ https://www.boost.org/LICENSE_1_0.txt ```cpp namespace boost { + template class array; - template void swap(array&, array&); + template - bool operator==(const array&, const array&); + constexpr void swap(array&, array&); + template - bool operator!=(const array&, const array&); + constexpr bool operator==(const array&, const array&); template - bool operator<(const array&, const array&); + constexpr bool operator!=(const array&, const array&); + template - bool operator>(const array&, const array&); + constexpr bool operator<(const array&, const array&); template - bool operator<=(const array&, const array&); + constexpr bool operator>(const array&, const array&); template - bool operator>=(const array&, const array&); - template - T boost::get(array&); - template - T boost::get(const array&); + constexpr bool operator<=(const array&, const array&); + template + constexpr bool operator>=(const array&, const array&); + + template + constexpr T& get(array&) noexcept; + template + constexpr const T& get(const array&) noexcept; } ``` @@ -46,7 +52,9 @@ namespace boost { template class array { public: + // types + typedef T value_type; typedef T* iterator; typedef const T* const_iterator; @@ -58,361 +66,340 @@ public: typedef std::ptrdiff_t difference_type; // static constants + static const size_type static_size = N; - // construct/copy/destruct + // construct/copy/destroy + template array& operator=(const array&); // iterator support - iterator begin(); - const_iterator begin() const; - iterator end(); - const_iterator end() const; - const_iterator cbegin(); - const_iterator cend(); + + constexpr iterator begin() noexcept; + constexpr const_iterator begin() const noexcept; + constexpr const_iterator cbegin() const noexcept; + + constexpr iterator end() noexcept; + constexpr const_iterator end() const noexcept; + constexpr const_iterator cend() const noexcept; // reverse iterator support - reverse_iterator rbegin(); - const_reverse_iterator rbegin() const; - reverse_iterator rend(); - const_reverse_iterator rend() const; - const_reverse_iterator crbegin(); - const_reverse_iterator crend(); + + reverse_iterator rbegin() noexcept; + const_reverse_iterator rbegin() const noexcept; + const_reverse_iterator crbegin() const noexcept; + + reverse_iterator rend() noexcept; + const_reverse_iterator rend() const noexcept; + const_reverse_iterator crend() const noexcept; // capacity - size_type size(); - bool empty(); - size_type max_size(); + + static constexpr size_type size() noexcept; + static constexpr bool empty() noexcept; + static constexpr size_type max_size() noexcept; // element access - reference operator[](size_type); - const_reference operator[](size_type) const; - reference at(size_type); - const_reference at(size_type) const; - reference front(); - const_reference front() const; - reference back(); - const_reference back() const; - const T* data() const; - T* c_array(); + + constexpr reference operator[](size_type); + constexpr const_reference operator[](size_type) const; + + constexpr reference at(size_type); + constexpr const_reference at(size_type) const; + + constexpr reference front(); + constexpr const_reference front() const; + + constexpr reference back(); + constexpr const_reference back() const; + + constexpr T* data() noexcept; + constexpr const T* data() const noexcept; + + T* c_array() noexcept; // deprecated // modifiers - void swap(array&); - void assign(const T&); + + constexpr void swap(array&); + + constexpr void fill(const T&); + void assign(const T&); // deprecated // public data members T elems[N]; }; - -// specialized algorithms -template void swap(array&, array&); - -// comparisons -template - bool operator==(const array&, const array&); -template - bool operator!=(const array&, const array&); -template - bool operator<(const array&, const array&); -template - bool operator>(const array&, const array&); -template - bool operator<=(const array&, const array&); -template - bool operator>=(const array&, const array&); - -// specializations -template - T boost::get(array&); -template - T boost::get(const array&); ``` -### Description - -#### array public construct/copy/destruct +### Construct/Copy/Destroy ``` template array& operator=(const array& other); ``` [horizontal] -Effects: :: `std::copy(rhs.begin(), rhs.end(), begin())` +Effects: :: `std::copy(rhs.begin(), rhs.end(), begin())`. --- -#### array iterator support +### Iterator Support ``` -iterator begin(); -const_iterator begin() const; +constexpr iterator begin() noexcept; +constexpr const_iterator begin() const noexcept; +constexpr const_iterator cbegin() const noexcept; ``` [horizontal] -Returns: :: iterator for the first element -Throws: :: will not throw +Returns: :: `data()`. --- ``` -iterator end(); -const_iterator end() const; +constexpr iterator end() noexcept; +constexpr const_iterator end() const noexcept; +constexpr const_iterator cend() const noexcept; ``` [horizontal] -Returns: :: iterator for position after the last element -Throws: :: will not throw +Returns: :: `data() + size()`. --- +### Reverse Iterator Support + ``` -const_iterator cbegin(); +reverse_iterator rbegin() noexcept; ``` [horizontal] -Returns: :: constant iterator for the first element -Throws: :: will not throw +Returns: :: `reverse_iterator(end())`. --- ``` -const_iterator cend(); +const_reverse_iterator rbegin() const noexcept; +const_reverse_iterator crbegin() const noexcept; ``` [horizontal] -Returns: :: constant iterator for position after the last element -Throws: :: will not throw +Returns: :: `const_reverse_iterator(end())`. --- -#### array reverse iterator support - ``` -reverse_iterator rbegin(); -const_reverse_iterator rbegin() const; +reverse_iterator rend() noexcept; ``` [horizontal] -Returns: :: reverse iterator for the first element of reverse iteration +Returns: :: `reverse_iterator(begin())`. --- ``` -reverse_iterator rend(); -const_reverse_iterator rend() const; +const_reverse_iterator rend() const noexcept; +const_reverse_iterator crend() const noexcept; ``` [horizontal] -Returns: :: reverse iterator for position after the last element in reverse iteration +Returns: :: `const_reverse_iterator(begin())`. --- +### Capacity + ``` -const_reverse_iterator crbegin(); +static constexpr size_type size() noexcept; ``` [horizontal] -Returns: :: constant reverse iterator for the first element of reverse iteration -Throws: :: will not throw +Returns: :: `N`. --- ``` -const_reverse_iterator crend(); +static constexpr bool empty() noexcept; ``` [horizontal] -Returns: :: constant reverse iterator for position after the last element in reverse iteration -Throws: :: will not throw +Returns: :: `N == 0`. --- -#### array capacity - ``` -size_type size(); +static constexpr size_type max_size() noexcept; ``` [horizontal] -Returns: :: `N` +Returns: :: `N`. --- +### Element Access + ``` -bool empty(); +constexpr reference operator[](size_type i); +constexpr const_reference operator[](size_type i) const; ``` [horizontal] -Returns: :: `N==0` -Throws: :: will not throw +Requires: :: `i < N`. +Returns: :: `elems[i]`. +Throws: :: nothing. --- ``` -size_type max_size(); +constexpr reference at(size_type i); +constexpr const_reference at(size_type i) const; ``` [horizontal] -Returns: :: `N` -Throws: :: will not throw +Returns: :: `elems[i]`. +Throws: :: `std::out_of_range` if `i >= N`. --- -#### array element access - ``` -reference operator[](size_type i); -const_reference operator[](size_type i) const; +constexpr reference front(); +constexpr const_reference front() const; ``` [horizontal] -Requires: :: `i < N` -Returns: :: element with index `i` -Throws: :: will not throw. +Requires: :: `N > 0`. +Returns: :: `elems[0]`. +Throws: :: nothing. --- ``` -reference at(size_type i); -const_reference at(size_type i) const; +constexpr reference back(); +constexpr const_reference back() const; ``` [horizontal] -Returns: :: element with index `i` -Throws: :: `std::range_error` if `i >= N` +Requires: :: `N > 0`. +Returns: :: `elems[N-1]`. +Throws: :: nothing. --- ``` -reference front(); -const_reference front() const; +constexpr T* data() noexcept; +constexpr const T* data() const noexcept; ``` [horizontal] -Requires: :: `N > 0` -Returns: :: the first element -Throws: :: will not throw +Returns: :: `elems`. --- ``` -reference back(); -const_reference back() const; +T* c_array() noexcept; // deprecated ``` [horizontal] -Requires: :: `N > 0` -Returns: :: the last element -Throws: :: will not throw +Returns: :: `data()`. +Remarks: :: This function is deprecated. Use `data()` instead. --- +### Modifiers + ``` -const T* data() const; +constexpr void swap(array& other); ``` [horizontal] -Returns: :: `elems` -Throws: :: will not throw +Effects: :: for each `i` in `[0..N)`, calls `swap(elems[i], other.elems[i])`. +Complexity: :: linear in `N`. --- ``` -T* c_array(); +void fill(const T& value); ``` [horizontal] -Returns: :: `elems` -Throws: :: will not throw +Effects: :: for each `i` in `[0..N)`, performs `elems[i] = value;`. --- -#### array modifiers - ``` -void swap(array& other); +void assign(const T& value); // deprecated ``` [horizontal] -Effects: :: `std::swap_ranges(begin(), end(), other.begin())` -Complexity: :: linear in `N` +Effects: :: `fill(value)`. +Remarks: :: An obsolete and deprecated spelling of `fill`. Use `fill` instead. --- -``` -void assign(const T& value); -``` -[horizontal] -Effects: :: `std::fill_n(begin(), N, value)` - ---- - -#### array specialized algorithms - -``` -template void swap(array& x, array& y); -``` -[horizontal] -Effects: :: `x.swap(y)` -Throws: :: will not throw. - ---- - -#### array comparisons +### Specialized Algorithms ``` template - bool operator==(const array& x, const array& y); + constexpr void swap(array& x, array& y); ``` [horizontal] -Returns: :: `std::equal(x.begin(), x.end(), y.begin())` +Effects: :: `x.swap(y)`. + +--- + +### Comparisons + +``` +template + constexpr bool operator==(const array& x, const array& y); +``` +[horizontal] +Returns: :: `std::equal(x.begin(), x.end(), y.begin())`. --- ``` template - bool operator!=(const array& x, const array& y); + constexpr bool operator!=(const array& x, const array& y); ``` [horizontal] -Returns: :: `!(x == y)` +Returns: :: `!(x == y)`. --- ``` template - bool operator<(const array& x, const array& y); + constexpr bool operator<(const array& x, const array& y); ``` [horizontal] -Returns: :: `std::lexicographical_compare(x.begin(), x.end(), y.begin(), y.end())` +Returns: :: `std::lexicographical_compare(x.begin(), x.end(), y.begin(), y.end())`. --- ``` template - bool operator>(const array& x, const array& y); + constexpr bool operator>(const array& x, const array& y); ``` [horizontal] -Returns: :: `y < x` +Returns: :: `y < x`. --- ``` template - bool operator<=(const array& x, const array& y); + constexpr bool operator<=(const array& x, const array& y); ``` [horizontal] -Returns: :: `!(y < x)` +Returns: :: `!(y < x)`. --- ``` template - bool operator>=(const array& x, const array& y); + constexpr bool operator>=(const array& x, const array& y); ``` [horizontal] -Returns: :: `!(x < y)` +Returns: :: `!(x < y)`. --- -#### array specializations +### Specializations ``` -template - T boost::get(array& arr); +template + constexpr T& get(array& arr) noexcept; ``` [horizontal] -Returns: :: element of array with index `Idx` -Effects: :: Will `static_assert` if `Idx >= N` +Mandates: :: `Idx < N`. +Returns: :: `arr[Idx]`. --- ``` -template - T boost::get(const array& arr); +template + constexpr const T& get(const array& arr) noexcept; ``` [horizontal] -Returns: :: const element of array with index `Idx` -Effects: :: Will `static_assert` if `Idx >= N` +Mandates: :: `Idx < N`. +Returns: :: `arr[Idx]`. ---