Examples

@@ -209,8 +209,8 @@ public:

- <emphasis>ValueType</emphasis> requirements +

+ <bold>ValueType</bold> requirements Values are strongly informational objects for which identity is not significant, i.e. the focus is principally on @@ -473,7 +473,7 @@ public: -

Acknowledgements Doug Gregor ported the documentation to the BoostBook format. diff --git a/docbook/relaxng/api/tests/api.docbook b/docbook/relaxng/api/tests/api.docbook new file mode 100644 index 000000000..7ec98c314 --- /dev/null +++ b/docbook/relaxng/api/tests/api.docbook @@ -0,0 +1,424 @@ + + + + + What's Included in This Document + + + This document represents only a subset of the full Boost + documentation: that part which is generated from BoostBook or + QuickBook sources. Eventually all Boost libraries may use these + formats, but in the meantime, much of Boost's documentation is not + available here. Please + see http://www.boost.org/libs + for complete documentation. + + + + Documentation for some of the libraries described in this document is + available in alternative formats: + + + HTML (tarred, gzipped) + + + PDF + + + + Unix man pages + + + + DocBook + + + + XSL Formatting Objects + + + + + + + + The Boost C++ Libraries (BoostBook Subset) + + + + + Kevlin Henney + + 2001 + Kevlin Henney + + 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) + + + + Boost.Any + +

+ Introduction + + There are times when a generic (in the sense of + general as opposed to + template-based programming) type is needed: + variables that are truly variable, accommodating values of many + other more specific types rather than C++'s normal strict and + static types. We can distinguish three basic kinds of generic + type: + + + + Converting types that can hold one of a number of + possible value types, e.g. int and + string, and freely convert between them, for + instance interpreting 5 as "5" or + vice-versa. Such types are common in scripting and other + interpreted + languages. + boost::lexical_cast + supports such conversion functionality. + + + + Discriminated types that contain values of different types but + do not attempt conversion between them, i.e. 5 is + held strictly as an int and is not implicitly + convertible either to "5" or to + 5.0. Their indifference to interpretation but + awareness of type effectively makes them safe, generic + containers of single values, with no scope for surprises from + ambiguous conversions. + + + + Indiscriminate types that can refer to anything but are + oblivious to the actual underlying type, entrusting all forms + of access and interpretation to the programmer. This niche is + dominated by void *, which offers plenty of scope + for surprising, undefined behavior. + + + + The boost::any class + (based on the class of the same name described in "Valued + Conversions" by Kevlin Henney, C++ + Report 12(7), July/August 2000) is a variant value type + based on the second category. It supports copying of any value + type and safe checked extraction of that value strictly against + its type. A similar design, offering more appropriate operators, + can be used for a generalized function adaptor, + any_function, a generalized iterator adaptor, + any_iterator, and other object types that need + uniform runtime treatment but support only compile-time template + parameter conformance. +

+ +

+ Examples + + + + + The following code demonstrates the syntax for using + implicit conversions to and copying of any objects: + + +#include <list> +#include <boost/any.hpp> + +using boost::any_cast; +typedef std::list<boost::any> many; + +void append_int(many & values, int value) +{ + boost::any to_append = value; + values.push_back(to_append); +} + +void append_string(many & values, const std::string & value) +{ + values.push_back(value); +} + +void append_char_ptr(many & values, const char * value) +{ + values.push_back(value); +} + +void append_any(many & values, const boost::any & value) +{ + values.push_back(value); +} + +void append_nothing(many & values) +{ + values.push_back(boost::any()); +} + + + The following predicates follow on from the previous + definitions and demonstrate the use of queries on any + objects: + + +bool is_empty(const boost::any & operand) +{ + return operand.empty(); +} + +bool is_int(const boost::any & operand) +{ + return operand.type() == typeid(int); +} + +bool is_char_ptr(const boost::any & operand) +{ + try + { + any_cast<const char *>(operand); + return true; + } + catch(const boost::bad_any_cast &) + { + return false; + } +} + +bool is_string(const boost::any & operand) +{ + return any_cast<std::string>(&operand); +} + +void count_all(many & values, std::ostream & out) +{ + out << "#empty == " + << std::count_if(values.begin(), values.end(), is_empty) << std::endl; + out << "#int == " + << std::count_if(values.begin(), values.end(), is_int) << std::endl; + out << "#const char * == " + << std::count_if(values.begin(), values.end(), is_char_ptr) << std::endl; + out << "#string == " + << std::count_if(values.begin(), values.end(), is_string) << std::endl; +} + + + The following type, patterned after the OMG's Property Service, defines name-value pairs for arbitrary value types: + + +struct property +{ + property(); + property(const std::string &, const boost::any &); + + std::string name; + boost::any value; +}; + +typedef std::list<property> properties; + + + The following base class demonstrates one approach to + runtime polymorphism based callbacks that also require arbitrary + argument types. The absence of virtual member templates requires + that different solutions have different trade-offs in terms of + efficiency, safety, and generality. Using a checked variant type + offers one approach: + + +class consumer +{ +public: + virtual void notify(const any &) = 0; + ... +}; + +

