|
|
Boost-Commit : |
From: asutton_at_[hidden]
Date: 2007-07-24 07:27:35
Author: asutton
Date: 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
New Revision: 7519
URL: http://svn.boost.org/trac/boost/changeset/7519
Log:
Adding more concept docs
Text files modified:
sandbox/boost_docs/trunk/libs/standard/doc/concepts/concepts.qbk | 34 +++++++++++++++
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/assignable.qbk | 32 +++++++++++---
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/copy_constructible.qbk | 69 ++++++++++++++++++++++---------
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/default_constructible.qbk | 52 ++++++++++++++++++-----
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/equality_comparable.qbk | 57 ++++++++++++++++++++++++++
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/less_than_comparable.qbk | 87 ++++++++++++++++++++++++++++++++++++++++
sandbox/boost_docs/trunk/libs/standard/doc/std.qbk | 12 ++--
7 files changed, 298 insertions(+), 45 deletions(-)
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/concepts.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/concepts.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/concepts.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -6,6 +6,38 @@
/]
[section Concepts]
+[heading Introduction]
+In C++, concepts are essentially an expression of /requirement/ on types. Such
+requirements may state, for example, that a type have a default or copy
+constructor, should support pre- and post-increment operators, or a have
+a `swap()` member function. A type type is said to be a /model/ of a concept
+if it meets that concept's requirements.
+
+For example, the concept [StdDefaultConstructible] requires that a type has a
+default constructor. Types that model this concept include (but are not limited
+to) `int`, `float`, `std::complex`, `std::pair`, `std::string`, etc. Note that
+the concept makes no mention of the /initial values/ of default constructible
+objects, only that the expression of default construction is valid (and compiles).
+
+Concepts are developed explicitly for a library. As such, the standard library
+has groups of concepts for containers and iterators, and general purpose concepts
+used by both of these groups. Within each group concepts are typically designed
+/hierarchically/, where more specific concepts /refine/ general concepts. The
+notion of /refinement/ is similar to /inheritance/ with the specific concept
+including all of the requirements of the general.
+
+[heading C++0x]
+The newest version of C++ introduces explicit language support for concepts
+and concept checking. Additionally, many concepts are explicitly realized
+in the standard library itself. These concepts further refine those originally
+defined for the Standard Template Library, and the type requirements in the
+C++ standard. For example, the current [StdCopyConstructible] concept also
+requires that a type have a destructor. In the future the concept is made
+explicit as `Destructible`.
+
+Where appropriate, these documents describe the differences between the current
+and future standards. These sections are informative (i.e., non-normative) and
+are only provided for perspective, not reference.
[section Utilities]
[include utilities/utilities.qbk]
@@ -26,7 +58,7 @@
[section Streams]
[note
Curiously, there is not concept documentation for streams - at least none that
-I've ever seen. It might be a nice excercise to provide concept documents for
+I've ever seen. It might be a nice exercise to provide concept documents for
stream types (e.g. InputStreamable and OutputStreamable).
]
[endsect]
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/assignable.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/assignable.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/assignable.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -7,21 +7,39 @@
[section Assignable]
A type `T` is said to be /assignable/ if the value of one instance, `u`, can be copied
-to the value of another, `t` through an assignment expression. Note that the type of
-`u` must be `T` or `const T`.
+to the value of another, `t` through an assignment expression. The type of `u` must
+be `T` or `const T`.
-This concept sets no requirements nor makes provision for assignment when the type
-of `u` is not `T` or `const T`. This simply states that instances of a type, that models
-this concept, may be assigned to one another.
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[T] [An [StdAssignable] type.]]
+ [[t] [An instance of type `T`.]]
+ [[u] [An instance of type 'const `T`.]]
+]
-[heading Requirements]
+[heading Requirements]
[table
[[Expression] [Return Type] [Post-condition]]
[
[`t = u`]
[`T&`]
- [`t` is equivalent to `u`]
+ [`t` is equivalent to `u`.]
]
]
+[heading C++0x]
+In the next version of the C++ standards, the [StdAssignable] concept has been refined
+into a set of two distinct concepts: `CopyAssignable` and `MoveAssignable`. The
+`CopyAssignable` concept is defined as:
+
+ auto concept CopyAssignable<typename T, typename U = T>
+ {
+ typename result_type;
+ result_type operator =(T&, const U&);
+ }
+
+The `result_type` associated type is used to indicate that the return type is not
+required (as above) to be `T&` and could be any type.
+
[endsect]
\ No newline at end of file
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/copy_constructible.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/copy_constructible.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/copy_constructible.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -13,30 +13,35 @@
[heading Notation]
[table
- [[Expression] [Description]]
- [[T] [A copy-constructible type.]]
- [[t] [An instance of type `T`.]]
- [[u] [An instance of type 'const T`.]]
+ [[Expression] [Description]]
+ [[T] [A [StdCopyConstructible] type.]]
+ [[t] [An instance of type `T`.]]
+ [[u] [An instance of type 'const `T`.]]
]
[heading Requirements]
[table
- [[Expression] [Return Type] [Requirements]]
- [
- [`T t(u)`]
- []
- [`t` is equivalent to `u`]
- ]
- [
- [`t.~T()`]
- []
- [`t` is destructed.]
- ]
- [
- [`&t`]
- [`T*`]
- [Denotes the address of `t`.]
- ]
+ [[Expression] [Return Type] [Requirements]]
+ [
+ [`T t(u)`]
+ []
+ [`t` is an instance of `T` and is equivalent to `u`.]
+ ]
+ [
+ [`T(u)`]
+ []
+ [An instance of `T` is constructed that is equivalent to `u`.]
+ ]
+ [
+ [`t.~T()`]
+ []
+ [`t` is destructed.]
+ ]
+ [
+ [`&t`]
+ [`T*`]
+ [Denotes the address of `t`.]
+ ]
]
Taking the address of an instance with `const` type yields a
@@ -44,4 +49,28 @@
of `U`. The return type of `&u` is `U*`, which by substitution is
the same as `const T*`.
+[heading C++0x]
+In the next version of the C++ language, the destructible and addressable
+requirements are removed from this concept and made explicit elsewhere. The
+`CopyConstructible` concept is refined from the concepts for `Destructible`
+and `MoveConstructible` as follows:
+
+ auto concept Destructible<typename T>
+ {
+ T::~T();
+ };
+
+ auto concept MoveConstructible<typename T>
+ : Destructible<T>
+ {
+ T::T(T&&);
+ };
+
+ auto concept CopyConstructible<typename T>
+ : MoveConstructible<T>
+ {
+ T::T(const T&);
+ };
+
+
[endsect]
\ No newline at end of file
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/default_constructible.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/default_constructible.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/default_constructible.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -14,19 +14,49 @@
Non-trivial default constructors may specify a default value or state for
an object, but such values are not required by this concept.
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[T] [A [StdDefaultConstructible] type.]]
+ [[t] [An instance of `T`.]]
+]
+
[heading Requirements]
[table
- [[Expression] [Return Type] [Requirements]]
- [
- [`T x`]
- []
- [`x` is an instance of `T`.]
- ]
- [
- [`T()`]
- [An instance of `T` is constructed.]
- []
- ]
+ [[Expression] [Return Type] [Requirements]]
+ [
+ [`T t`]
+ []
+ [`t` is an instance of `T`.]
+ ]
+ [
+ [`T()`]
+ []
+ [An instance of `T` is constructed.]
+ ]
]
+[heading C++0x]
+The `DefaultConstructible` concept is made explicit in the next version of C++. It
+is refined from the Destructible and `Constructible` concepts, which allows
+construction from any number of arguments. It is given as:
+
+ auto concept Destructible<typename T>
+ {
+ T::~T();
+ };
+
+ auto concept Constructible<typename T, typename... Args>
+ : Destructible<T>
+ {
+ T::T(Args...);
+ };
+
+ auto concept DefaultConstructible<typename T>
+ : Constructible<T>
+ {};
+
+This effectively requires the that T have a constructor that takes no arguments, hence
+a default constructor.
+
[endsect]
\ No newline at end of file
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/equality_comparable.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/equality_comparable.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/equality_comparable.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -6,5 +6,62 @@
/]
[section Equality Comparable]
+A type `T` is said to be /equality comparable/ if it defines an /equivalence relation/
+and can be compared using the equality comparison operator (`==`). An equivalence
+relation is a binary relation between any two instances of `T` that denotes them as
+being "equivalent". Note that the meaning of equivalent depends on the type.
+Equivalence relations are required to be /reflexive/, /symmetric/, and /transitive/.
+Equality comparability also introduces the notion of /identity/ for instances of a
+type. This states that an instance of a [StdEqualityComparable] is equivalent
+to itself.
+
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[T] [An [StdEqualityComparable] type.]]
+ [[`t`, `u`, `v`] [Instances of `T`.]]
+]
+
+[heading Requirements]
+[table
+ [[Expression] [Return Type] [Requirements]]
+ [
+ [`t == u`]
+ [Convertible to `bool`.]
+ [If `t` and `u` are equivalent, the return value is convertible to `true`.]
+ ]
+ [
+ [`t != u`]
+ [Convertible to `bool`.]
+ [If `t` and `v` are not equivalent, the return value is convertible to `false`]
+ ]
+]
+
+Note that inequality operator (`!=`) can be trivially implemented if the equality operator
+(`==`) is defined for a type as:
+
+ bool operator !=(const T& t, const T& v) { return !(t == v); }
+
+[heading Invariants]
+The following properties must hold for all models of [StdEqualityComparable].
+
+[table
+ [[Property] [Semantics]]
+ [[Reflexivity] [`t == t` is true.]]
+ [[Symmetry] [`t == u` implies `u == t`.]]
+ [[Transitivity] [`t == u` and `u == v` implies `t == v`.]]
+ [[Identity] [`&t == &u` implies `t == u`.]]
+]
+
+[heading C++0x]
+The `EqualityComparable` concept in C++0x does not impose the /identity/ property on
+the equality comparable relation. This concept also provides a default implementation
+of the inequality (`!=`) operator. It is given as:
+
+ auto concept EqualityComparable<typename T, typename U = T>
+ {
+ bool operator (const T&, const U&);
+ bool operator !=(const T& t, const U& u) { return !(t == u); }
+ }
[endsect]
\ No newline at end of file
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/less_than_comparable.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/less_than_comparable.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/less_than_comparable.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -6,5 +6,92 @@
/]
[section Less Than Comparable]
+A type `T` is said to be /less than comparable/ if two instances of `T` can be
+compared with the less than operator (`<`) and that operator defines a
+/strict weak ordering/ of values `T`. A strict weak ordering is a binary relation
+between any two instances, `t` and `u` of `T` that denotes their ordering. The
+meaning of `t < u` is that `t` occurs before `u`. Strict weak orderings are
+required to be be /irreflixive/, /antisymmetric/, and /transitive/.
+
+[heading Notation]
+[table
+ [[Expression] [Description]]
+ [[T] [An [StdLessThanComparable] type.]]
+ [[`t`, `u`, `v`] [Instances of `T`.]]
+]
+
+[heading Requirements]
+[table
+ [[Expression] [Return Type] [Requirements]]
+ [
+ [`t < u`]
+ [Convertible to `bool`.]
+ [If `t` is ordered before `u`, the return value is convertible to `true`.]
+ ]
+ [
+ [`t > u`]
+ [Convertible to `bool`.]
+ [If `t` is ordered after `u`, the return value is convertible to `true`.]
+ ]
+ [
+ [`t <= u`]
+ [Convertible to `bool`.]
+ [If `t` is equivalent to ordered before `u`, the return value is convertible to `true`.]
+ ]
+ [
+ [`t >= u`]
+ [Convertible to `bool`.]
+ [If `t` is equivalent to ordered after `u`, the return value is convertible to `true`.]
+ ]
+]
+
+The `>`, `<=` and `>=` operator can all be trivially implemented if the `<` operator is defined
+for type `T` as:
+
+ bool operator >(const T& t, const T& u) { return u < v; }
+ bool operator <=(const T& t, const T& v) { return !(u < v); }
+ bool operator >=(const T& t, const T& v) { return !(v < u); }
+
+[heading Invariants]
+The following properties must hold for all models of [StdLessThanComparable].
+
+[table
+ [[Property] [Semantics]]
+ [[Irreflexivity] [`t < t` is false.]]
+ [[Antisymmetry] [`t < u` implies `!(u < t)`.]]
+ [[Transitivity] [`t < u` and `u < v` implies `t < v`.]]
+]
+
+[heading Notes]
+From a mathematical perspective, values of `T` can be incomparable. For example,
+to state that `t` and `u` are incomparable means that the `t < u` has no meaning.
+This is generally infeasible from a programming perspective since the less than
+operator (`<`) typically only has two values: `true` and `false`. If `t` and
+`u` were incomparable, then the return type could be neither `true` nor `false`
+since that would effectively compare the elements. In this sense, most strict
+weak orderings of `T` are also total orderings of `T`.
+
+The original Standard Template Library requires that the less than operator (`<`)
+implement a /partial ordering/ over instances `T`. A partial order is required to
+be /reflexive/, /antisymmetric/, and /transitive/. Since incomparability is rarely
+(if ever) a factor in most programs, the transitivity of `<` implies that this is
+a strict ordering.
+
+As a result, providing the less than operator (`<`) for a type `T` will almost always
+guarantee a total ordering and a strict weak ordering over `T`.
+
+[heading C++0x]
+In the next version of C++ the `LessThanComparable` concept requires that the less
+than operator (`<`) implement a strict weak ordering over instances of `T` rather
+than just a partial ordering, and it provides default implementations of the other
+relative comparison operators (`>`, `<=`, and `>=`). It is given as:
+
+ auto concept LessThanComparable<typename T, typename U = T>
+ {
+ bool operator <(const T&, const U&);
+ bool operator >(const T& t, const U& u) { return u < v; }
+ bool operator <=(const T& t, const U& u) { return !(u < v); }
+ bool operator >=(const T& t, const U& u) { return !(v < u); }
+ };
[endsect]
\ No newline at end of file
Modified: sandbox/boost_docs/trunk/libs/standard/doc/std.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/std.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/std.qbk 2007-07-24 07:27:34 EDT (Tue, 24 Jul 2007)
@@ -10,7 +10,7 @@
[id standard]
[dirname standard]
[purpose
- The Standard Template Library Concept and Reference documentation
+ The Standard Template Library Concept and Reference Documentation
]
[license
Distributed under the Boost Software License, Version 1.0.
@@ -20,11 +20,11 @@
]
[/ Quick Reference Templates /]
-[template StdDefaultConstructible[] [link standard.concepts.utilities.default_constructible ['DefaultConstructible]]]
-[template StdCopyConstructible[] [link standard.concepts.utilities.copy_constructible ['CopyConstructible]]]
-[template StdAssignable[] [link standard.concepts.utilities.assignable ['Assignable]]]
-[template EqualityComparable[] [link standard.concepts.utilities.equality_comparable ['EqualityComparable]]]
-[template LessThanComparable[] [link standard.concepts.utilities.less_than_comparable ['LessThanComparable]]]
+[template StdDefaultConstructible[] [link standard.concepts.utilities.default_constructible [^DefaultConstructible]]]
+[template StdCopyConstructible[] [link standard.concepts.utilities.copy_constructible [^CopyConstructible]]]
+[template StdAssignable[] [link standard.concepts.utilities.assignable [^Assignable]]]
+[template StdEqualityComparable[] [link standard.concepts.utilities.equality_comparable [^EqualityComparable]]]
+[template StdLessThanComparable[] [link standard.concepts.utilities.less_than_comparable [^LessThanComparable]]]
[/ Contents ]
[include concepts/concepts.qbk]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk