diff --git a/doc/array.xml b/doc/array.xml new file mode 100644 index 0000000..af230d8 --- /dev/null +++ b/doc/array.xml @@ -0,0 +1,542 @@ + + + + Boost.Array + + + + Nicolai + Josuttis + + + + 2001 + Nicolai M. Josuttis + + + + 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. + + + STL compliant container wrapper for arrays of constant size + + + +
+ Introduction + + + + + 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 + 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 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. + + 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 undetermined initial value (see ). + 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. + + +
+ + +
+ + + + + STL compliant container wrapper for arrays of constant size + + T + + + T* + + + const T* + + + std::reverse_iterator<iterator> + + + std::reverse_iterator<const_iterator> + + + T& + + + const T& + + + std::size_t + + + std::ptrdiff_t + + + + + + + + const array<U, N>& + + std::copy(rhs.begin(),rhs.end(), begin()) + + + + + + iterator + + + const_iterator + + + iterator for the first element + will not throw + + + + + iterator + + + const_iterator + + + iterator for position after the last element + will not throw + + + + + + + reverse_iterator + + + const_reverse_iterator + + + reverse iterator for the first element of reverse iteration + + + + + reverse_iterator + + + const_reverse_iterator + + + reverse iterator for position after the last element in reverse iteration + + + + + + size_type + N + + + bool + N==0 + will not throw + + + size_type + N + will not throw + + + + + + + reference + + size_type + + + + + const_reference + + size_type + + + + i < N + element with index i + will not throw. + + + + + reference + + size_type + + + + + const_reference + + size_type + + + + element with index i + std::range_error if i >= N + + + + + reference + + + const_reference + + N > 0 + the first element + will not throw + + + + + reference + + + const_reference + + N > 0 + the last element + will not throw + + + + const T* + elems + will not throw + + + + + + void + + array<T, N>& + + std::swap_ranges(begin(), end(), other.begin()) + linear in N + + + void + + const T& + + std::fill_n(begin(), N, value) + + + + + T + + + + + + + void + + + array<T, N>& + + + array<T, N>& + + + x.swap(y) + will not throw. + + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + std::equal(x.begin(), x.end(), y.begin()) + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + !(x == y) + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + std::lexicographical_compare(x.begin(), x.end(), y.begin(), y.end()) + + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + y < x + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + !(y < x) + + + + + + bool + + + const array<T, N>& + + + const array<T, N>& + + + !(x < y) + + + + +
+ + +
+ Design Rationale + + There was an important design tradeoff regarding the + constructors: We could implement array as an "aggregate" (see + Section 8.5.1, [dcl.init.aggr], of the C++ Standard). This would + mean: + + An array can be initialized with a + brace-enclosing, comma-separated list of initializers for the + elements of the container, written in increasing subscript + order: + + boost::array<int,4> a = { { 1, 2, 3 } }; + + Note that if there are fewer elements in the + initializer list, then each remaining element gets + default-initialized (thus, it has a defined value). However, + passing no initializer list means that the elements have an + indetermined initial value. + + It has no user-declared constructors. + It has no private or protected non-static data members. + It has no base classes. + It has no virtual functions. + + + + The current implementation uses this approach. However, being + able to have indeterminate initial values is a big drawback. So, + please give me some feedback, how useful you consider this feature + to be. +
+ +
+ Open Issues + + + + + Do we want initializer list support or would the + following be OK?: + + int data[] = { 1, 2, 3, 4 } +boost::array<int,5> x(data); // or boost::array<int,data> x; + + + Could "{ ... }" be used portably instead of "{ + { ... } }" to initialize values? 8.5.1 (11) of the Standard seems + to allow it; however, gcc 2.95.2 prints a warning + message. + + Any way to have determinate initial values and + initializer list support? + + Static_casts for reverse iterator stuff? + + + 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. +
+ +
+ For more information... + 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 +
+ +
+ Acknowledgements + + Doug Gregor ported the documentation to the BoostBook format. +
+ + + +