+ +

Reference +

+ <emphasis role="bold">ValueType</emphasis> requirements + + Values are strongly informational objects for which + identity is not significant, i.e. the focus is principally on + their state content and any behavior organized around + that. Another distinguishing feature of values is their + granularity: normally fine-grained objects representing simple + concepts in the system such as quantities. + + As the emphasis of a value lies in its state not its + identity, values can be copied and typically assigned one to + another, requiring the explicit or implicit definition of a + public copy constructor and public assignment operator. Values + typically live within other scopes, i.e. within objects or + blocks, rather than on the heap. Values are therefore normally + passed around and manipulated directly as variables or through + references, but not as pointers that emphasize identity and + indirection. + + The specific requirements on value types to be used in an + any + are: + + + A ValueType is + CopyConstructible [20.1.3]. + + + A ValueType is + optionally Assignable [23.1]. The strong + exception-safety guarantee is required for all forms of + assignment. + + + The destructor for a + ValueType upholds the no-throw + exception-safety guarantee. + + +

+ +

Header <<ulink url="../../boost/any.hpp">boost/any.hpp</ulink>>namespace boost { + class bad_any_cast; + class any; + template<> T any_cast(any &); + template<> T any_cast(const any &); + template<> const ValueType * any_cast(const any *); + template<> ValueType * any_cast(any *); +} + Class bad_any_cast3boost::bad_any_castThe exception thrown in the event of a failed + any_cast of an + any value.// In header: <boost/any.hpp> + + +class bad_any_cast : public std::bad_cast { +public: + virtual const char * what() const; +};Descriptionvirtual const char * what() const;Class any3boost::anyA class whose instances can hold instances of any + type that satisfies ValueType + requirements.// In header: <boost/any.hpp> + + +class any { +public: + // construct/copy/destruct + any(); + any(const any &); + template<> any(const ValueType &); + any & operator=(const any &); + template<> any & operator=(const ValueType &); + ~any(); + + // modifiers + any & swap(any &); + + // queries + bool empty() const; + const std::type_info & type() const; +};Description<anchor id="boost.anyconstruct-copy-destruct"/><computeroutput>any</computeroutput> + public + construct/copy/destructany();Postconditions:this->empty()any(const any & other);Effects: Copy constructor that copies content of + other into new instance, so that any content + is equivalent in both type and value to the content of + other, or empty if other is + empty. Throws:May fail with a + std::bad_alloc + exception or any exceptions arising from the copy + constructor of the contained type.template<> any(const ValueType & value);Effects:Makes a copy of value, so + that the initial content of the new instance is equivalent + in both type and value to + value.Throws:std::bad_alloc + or any exceptions arising from the copy constructor of the + contained type.any & operator=(const any & rhs);Effects:Copies content of rhs into + current instance, discarding previous content, so that the + new content is equivalent in both type and value to the + content of rhs, or empty if + rhs.empty().Throws:std::bad_alloc + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety.template<> any & operator=(const ValueType & rhs);Effects:Makes a copy of rhs, + discarding previous content, so that the new content of is + equivalent in both type and value to + rhs.Throws:std::bad_alloc + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety.~any();Effects:Releases any and all resources used in + management of instance.Throws:Nothing.<anchor id="id61937-bb"/><computeroutput>any</computeroutput> modifiersany & swap(any & rhs);Effects:Exchange of the contents of + *this and + rhs.Returns:*thisThrows:Nothing.<anchor id="id61992-bb"/><computeroutput>any</computeroutput> queriesbool empty() const;Returns:true if instance is + empty, otherwise false.Throws:Will not throw.const std::type_info & type() const;Returns:the typeid of the + contained value if instance is non-empty, otherwise + typeid(void).Notes:Useful for querying against types known + either at compile time or only at + runtime.Function any_cast3boost::any_castCustom keyword cast for extracting a value + of a given type from an + any.// In header: <boost/any.hpp> + + +template<> T any_cast(any & operand); +template<> T any_cast(const any & operand); +template<> const ValueType * any_cast(const any * operand); +template<> ValueType * any_cast(any * operand);DescriptionReturns: If passed a pointer, it returns a + similarly qualified pointer to the value content if + successful, otherwise null is returned. + If T is ValueType, it returns a copy of the held value, otherwise, if T is a reference + to (possibly const qualified) ValueType, it returns a reference to the held + value.Throws:Overloads taking an + any pointer do not + throw; overloads taking an + any value or reference + throws bad_any_cast if + unsuccessful. +

