A type is Assignable if it is possible to assign one object of the type + to another object of that type.
+ +| T | + +is type that is a model of Assignable | +
| t | + +is an object of type T | +
| u | + +is an object of type T or possibly const + T | +
| Name | + +Expression | + +Return type | + +Semantics | +
|---|---|---|---|
| Assignment | + +t = u | + +T& | + +t is equivalent to u | +
DefaultConstructible
+ and CopyConstructible
Revised + 05 December, 2006
+ +| Copyright © 2000 | + +Jeremy Siek, Univ.of + Notre Dame (jsiek@lsc.nd.edu) | +
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)
diff --git a/Collection.html b/Collection.html index 942d491..b92ddd6 100644 --- a/Collection.html +++ b/Collection.html @@ -1,19 +1,534 @@ + + -A Collection is a concept similar to the STL Container concept. A + Collection provides iterators for accessing a range of elements and + provides information about the number of elements in the Collection. + However, a Collection has fewer requirements than a Container. The + motivation for the Collection concept is that there are many useful + Container-like types that do not meet the full requirements of Container, + and many algorithms that can be written with this reduced set of + requirements. To summarize the reduction in requirements:
+ +| Value type | + +X::value_type | + +The type of the object stored in a Collection. If the + Collection is mutable then the value type must be Assignable. Otherwise + the value type must be CopyConstructible. | +
| Iterator type | + +X::iterator | + +The type of iterator used to iterate through a + Collection's elements. The iterator's value type is expected to be the + Collection's value type. A conversion from the iterator type to the + const iterator type must exist. The iterator type must be an InputIterator. | +
| Const iterator type | + +X::const_iterator | + +A type of iterator that may be used to examine, but + not to modify, a Collection's elements. | +
| Reference type | + +X::reference | + +A type that behaves like a reference to the + Collection's value type. [1] | +
| Const reference type | + +X::const_reference | + +A type that behaves like a const reference to the + Collection's value type. | +
| Pointer type | + +X::pointer | + +A type that behaves as a pointer to the Collection's + value type. | +
| Distance type | + +X::difference_type | + +A signed integral type used to represent the distance + between two of the Collection's iterators. This type must be the same + as the iterator's distance type. | +
| Size type | + +X::size_type | + +An unsigned integral type that can represent any + nonnegative value of the Collection's distance type. | +
| X | + +A type that is a model of Collection. | +
| a, b | + +Object of type X. | +
| T | + +The value type of X. | +
The following expressions must be valid.
+ +| Name | + +Expression | + +Return type | +
|---|---|---|
| Beginning of range | + +a.begin() | + +iterator if a is mutable, + const_iterator otherwise | +
| End of range | + +a.end() | + +iterator if a is mutable, + const_iterator otherwise | +
| Size | + +a.size() | + +size_type | +
| Empty Collection | + +a.empty() | + +Convertible to bool | +
| Swap | + +a.swap(b) | + +void | +
| Name | + +Expression | + +Semantics | + +Postcondition | +
|---|---|---|---|
| Beginning of range | + +a.begin() | + +Returns an iterator pointing to the first element in + the Collection. | + +a.begin() is either dereferenceable or + past-the-end. It is past-the-end if and only if a.size() == + 0. | +
| End of range | + +a.end() | + +Returns an iterator pointing one past the last element + in the Collection. | + +a.end() is past-the-end. | +
| Size | + +a.size() | + +Returns the size of the Collection, that is, its + number of elements. | + +a.size() >= 0 | +
| Empty Collection | + +a.empty() | + +Equivalent to a.size() == 0. (But possibly + faster.) | + ++ |
| Swap | + +a.swap(b) | + +Equivalent to swap(a,b) | + ++ |
begin() and end() are amortized constant time.
+ +size() is at most linear in the Collection's size. + empty() is amortized constant time.
+ +swap() is at most linear in the size of the two + collections.
+ +| Valid range | + +For any Collection a, [a.begin(), + a.end()) is a valid range. | +
| Range size | + +a.size() is equal to the distance from + a.begin() to a.end(). | +
| Completeness | + +An algorithm that iterates through the range + [a.begin(), a.end()) will pass through every element of + a. | +
There are quite a few concepts that refine the Collection concept, + similar to the concepts that refine the Container concept. Here is a brief + overview of the refining concepts.
+ +The elements are arranged in some order that does not change + spontaneously from one iteration to the next. As a result, a + ForwardCollection is EqualityComparable + and LessThanComparable. + In addition, the iterator type of a ForwardCollection is a + MultiPassInputIterator which is just an InputIterator with the added + requirements that the iterator can be used to make multiple passes through + a range, and that if it1 == it2 and it1 is + dereferenceable then ++it1 == ++it2. The ForwardCollection also + has a front() method.
+ +| Name | + +Expression | + +Return type | + +Semantics | +
|---|---|---|---|
| Front | + +a.front() | + +reference if a is mutable, + const_reference otherwise. |
+
+ Equivalent to *(a.begin()). | +
The container provides access to iterators that traverse in both + directions (forward and reverse). The iterator type must meet all of the + requirements of BidirectionalIterator + except that the reference type does not have to be a real C++ reference. + The ReversibleCollection adds the following requirements to those of + ForwardCollection.
+ +| Name | + +Expression | + +Return type | + +Semantics | +
|---|---|---|---|
| Beginning of range | + +a.rbegin() | + +reverse_iterator if a is mutable, + const_reverse_iterator otherwise. | + +Equivalent to + X::reverse_iterator(a.end()). | +
| End of range | + +a.rend() | + +reverse_iterator if a is mutable, + const_reverse_iterator otherwise. | + +Equivalent to + X::reverse_iterator(a.begin()). | +
| Back | + +a.back() | + +reference if a is mutable, + const_reference otherwise. |
+
+ Equivalent to *(--a.end()). | +
The elements are arranged in a strict linear order. No extra methods are + required.
+ +The iterators of a RandomAccessCollection satisfy all of the + requirements of RandomAccessIterator + except that the reference type does not have to be a real C++ reference. In + addition, a RandomAccessCollection provides an element access operator.
+ +| Name | + +Expression | + +Return type | + +Semantics | +
|---|---|---|---|
| Element Access | + +a[n] | + +reference if a is mutable, + const_reference otherwise. | + +Returns the nth element of the Collection. n + must be convertible to size_type. Precondition: 0 <= n + < a.size(). | +
[1] The reference type does not have to be a + real C++ reference. The requirements of the reference type depend on the + context within which the Collection is being used. Specifically it depends + on the requirements the context places on the value type of the Collection. + The reference type of the Collection must meet the same requirements as the + value type. In addition, the reference objects must be equivalent to the + value type objects in the collection (which is trivially true if they are + the same object). Also, in a mutable Collection, an assignment to the + reference object must result in an assignment to the object in the + Collection (again, which is trivially true if they are the same object, but + non-trivial if the reference type is a proxy class).
+ +Revised + 05 + December, 2006
+ +| Copyright © 2000 | + +Jeremy + Siek, Univ.of Notre Dame and C++ Library & Compiler Group/SGI + (jsiek@engr.sgi.com) | +
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)
diff --git a/CopyConstructible.html b/CopyConstructible.html index 942d491..6a7ce65 100644 --- a/CopyConstructible.html +++ b/CopyConstructible.html @@ -1,19 +1,185 @@ + + -A type is Copy Constructible if it is possible to copy objects of that + type.
+ +| T | + +is type that is a model of Copy Constructible | +
| t | + +is an object of type T | +
| u | + +is an object of type const T | +
| Name | + +Expression | + +Return type | + +Semantics | +
|---|---|---|---|
| Copy constructor | + +T(t) | + +T | + +t is equivalent to T(t) | +
| Copy constructor | + +
+ +T(u) ++ |
+
+ T | + +u is equivalent to T(u) | +
| Destructor | + +
+ +t.~T() ++ |
+
+ T | + ++ |
| Address Operator | + +
+ +&t ++ |
+
+ T* | + +denotes the address of t | +
| Address Operator | + +
+ +&u ++ |
+
+ T* | + +denotes the address of u | +
+ template <class T>
+ struct CopyConstructibleConcept
+ {
+ void constraints() {
+ T a(b); // require copy constructor
+ T* ptr = &a; // require address of operator
+ const_constraints(a);
+ ignore_unused_variable_warning(ptr);
+ }
+ void const_constraints(const T& a) {
+ T c(a); // require const copy constructor
+ const T* ptr = &a; // require const address of operator
+ ignore_unused_variable_warning(c);
+ ignore_unused_variable_warning(ptr);
+ }
+ T b;
+ };
+
+
+ Default
+ Constructible and Assignable
Revised + 05 + December, 2006
+ +| Copyright © 2000 | + +Jeremy Siek, Univ.of + Notre Dame (jsiek@lsc.nd.edu) | +
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)
diff --git a/LessThanComparable.html b/LessThanComparable.html index 942d491..15b938f 100644 --- a/LessThanComparable.html +++ b/LessThanComparable.html @@ -1,19 +1,210 @@ + + + + -A type is LessThanComparable if it is ordered: it must be possible to + compare two objects of that type using operator<, and + operator< must be a strict weak ordering relation.
+ +| X | + +A type that is a model of LessThanComparable | +
| x, y, z | + +Object of type X | +
Consider the relation !(x < y) && !(y < x). If + this relation is transitive (that is, if !(x < y) && !(y + < x) && !(y < z) && !(z < y) implies !(x + < z) && !(z < x)), then it satisfies the mathematical + definition of an equivalence relation. In this case, operator< + is a strict weak ordering.
+ +If operator< is a strict weak ordering, and if each + equivalence class has only a single element, then operator< is + a total ordering.
+ +| Name | + +Expression | + +Type requirements | + +Return type | +
|---|---|---|---|
| Less | + +x < y | + ++ + | Convertible to bool | +
| Name | + +Expression | + +Precondition | + +Semantics | + +Postcondition | +
|---|---|---|---|---|
| Less | + +x < y | + +x and y are in the domain of + < | + ++ |
| Irreflexivity | + +x < x must be false. | +
| Antisymmetry | + +x < y implies !(y < x) [2] | +
| Transitivity | + +x < y and y < z implies x + < z [3] | +
[1] Only operator< is fundamental; + the other inequality operators are essentially syntactic sugar.
+ +[2] Antisymmetry is a theorem, not an axiom: it + follows from irreflexivity and transitivity.
+ +[3] Because of irreflexivity and transitivity, + operator< always satisfies the definition of a partial + ordering. The definition of a strict weak ordering is stricter, + and the definition of a total ordering is stricter still.
+ +EqualityComparable,
+ StrictWeakOrdering
+
Revised + 05 + December, 2006
+ +| Copyright © 2000 | + +Jeremy Siek, Univ.of + Notre Dame (jsiek@lsc.nd.edu) | +
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)
diff --git a/MultiPassInputIterator.html b/MultiPassInputIterator.html index 942d491..e331ca3 100644 --- a/MultiPassInputIterator.html +++ b/MultiPassInputIterator.html @@ -1,19 +1,95 @@ + + -This concept is a refinement of Input Iterator, adding + the requirements that the iterator can be used to make multiple passes + through a range, and that if it1 == it2 and it1 is + dereferenceable then ++it1 == ++it2. The Multi-Pass Input Iterator + is very similar to the Forward Iterator. + The only difference is that a Forward Iterator + requires the reference type to be value_type&, + whereas MultiPassInputIterator is like Input Iterator in that + the reference type merely has to be convertible to + value_type.
+ +comments by Valentin Bonnard:
+ +I think that introducing Multi-Pass Input Iterator isn't the right + solution. Do you also want to define Multi-Pass Bidirectionnal Iterator and + Multi-Pass Random Access Iterator ? I don't, definitly. It only confuses + the issue. The problem lies into the existing hierarchy of iterators, which + mixes movabillity, modifiabillity and lvalue-ness, and these are clearly + independant.
+ +The terms Forward, Bidirectionnal and Random Access are about + movabillity and shouldn't be used to mean anything else. In a completly + orthogonal way, iterators can be immutable, mutable, or neither. Lvalueness + of iterators is also orthogonal with immutabillity. With these clean + concepts, your Multi-Pass Input Iterator is just called a Forward + Iterator.
+ +Other translations are:
+ std::Forward Iterator -> ForwardIterator & Lvalue Iterator
+ std::Bidirectionnal Iterator -> Bidirectionnal Iterator & Lvalue
+ Iterator
+ std::Random Access Iterator -> Random Access Iterator & Lvalue
+ Iterator
Note that in practice the only operation not allowed on my Forward + Iterator which is allowed on std::Forward Iterator is &*it. I + think that &* is rarely needed in generic code.
+ +reply by Jeremy Siek:
+ +The above analysis by Valentin is right on. Of course, there is the
+ problem with backward compatibility. The current STL implementations are
+ based on the old definition of Forward Iterator. The right course of action
+ is to get Forward Iterator, etc. changed in the C++ standard. Once that is
+ done we can drop Multi-Pass Input Iterator.
Revised + 05 + December, 2006
+ +| Copyright © 2000 | + +Jeremy Siek, Univ.of + Notre Dame (jsiek@lsc.nd.edu) | +
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)
diff --git a/OptionalPointee.html b/OptionalPointee.html index 942d491..c3c7e44 100644 --- a/OptionalPointee.html +++ b/OptionalPointee.html @@ -1,19 +1,159 @@ - - -
+
+| T | +is a type that is a model of OptionalPointee | +
| t | +is an object of type T or possibly const T | +
| Name | +Expression | +Return type | +Semantics | +|
|---|---|---|---|---|
| Value Access | +*t | +T& | +If the pointee is valid returns a reference to
+ the pointee. + If the pointee is invalid the result is undefined. |
+ + |
| Value Access | +t->xyz | +T* | +If the pointee is valid returns a builtin pointer to the pointee. + If the pointee is invalid the result is undefined (It might not even return NULL). + |
+ + |
| Validity Test | +bool(t) | +bool | +If the pointee is valid returns true. + If the pointee is invalid returns false. |
+ + |
| Invalidity Test | +!t | +bool | +If the pointee is valid returns false. + If the pointee is invalid returns true. |
+ + |
This concept does not define any particular semantic for relational operations, therefore,
+a type which models this concept might have either shallow or deep relational semantics.
+For instance, pointers, which are models of OptionalPointee, have shallow relational operators:
+comparisons of pointers do not involve comparisons of pointees.
+This makes sense for pointers because they have shallow copy semantics.
+But boost::optional<T>, on the other hand, which is also a model of OptionalPointee, has
+deep-copy and deep-relational semantics.
+If generic code is written for this concept, it is important not to use relational
+operators directly because the semantics might be different depending on the actual type.
+Still, the concept itsef can be used to define deep relational tests that can
+be used in generic code with any type which models OptionalPointee:
Equivalence relation:
+template<class OptionalPointee>
+inline
+bool equal_pointees ( OptionalPointee const& x, OptionalPointee const& y )
+{
+ return (!x) != (!y) ? false : ( !x ? true : (*x) == (*y) ) ;
+}
+template<class OptionalPointee>
+struct equal_pointees_t : std::binary_function<OptionalPointee,OptionalPointee,bool>
+{
+ bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const
+ { return equal_pointees(x,y) ; }
+} ;
+
+The preceding generic function and function object have the following semantics:
+If both x and y have valid pointees, it compares values via (*x == *y).
+If only one has a valid pointee, returns false.
+If both have invalid pointees, returns true.
Less-than relation:
+template<class OptionalPointee>
+inline
+bool less_pointees ( OptionalPointee const& x, OptionalPointee const& y )
+{
+ return !y ? false : ( !x ? true : (*x) < (*y) ) ;
+}
+template<class OptionalPointee>
+struct less_pointees_t : std::binary_function<OptionalPointee,OptionalPointee,bool>
+{
+ bool operator() ( OptionalPointee const& x, OptionalPointee const& y ) const
+ { return less_pointees(x,y) ; }
+} ;
+
+The preceding generic function and function object have the following semantics:
+If y has an invalid pointee, returns false.
+Else, if x has an invalid pointee, returns true.
+Else, ( x and y have valid pointees), compares values via (*x <
+*y).
+All these functions and function
+objects are is implemented in compare_pointees.hpp
Notice that OptionalPointee does not imply aliasing (and optional<> for instance does not alias); +so direct usage of relational operators with the implied aliasing of shallow semantics +-as with pointers- should not be used with generic code written for this concept.
+ +Based on the original concept developed by Augustus Saunders.
+
+
+
| Copyright © 2003 | +Fernando Cacciola + |
Distributed under the Boost Software License, Version 1.0. See +www.boost.org/LICENSE_1_0.txt
+ + +