From 669e6938ccebb443da5aecf0061ca01776d8428e Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Mon, 8 Dec 2003 01:15:31 +0000 Subject: [PATCH] Added Caramel/BoostBook concept documentation (finally) [SVN r21176] --- doc/Jamfile.v2 | 4 + doc/reference/Assignable.xml | 59 +++ doc/reference/BidirectionalIterator.xml | 136 ++++++ doc/reference/CopyConstructible.xml | 47 ++ doc/reference/DefaultConstructible.xml | 40 ++ doc/reference/EqualityComparable.xml | 63 +++ doc/reference/ForwardIterator.xml | 174 ++++++++ doc/reference/InputIterator.xml | 168 ++++++++ doc/reference/LessThanComparable.xml | 81 ++++ doc/reference/OutputIterator.xml | 203 +++++++++ doc/reference/RandomAccessIterator.xml | 313 ++++++++++++++ doc/reference/SignedInteger.xml | 549 ++++++++++++++++++++++++ doc/reference/concepts.xml | 78 ++++ 13 files changed, 1915 insertions(+) create mode 100644 doc/Jamfile.v2 create mode 100644 doc/reference/Assignable.xml create mode 100644 doc/reference/BidirectionalIterator.xml create mode 100644 doc/reference/CopyConstructible.xml create mode 100644 doc/reference/DefaultConstructible.xml create mode 100644 doc/reference/EqualityComparable.xml create mode 100644 doc/reference/ForwardIterator.xml create mode 100644 doc/reference/InputIterator.xml create mode 100644 doc/reference/LessThanComparable.xml create mode 100644 doc/reference/OutputIterator.xml create mode 100644 doc/reference/RandomAccessIterator.xml create mode 100644 doc/reference/SignedInteger.xml create mode 100644 doc/reference/concepts.xml diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 0000000..7b00065 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,4 @@ +project boost/concepts ; +import boostbook : boostbook ; + +boostbook concepts : reference/concepts.xml ; diff --git a/doc/reference/Assignable.xml b/doc/reference/Assignable.xml new file mode 100644 index 0000000..56f4052 --- /dev/null +++ b/doc/reference/Assignable.xml @@ -0,0 +1,59 @@ + + + + + The type must be a model of . + + + Assignable types must have copy constructors, + operator= for assignment, and the swap() + function defined. + + + + + + + + + + + + + + + + + + + + + Require operator= + + + + + + + + + Require swap() function + + + + + + diff --git a/doc/reference/BidirectionalIterator.xml b/doc/reference/BidirectionalIterator.xml new file mode 100644 index 0000000..9b6b9f6 --- /dev/null +++ b/doc/reference/BidirectionalIterator.xml @@ -0,0 +1,136 @@ + + + + + + + The iterator type must be a model of . + + + A bidirectional iterator is an iterator that can read through a sequence + of values. It can move in either direction through the sequence, and can + be either mutable (data pointed to by it can be changed) or not mutable. + + An iterator represents a position in a sequence. Therefore, the + iterator can point into the sequence (returning a value when dereferenced + and being incrementable), or be off-the-end (and not dereferenceable or + incrementable). + + + + + + + + + The value type of the iterator + + + + + + + + + + + + + + + + + The category of the iterator + + + + + + + + + + + + + + + + + + + + + + + + + + + + i is incrementable (not + off-the-end) and some dereferenceable iterator j exists + such that i == ++j + + + + + + + + + + Same as for predecrement + Equivalent to {Iter j = i; --i; return j;} + i is dereferenceable or + off-the-end + + + + All iterator operations must take amortized constant time. + + + + &i = &(--i) + + + + i == j implies --i == --j + + + + ++i; --i; and --i; ++i; must end up with the + value of i unmodified, if i both of the + operations in the pair are valid. + + + + + + + + + + + + + + + + + + + diff --git a/doc/reference/CopyConstructible.xml b/doc/reference/CopyConstructible.xml new file mode 100644 index 0000000..9d278f3 --- /dev/null +++ b/doc/reference/CopyConstructible.xml @@ -0,0 +1,47 @@ + + + + + The type must be a model of . + + + Copy constructible types must be able to be constructed from another + member of the type. + + + + + + + + + + + + + + + + + + + Require copy constructor. + + + + + + diff --git a/doc/reference/DefaultConstructible.xml b/doc/reference/DefaultConstructible.xml new file mode 100644 index 0000000..1886ab0 --- /dev/null +++ b/doc/reference/DefaultConstructible.xml @@ -0,0 +1,40 @@ + + + + + The type must be a model of . + + DefaultConstructible objects only need to have a default + constructor. + + + + + + + Construct an instance of the type with default parameters. + + + + + + + + + + + + diff --git a/doc/reference/EqualityComparable.xml b/doc/reference/EqualityComparable.xml new file mode 100644 index 0000000..5d5479a --- /dev/null +++ b/doc/reference/EqualityComparable.xml @@ -0,0 +1,63 @@ + + + + + The type must be a model of + . + + Equality Comparable types must have == and + != operators. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/reference/ForwardIterator.xml b/doc/reference/ForwardIterator.xml new file mode 100644 index 0000000..dffe0ae --- /dev/null +++ b/doc/reference/ForwardIterator.xml @@ -0,0 +1,174 @@ + + + + + + + The iterator type must be a model of . + + + A forward iterator is an iterator that can read through a sequence of + values. It is multi-pass (old values of the iterator can be + re-used), and can be either mutable (data pointed to by it can be + changed) or not mutable. + + An iterator represents a position in a sequence. Therefore, the + iterator can point into the sequence (returning a value when dereferenced + and being incrementable), or be off-the-end (and not dereferenceable or + incrementable). + + + + + + + + + The value type of the iterator + + + + + + + + + + + + + + + + + + + + + The category of the iterator + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + + + i is incrementable (not + off-the-end) + Equivalent to {Iter j = i; ++i; return j;} + i is dereferenceable or + off-the-end + + + + All iterator operations must take amortized constant time. + + + + &i = &(++i) + + + + i == j implies ++i == ++j + + + + + + + + + + + + + + + + + + + diff --git a/doc/reference/InputIterator.xml b/doc/reference/InputIterator.xml new file mode 100644 index 0000000..794c62c --- /dev/null +++ b/doc/reference/InputIterator.xml @@ -0,0 +1,168 @@ + + + + + + + The iterator type must be a model of . + + + An input iterator is an iterator that can read through a sequence of + values. It is single-pass (old values of the iterator cannot be + re-used), and read-only. + + An input iterator represents a position in a sequence. Therefore, the + iterator can point into the sequence (returning a value when dereferenced + and being incrementable), or be off-the-end (and not dereferenceable or + incrementable). + + + + + + + + + + + + + + + + + + + The value type of the iterator (not necessarily what + *i returns) + + + + + + + + + The difference type of the iterator + + + + + + + + + The category of the iterator + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + i is incrementable (not + off-the-end) + Equivalent to (void)(++i) + i is dereferenceable or + off-the-end + + + + + + + + + + + + i is incrementable (not + off-the-end) + Equivalent to {value_type t = *i; ++i; return t;} + i is dereferenceable or + off-the-end + + + + All iterator operations must take amortized constant time. + + + + + + + + + + diff --git a/doc/reference/LessThanComparable.xml b/doc/reference/LessThanComparable.xml new file mode 100644 index 0000000..97f4c46 --- /dev/null +++ b/doc/reference/LessThanComparable.xml @@ -0,0 +1,81 @@ + + + + + The type must be a model of . + + LessThanComparable types must have <, + >, <=, and >= + operators. + + + + + + + + + + + + + + Determine if one value is less than another. + + + + + + + + + + + + + Determine if one value is less than or equal to another. + + + + + + + + + + + + + Determine if one value is greater than another. + + + + + + + + + + + + + Determine if one value is greater than or equal to another. + + + + + + diff --git a/doc/reference/OutputIterator.xml b/doc/reference/OutputIterator.xml new file mode 100644 index 0000000..d3f8062 --- /dev/null +++ b/doc/reference/OutputIterator.xml @@ -0,0 +1,203 @@ + + + + + + + + The iterator type (with value type ) must be a model of . + + + An output iterator is an iterator that can write a sequence of + values. It is single-pass (old values of the iterator cannot be + re-used), and write-only. + + An output iterator represents a position in a (possibly infinite) + sequence. Therefore, the iterator can point into the sequence (returning + a value when dereferenced and being incrementable), or be off-the-end + (and not dereferenceable or incrementable). + + + + + + + + + + + + + + + + + + + + + + + + + The stated value type of the iterator (should be + void for an output iterator that does not model some other + iterator concept). + + + + + + + + + The difference type of the iterator + + + + + + + + + The category of the iterator + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + + + + i is incrementable (not + off-the-end) + *i may not be written to again until it has + been incremented. + + + + + + + + + + + + i is incrementable (not + off-the-end) + + + + + + + + i is incrementable (not + off-the-end) + Equivalent to (void)(++i) + i is dereferenceable or + off-the-end + + + + + + + + + + + + + i is incrementable (not + off-the-end) + Equivalent to {*i = t; ++i;} + i is dereferenceable or + off-the-end + + + + All iterator operations must take amortized constant time. + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/reference/RandomAccessIterator.xml b/doc/reference/RandomAccessIterator.xml new file mode 100644 index 0000000..f77f8fd --- /dev/null +++ b/doc/reference/RandomAccessIterator.xml @@ -0,0 +1,313 @@ + + + + + + + The iterator type must be a model of . + + + A random access iterator is an iterator that can read through + a sequence of values. It can move in either direction through the + sequence (by any amount in constant time), and can be either mutable + (data pointed to by it can be changed) or not mutable. + + An iterator represents a position in a sequence. Therefore, + the iterator can point into the sequence (returning a value when + dereferenced and being incrementable), or be off-the-end (and not + dereferenceable or incrementable). + + + + + + + + + The value type of the iterator + + + + + + + + + + + + + + + + + + The category of the iterator + + + + + + + + + The difference type of the iterator (measure of the number + of steps between two iterators) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Equivalent to applying i++ n times + if n is positive, applying i-- + -n times if n is negative, and to a null + operation if n is zero. + + + + + + + + + + + + + Equivalent to applying i++ n times + if n is positive, applying i-- + -n times if n is negative, and to a null + operation if n is zero. + + + + + + + + + + + + + Equivalent to i+=(-n) + + + + + + + + + + + + + Equivalent to i+=(-n) + + + + + + + + + + + Equivalent to {Iter j = i; j += n; return j;} + + + + + + + + + + + Equivalent to {Iter j = i; j += n; return j;} + + + + + + + + + + + Equivalent to i + n + + + + + + + + + + + Equivalent to i + n + + + + + + + + + + + Equivalent to i + (-n) + + + + + + + + + + + Equivalent to i + (-n) + + + + + + + + + + + The number of times i must be incremented (or + decremented if the result is negative) to reach j. Not + defined if j is not reachable from + i. + + + + + + + + + + + + + + + + + Equivalent to *(i + n) + + + + + + + + + + + + + + + + + Equivalent to *(i + n) + + + + All iterator operations must take amortized constant time. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/reference/SignedInteger.xml b/doc/reference/SignedInteger.xml new file mode 100644 index 0000000..d47693b --- /dev/null +++ b/doc/reference/SignedInteger.xml @@ -0,0 +1,549 @@ + + + + + Integer type must be a model of . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/reference/concepts.xml b/doc/reference/concepts.xml new file mode 100644 index 0000000..bd7cce0 --- /dev/null +++ b/doc/reference/concepts.xml @@ -0,0 +1,78 @@ + + + + + + 2001 + 2002 + Indiana University + + + + 2000 + 2001 + University of Notre Dame du Lac + + + + 2000 + Jeremy Siek + Lie-Quan Lee + Andrew Lumsdaine + + + + 1996 + 1997 + 1998 + 1999 + Silicon Graphics Computer Systems, Inc. + + + + 1994 + Hewlett-Packard Company + + + + This product includes software developed at the University + of Notre Dame and the Pervasive Technology Labs at Indiana + University. For technical information contact Andrew Lumsdaine + at the Pervasive Technology Labs at Indiana University. For + administrative and license questions contact the Advanced + Research and Technology Institute at 351 West 10th Street. + Indianapolis, Indiana 46202, phone 317-278-4100, fax + 317-274-5902. + + Some concepts based on versions from the MTL draft manual + and Boost Graph and Property Map documentation, the SGI Standard + Template Library documentation and the Hewlett-Packard STL, + under the following license: +
Permission to use, copy, modify, distribute and + sell this software and its documentation for any purpose is + hereby granted without fee, provided that the above copyright + notice appears in all copies and that both that copyright + notice and this permission notice appear in supporting + documentation. Silicon Graphics makes no representations + about the suitability of this software for any purpose. It is + provided "as is" without express or implied + warranty.
 + + + Concept reference + + + + + + + + + + + + +