+ +

+ Acknowledgements + + Doug Gregor ported the documentation to the BoostBook format. +

+ + + + + Boost Tools + + + + Boost developers, testers, and maintainers have developed various programs to + help with the administration of the Boost Libraries. Like everything else about + Boost, these tools are available in source form, and are part of the regular + Boost distribution. + + + Users may find these tools useful when porting Boost libraries to a new platform, + or for use with their own applications. + + + + + diff --git a/docbook/relaxng/api/tests/boost.xml b/docbook/relaxng/api/tests/boost.xml new file mode 100644 index 000000000..d4a87c7aa --- /dev/null +++ b/docbook/relaxng/api/tests/boost.xml @@ -0,0 +1,550 @@ + + + + + + What's Included in This Document + + + This document represents only a subset of the full Boost + documentation: that part which is generated from BoostBook or + QuickBook sources. Eventually all Boost libraries may use these + formats, but in the meantime, much of Boost's documentation is not + available here. Please + see http://www.boost.org/libs + for complete documentation. + + + + Documentation for some of the libraries described in this document is + available in alternative formats: + + + HTML (tarred, gzipped) + + + PDF + + + + Unix man pages + + + + DocBook + + + + XSL Formatting Objects + + + + + + + + The Boost C++ Libraries (BoostBook Subset) + + + + + + + Boost Tools + + + + Boost developers, testers, and maintainers have developed various programs to + help with the administration of the Boost Libraries. Like everything else about + Boost, these tools are available in source form, and are part of the regular + Boost distribution. + + + Users may find these tools useful when porting Boost libraries to a new platform, + or for use with their own applications. + + + + + diff --git a/docbook/relaxng/api/tests/html/any/acknowledgments.html b/docbook/relaxng/api/tests/html/any/acknowledgments.html new file mode 100644 index 000000000..57899e654 --- /dev/null +++ b/docbook/relaxng/api/tests/html/any/acknowledgments.html @@ -0,0 +1,32 @@ + + + +Acknowledgements + + + + + + + + +

+Acknowledgements

Doug Gregor ported the documentation to the BoostBook format.

+ + + +

+ + diff --git a/docbook/relaxng/api/tests/html/any/examples.html b/docbook/relaxng/api/tests/html/any/examples.html new file mode 100644 index 000000000..5c00ae5aa --- /dev/null +++ b/docbook/relaxng/api/tests/html/any/examples.html @@ -0,0 +1,137 @@ + + + +Examples + + + + + + + + +

+Examples

The following code demonstrates the syntax for using + implicit conversions to and copying of any objects:

+#include <list>
+#include <boost/any.hpp>
+
+using boost::any_cast;
+typedef std::list<boost::any> many;
+
+void append_int(many & values, int value)
+{
+    boost::any to_append = value;
+    values.push_back(to_append);
+}
+
+void append_string(many & values, const std::string & value)
+{
+    values.push_back(value);
+}
+
+void append_char_ptr(many & values, const char * value)
+{
+    values.push_back(value);
+}
+
+void append_any(many & values, const boost::any & value)
+{
+    values.push_back(value);
+}
+
+void append_nothing(many & values)
+{
+    values.push_back(boost::any());
+}
+

The following predicates follow on from the previous + definitions and demonstrate the use of queries on any + objects:

