|
|
Boost-Commit : |
From: asutton_at_[hidden]
Date: 2007-08-13 18:11:23
Author: asutton
Date: 2007-08-13 18:11:18 EDT (Mon, 13 Aug 2007)
New Revision: 38636
URL: http://svn.boost.org/trac/boost/changeset/38636
Log:
Revising concept docs
Text files modified:
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/copy_constructible.qbk | 54 ++++++++---------
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/default_constructible.qbk | 123 ++++++++-------------------------------
sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/destructible.qbk | 60 ++++---------------
3 files changed, 65 insertions(+), 172 deletions(-)
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-08-13 18:11:18 EDT (Mon, 13 Aug 2007)
@@ -6,14 +6,16 @@
/]
[section Copy Constructible]
-A type `T` is /copy constructible/ if it is possible to create copies
-of that type. `T` is only copy constructible if it has either a
-compiler-generated or user-defined copy constructor that accepts a single
-argument: a `const` reference to `T`. After construction, a constructed
-object is equivalent to the object passed as an argument.
+A type `T` is /copy constructible/ if it is possible to create copies of an
+object that type using a copy constructor. `T` is only copy constructible
+if it has either a compiler-generated or user-defined copy constructor that
+accepts a single argument: a `const` reference to `T`. After construction,
+a constructed object is equivalent to the object passed as an argument.
+[note
Two objects `t` and `u` are equivalent if the expression `t == u` returns
-`true`.
+`true`. See [StdEqualityComparable] for more information.
+]
[heading Refinement of]
[StdDestructible]
@@ -33,12 +35,13 @@
[
[Copy Constructor]
[
- `T t(u);`
+ `T t(u);` [br/]
`T t = u;`
]
[]
[
- *Semantics:* `t` is declared as an object of type `T`.
+ The object `t` is declared as an object of type `T` whose
+ value or state is equivalent to `u`
*Postcondition:* `t` is equivalent to `u`.
]
@@ -48,7 +51,8 @@
[`T(u)`]
[`T`]
[
- *Semantics:* Creates an object of type `T`.
+ Construct an object of type `T` whose value or state is
+ equivalent to `u`.
*Postcondition:* `t` is equivalent to `u`.
]
@@ -57,27 +61,21 @@
[heading Notes]
A type that explicitly defines a private copy constructor is not
-[StdCopyConstructible]. These types are also called non-copyable types.
+[StdCopyConstructible]. These types are called non-copyable types.
[heading Examples]
-
-
-[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 MoveConstructible<typename T>
- :``[StdDestructible]``<T>
- {
- T::T(T&&);
- };
-
- auto concept CopyConstructible<typename T>
- : MoveConstructible<T>
+A type `T` is required to be [StdCopyConstructible] when an object of type `T`
+is when the copy constructor of `T` is invoked passing another object of
+type `T` as an argument.
+
+ // This function requires `T` to be copy constructible because it declares
+ // an object of type T constructed with the value of u. If T is not
+ // ``[StdCopyConstructible]``, calling this function will result in a
+ // compiler error.
+ template <typename T>
+ void copy_declare(const T& u)
{
- T::T(const T&);
- };
+ T t(u);
+ }
[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-08-13 18:11:18 EDT (Mon, 13 Aug 2007)
@@ -9,10 +9,14 @@
A type `T` is /default constructible/ if objects of type `T` can be constructed
without providing any arguments to a constructor. A type that is default
constructible has either a compiler-generated or user-defined constructor
-that can be called without arguments. [StdDefaultConstructible] types may or
-may not initilize objects to a default value or state depending on the the
-type itself and the syntax used for construction. Objects that are not initialized
-to a default value have indeterminate value (i.e., uninitialized).
+that can be called without arguments.
+
+[note
+[StdDefaultConstructible] types may or may not initilize objects to a default value
+or state depending on the type itself and the syntax used for construction. Objects
+that are not initialized to a default are /uninitialized. Reading from or otherwise
+using uninitialized objects often results in undefined behavior.
+]
[heading Refinement of]
[StdDestructible]
@@ -33,7 +37,7 @@
[`T x;`]
[]
[
- *Semantics:* `x` is declared as an object of type `T` and may or may not
+ The object `x` is constructed as an object of type `T` and may or may not
initialized to a default value[footnote This syntax leaves fundamental
types unitialized while class types are default-initialized.].
]
@@ -43,7 +47,7 @@
[`T()`]
[`T`]
[
- *Semantics:* Creates object of type `T` is initialized to a default
+ Constructs an object of type `T` and is initializes it to its default
value[footnote This syntax will zero-initialize scalar and other
fundamental types and default-initialize others.].
]
@@ -55,105 +59,30 @@
model the [StdDefaultConstructible] concept.
[heading Examples]
-All fundamental types in C++ are [StdDefaultConstructible] but may not have default
-values, depending on how they are constructed.
+A type `T` is required to be [StdDefaultConstructible] when an object of type `T` is
+declared or when the default constructor of `T` is invoked without arguments.
- // Declare an uninitialized integer x. Reading the value of x before
- // assigning it a value may result in a compiler warning (if compiled with
- // appropriate warning levels).
- int x;
-
- // Create a (temporary) floating point value with a default value. Using
- // this default constructor form causes the value to be zero-initialized
- // so the output will be 0.
- std::cout << float() << std::endl;
-
-Types in the standard library are also [StdDefaultConstructible]. Most of these are
-initialized to default values when constructed.
-
- // Declare a 0-length vector of integers. Because std::vector is a
- // user-defined, this declaration invokes the default constructor.
- std::vector<int> v;
-
- // Create an empty string. Because the default construtor of the
- // std::string string class initializes an empty string object this will
- // not print anything.
- std::cout << string() << std::endl;
-
-Creating user-defined types that are [StdDefaultConstructible] can be done in two
-ways: explicitly providing a default constructor or allowing the compiler to generate
-it. The following examples shows two [StdDefaultConstructible] implementations of
-the same class.
-
- // Define a default-constructible type by explicitly defining a default
- // constructor. Here, both member variables x and y will be default-
- // initialized since the member list initializer explicitly invokes
- // their default constructors.
- struct default_initialized_point
- {
- int x, y;
-
- point() : x(), y()
- { }
- };
-
- // Define a default-constructible type by allowing the compiler to
- // generate it. In this instance, x and y are not default-initialized
- // since the default constructors are not explicitly called. The compiler
- // does not generate the default cosntructor in the class above.
- struct uninitialized_point
- {
- int x, y;
- };
-
- // Create both types of the points. These are default-constructed, but only
- // a is default-initialized.
- default_initialized_point a;
- unitialized_point b;
-
- // This will print 0,0.
- std::cout << a.x << "," << a.y << std::endl;
-
- // This may print garbage.
- std::cout << b.x << "," << b.y << std::endl;
-
-A type `T` is required to be [StdDefaultConstructible] within a template when an
-object of type `T` is declared or when the default constructor of `T` is invoked to
-create an object.
-
- // This function requires T to be default-constructible because it declares
- // a local variable of type T.
+ // This functions requires T to be ``[StdDefaultConstructible]`` because it
+ // declares an object of type T without providing any arguments to the default
+ // constructor. If T is not default constructible, calling this function will
+ // result in a compiler error.
template <typename T>
- void require_default_constructible()
+ void default_declare()
{
- T empty;
- // unspecified...
+ T x;
}
- // This function requires T to b default-constructible because it
- // explicilty invokes T's default constructor to print the default value.
+ // This function requires T to be ``[StdDefaultConstructible]`` because it
+ // explicitly invokes a constructor of T wihtout any arguments. If T is not
+ // default constructible, calling this function will result in a compiler
+ // error.
template <typename T>
- void print_default_value()
+ T default_construct()
{
- std::cout << T() << std::endl;
+ return T();
}
-[heading C++0x]
-The [StdDefaultConstructible] 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:
-
- // This concept requires that T be constructible with a variable number
- // of arguments. Constructible types are required to be Desctructible.
- auto concept Constructible<typename T, typename... Args>
- :``[StdDestructible]``<T>
- {
- T::T(Args...);
- };
-
- // This concept requires that T be Constructible with no arguments.
- auto concept DefaultConstructible<typename T>
- : Constructible<T>
- {};
+[heading Models]
+All fundamental types such as `bool`, `int`, and `float` are [StdDefaultConstructible].
[endsect]
\ No newline at end of file
Modified: sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/destructible.qbk
==============================================================================
--- sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/destructible.qbk (original)
+++ sandbox/boost_docs/trunk/libs/standard/doc/concepts/utilities/destructible.qbk 2007-08-13 18:11:18 EDT (Mon, 13 Aug 2007)
@@ -25,8 +25,7 @@
[`t.~T()`]
[]
[
- *Semantics:* The destructor of `t` is called, destroying
- the object.
+ The destructor of `t` is called, destroying the object.
*Exceptions:* Destructors must not throw exceptions.
]
@@ -38,51 +37,18 @@
is not [StdDestructible].
[heading Examples]
-In practice, there are very few types that are not destructible. The
-destructors of these types (whether implicitly or user-defined) are
-invoked when the lifetime of the [StdDestructible] object ends. For
-local (automatic) objects, this is when they go out of scope. For
-dynamically allocated (via `new`), this is when they are deleted. For
-static objects, this is when the program ends (maybe).
-
- int main()
- {
- std::string s;
- } // s goes out of scope, calling s.~std::string()
-
-A user-defined types are [StdDestructible] if they have an implicitly
-or user-defined destructor. In the following example, both types are
-[StdDestructible].
-
- // This type is destructible since it explicitly provides
- // a public destructor.
- struct foo
- {
- ~foo()
- { }
- };
-
- // This type is destructible since the destructor is
- // provided by the compiler.
- struct bar
- { };
-
- // This class is not destructible since the destructor
- // is declared with private visibility.
- class do_not_destroy
- {
- ~do_not_destroy()
- { }
- };
-
-[heading C++0x]
-The [StdDestructible] concept will be defined as:
-
- // The Destructible concept requires a public desctructor,
- // either compiler-generated or user-defined.
- auto concept Destructible<typename T>
+In practice, there are non-[StdDestructible] types are infrequent. Any type
+whose objects are statically or locally declared is required to be model the
+[StdDestructible] concept. Any type whose objects are `delete`d are also required
+to be [StdDestructible].
+
+ // This function requires T to be ``[StdDestructible]`` because it
+ // explicitly invokes the destructor. If T is not destructible,
+ // calling this function will result in a compiler error.
+ template <typename T>
+ void destruct(T& t)
{
- T::~T();
- };
+ t.~T();
+ }
[endsect]
\ No newline at end of file
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