+bool is_empty(const boost::any & operand)
+{
+    return operand.empty();
+}
+
+bool is_int(const boost::any & operand)
+{
+    return operand.type() == typeid(int);
+}
+
+bool is_char_ptr(const boost::any & operand)
+{
+    try
+    {
+        any_cast<const char *>(operand);
+        return true;
+    }
+    catch(const boost::bad_any_cast &)
+    {
+        return false;
+    }
+}
+
+bool is_string(const boost::any & operand)
+{
+    return any_cast<std::string>(&operand);
+}
+
+void count_all(many & values, std::ostream & out)
+{
+    out << "#empty == "
+        << std::count_if(values.begin(), values.end(), is_empty) << std::endl;
+    out << "#int == "
+        << std::count_if(values.begin(), values.end(), is_int) << std::endl;
+    out << "#const char * == "
+        << std::count_if(values.begin(), values.end(), is_char_ptr) << std::endl;
+    out << "#string == "
+        << std::count_if(values.begin(), values.end(), is_string) << std::endl;
+}
+

The following type, patterned after the OMG's Property Service, defines name-value pairs for arbitrary value types:

+struct property
+{
+    property();
+    property(const std::string &, const boost::any &);
+
+    std::string name;
+    boost::any value;
+};
+
+typedef std::list<property> properties;
+

The following base class demonstrates one approach to + runtime polymorphism based callbacks that also require arbitrary + argument types. The absence of virtual member templates requires + that different solutions have different trade-offs in terms of + efficiency, safety, and generality. Using a checked variant type + offers one approach:

+class consumer
+{
+public:
+    virtual void notify(const any &) = 0;
+    ...
+};
+

+ + + +

+ + diff --git a/docbook/relaxng/api/tests/html/any/reference.html b/docbook/relaxng/api/tests/html/any/reference.html new file mode 100644 index 000000000..051ee9356 --- /dev/null +++ b/docbook/relaxng/api/tests/html/any/reference.html @@ -0,0 +1,76 @@ + + + +Reference + + + + + + + + +

+Reference

+ValueType requirements

Values are strongly informational objects for which + identity is not significant, i.e. the focus is principally on + their state content and any behavior organized around + that. Another distinguishing feature of values is their + granularity: normally fine-grained objects representing simple + concepts in the system such as quantities.

As the emphasis of a value lies in its state not its + identity, values can be copied and typically assigned one to + another, requiring the explicit or implicit definition of a + public copy constructor and public assignment operator. Values + typically live within other scopes, i.e. within objects or + blocks, rather than on the heap. Values are therefore normally + passed around and manipulated directly as variables or through + references, but not as pointers that emphasize identity and + indirection.

The specific requirements on value types to be used in an + any + are:

A ValueType is + CopyConstructible [20.1.3].
A ValueType is + optionally Assignable [23.1]. The strong + exception-safety guarantee is required for all forms of + assignment.
The destructor for a + ValueType upholds the no-throw + exception-safety guarantee.

+Header <boost/any.hpp>

namespace boost {
+  class bad_any_cast;
+  class any;
+  template<> T any_cast(any &);
+  template<> T any_cast(const any &);
+  template<> const ValueType * any_cast(const any *);
+  template<> ValueType * any_cast(any *);
+}

+ + + +

+ + diff --git a/docbook/relaxng/api/tests/html/boost/any.html b/docbook/relaxng/api/tests/html/boost/any.html new file mode 100644 index 000000000..79f86187c --- /dev/null +++ b/docbook/relaxng/api/tests/html/boost/any.html @@ -0,0 +1,257 @@ + + + +Class any + + + + + + + + +

Class any

boost::any — A class whose instances can hold instances of any + type that satisfies ValueType + requirements.

Synopsis

// In header: <boost/any.hpp>
+
+
+class any {
+public:
+  // construct/copy/destruct
+  any();
+  any(const any &);
+  template<> any(const ValueType &);
+  any & operator=(const any &);
+  template<> any & operator=(const ValueType &);
+  ~any();
+
+  // modifiers
+  any & swap(any &);
+
+  // queries
+  bool empty() const;
+  const std::type_info & type() const;
+};

Description

+`any` + public + construct/copy/destruct

+
```
any();
```
+
++ + + + +

Postconditions:
this->empty()
+

any(const any & other);

++ + + + + + + + + + +

Effects:	Copy constructor that copies content of + `other` into new instance, so that any content + is equivalent in both type and value to the content of + `other`, or empty if `other` is + empty.
Throws:	May fail with a + `std::bad_alloc` + exception or any exceptions arising from the copy + constructor of the contained type.

template<> any(const ValueType & value);

++ + + + + + + + + + +

Effects:	Makes a copy of `value`, so + that the initial content of the new instance is equivalent + in both type and value to + `value`.
Throws:	+`std::bad_alloc` + or any exceptions arising from the copy constructor of the + contained type.

any & operator=(const any & rhs);

++ + + + + + + + + + +

Effects:	Copies content of `rhs` into + current instance, discarding previous content, so that the + new content is equivalent in both type and value to the + content of `rhs`, or empty if + `rhs.empty()`.
Throws:	+`std::bad_alloc` + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety.

template<> any & operator=(const ValueType & rhs);

++ + + + + + + + + + +

Effects:	Makes a copy of `rhs`, + discarding previous content, so that the new content of is + equivalent in both type and value to + `rhs`.
Throws:	+`std::bad_alloc` + or any exceptions arising from the copy constructor of the + contained type. Assignment satisfies the strong guarantee + of exception safety.

+
```
~any();
```
+
++ + + + + + + + + + +

Effects:
Releases any and all resources used in + management of instance.
Throws:
Nothing.
+

+`any` modifiers

any & swap(any & rhs);

++ + + + + + + + + + + + + + +

Effects:	Exchange of the contents of + `*this` and + `rhs`.
Returns:	`*this`
Throws:	Nothing.

+`any` queries

bool empty() const;

++ + + + + + + + + + +

Returns:	+`true` if instance is + empty, otherwise `false`.
Throws:	Will not throw.

const std::type_info & type() const;

++ + + + + + + + + + +

Returns:	the `typeid` of the + contained value if instance is non-empty, otherwise + `typeid(void)`.
Notes:	Useful for querying against types known + either at compile time or only at + runtime.

+ + + +

+ + diff --git a/docbook/relaxng/api/tests/html/boost/any_cast.html b/docbook/relaxng/api/tests/html/boost/any_cast.html new file mode 100644 index 000000000..108e1b858 --- /dev/null +++ b/docbook/relaxng/api/tests/html/boost/any_cast.html @@ -0,0 +1,72 @@ + + + +Function any_cast + + + + + + + + +

Function any_cast

boost::any_cast — Custom keyword cast for extracting a value + of a given type from an + any.

Synopsis

// In header: <boost/any.hpp>
+
+
+template<> T any_cast(any & operand);
+template<> T any_cast(const any & operand);
+template<> const ValueType * any_cast(const any * operand);
+template<> ValueType * any_cast(any * operand);

Description

++ + + + + + + + + + +

Returns:	If passed a pointer, it returns a + similarly qualified pointer to the value content if + successful, otherwise null is returned. + If T is ValueType, it returns a copy of the held value, otherwise, if T is a reference + to (possibly const qualified) ValueType, it returns a reference to the held + value.
Throws:	Overloads taking an + `any` pointer do not + throw; overloads taking an + `any` value or reference + throws `bad_any_cast` if + unsuccessful.

+ + + +

+ + diff --git a/docbook/relaxng/api/tests/html/boost/bad_any_cast.html b/docbook/relaxng/api/tests/html/boost/bad_any_cast.html new file mode 100644 index 000000000..0cb9c3479 --- /dev/null +++ b/docbook/relaxng/api/tests/html/boost/bad_any_cast.html @@ -0,0 +1,50 @@ + + + +Class bad_any_cast + + + + + + + + +

Class bad_any_cast

boost::bad_any_cast — The exception thrown in the event of a failed + any_cast of an + any value.

Synopsis

// In header: <boost/any.hpp>
+
+
+class bad_any_cast : public std::bad_cast {
+public:
+  virtual const char * what() const;
+};

Description

virtual const char * what() const;

+ + + +

+ +

Effects:	Releases any and all resources used in + management of instance.
Throws:	Nothing.

+Acknowledgements

+Examples

+Reference

+ValueType requirements

+Header <boost/any.hpp>

Class any

Synopsis

Description

+any + public + construct/copy/destruct

+any modifiers

+any queries

Function any_cast

Synopsis

Description

Class bad_any_cast

Synopsis

Description

+`any` + public + construct/copy/destruct

+`any` modifiers

+`any` queries