diff --git a/doc/BOOST_BINARY.qbk b/doc/BOOST_BINARY.qbk index 8abf94a..d89d8a1 100644 --- a/doc/BOOST_BINARY.qbk +++ b/doc/BOOST_BINARY.qbk @@ -6,8 +6,7 @@ /] [/===============] -[#sec:BOOST_BINARY] -[section Binary Integer Literals] +[section:BOOST_BINARY Binary Integer Literals] [/===============] [section Introduction] diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 7c80e8b..427ad51 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -285,6 +285,7 @@ doxygen result_of_reference doxygen string_view_reference : $(INCLUDES)/boost/utility/string_view.hpp + $(INCLUDES)/boost/utility/string_ref.hpp : tmp ENABLE_PREPROCESSING=YES diff --git a/doc/call_traits.qbk b/doc/call_traits.qbk index 9ca0e97..dd43687 100644 --- a/doc/call_traits.qbk +++ b/doc/call_traits.qbk @@ -7,7 +7,7 @@ /] [/===============] -[section Call Traits] +[section:call_traits Call Traits] [/===============] [section Introduction] @@ -19,9 +19,9 @@ The template class __call_traits_T__ encapsulates the "best" method to pass a parameter of some type `T` to or from a function, and consists of a collection of `typedef`s defined as in the table below. The purpose of __call_traits__ is to ensure -that problems like [link sec:refs "references to references"] +that problems like [link utility.utilities.call_traits.examples.refs "references to references"] never occur, and that parameters are passed in the most efficient -manner possible, as in the [link sec:examples examples]. In each +manner possible, as in the [link utility.utilities.call_traits.examples examples]. In each case, if your existing practice is to use the type defined on the left, then replace it with the __call_traits__ defined type on the right. @@ -100,7 +100,7 @@ used to solve the reference to reference problem. Notes: # If `T` is already reference type, then __call_traits__ is - defined such that [link sec:refs "references to references"] + defined such that [link utility.utilities.call_traits.examples.refs "references to references"] do not occur (requires partial specialization). # If `T` is an array type, then __call_traits__ defines `value_type` as a "constant pointer to type" rather than an @@ -145,8 +145,7 @@ If `T` is an assignable type the following assignments are possible: ] [endsect] -[#sec:examples] -[section Examples] +[section:examples Examples] The following table shows the effect that __call_traits__ has on various types. @@ -204,8 +203,7 @@ struct contained ``` [endsect] -[#sec:refs] -[section Example 2 (the reference to reference problem):] +[section:refs Example 2 (the reference to reference problem):] Consider the definition of __std_binder1st__: @@ -241,8 +239,7 @@ the no "reference to reference" occurs. [endsect] -[#sec:example3] -[section Example 3 (the `make_pair` problem):] +[section:example3 Example 3 (the `make_pair` problem):] If we pass the name of an array as one (or both) arguments to `__std_make_pair__`, then template argument deduction deduces the passed parameter as @@ -277,8 +274,7 @@ __std_make_pair__ are not expressed in terms of __call_traits__: doing so would prevent template argument deduction from functioning. [endsect] -[#sec:example4] -[section Example 4 (optimising fill):] +[section:example4 Example 4 (optimising fill):] The __call_traits__ template will "optimize" the passing of a small built-in type as a function parameter. This mainly has @@ -359,12 +355,12 @@ Small built-in types, what the standard calls [@https://en.cppreference.com/w/cp types], differ from existing practice only in the `param_type` `typedef`. In this case passing `T const` is compatible with existing practice, but may improve performance in some cases -(see [link sec:example4 Example 4]). In any case this should never +(see [link utility.utilities.call_traits.examples.example4 Example 4]). In any case this should never be any worse than existing practice. Pointers follow the same rationale as small built-in types. -For reference types the rationale follows [link sec:refs Example 2] +For reference types the rationale follows [link utility.utilities.call_traits.examples.refs Example 2] - references to references are not allowed, so the __call_traits__ members must be defined such that these problems do not occur. There is a proposal to modify the language such that @@ -425,7 +421,7 @@ For `value_type` (return by value), again only a pointer may be returned, not a copy of the whole array, and again __call_traits__ makes the degradation explicit. The `value_type` member is useful whenever an array must be explicitly degraded to a pointer - -[link sec:example3 Example 3] provides the test case. +[link utility.utilities.call_traits.examples.example3 Example 3] provides the test case. Footnote: the array specialisation for __call_traits__ is the least well understood of all the __call_traits__ specialisations. If the given diff --git a/doc/compressed_pair.qbk b/doc/compressed_pair.qbk index 154c8a7..842b11a 100644 --- a/doc/compressed_pair.qbk +++ b/doc/compressed_pair.qbk @@ -8,7 +8,7 @@ or copy at http://boost.org/LICENSE_1_0.txt ] -[section Compressed Pair] +[section:compressed_pair Compressed Pair] [section Introduction] diff --git a/doc/in_place_factory.qbk b/doc/in_place_factory.qbk index 42a0795..7646579 100644 --- a/doc/in_place_factory.qbk +++ b/doc/in_place_factory.qbk @@ -7,8 +7,7 @@ /] [/===============] -[#sec:in_place_factory] -[section In-place Factory] +[section:in_place_factory In-place Factory] [/===============] [section Introduction] @@ -296,7 +295,6 @@ void foo() [endsect] [/===============] -[#boost.typed_in_place_factory_base] [xinclude tmp/in_place_factory_reference.xml] [/===============] diff --git a/doc/main.qbk b/doc/main.qbk index f7574e1..3f9e23b 100644 --- a/doc/main.qbk +++ b/doc/main.qbk @@ -57,113 +57,113 @@ [/ (Macros are defined here because these macros are often referenced in other components) ] [/ (operators macros link to the a table of operators because there's no doxygen reference for the operators) ] -[def __BOOST_BINARY__ [link sec:BOOST_BINARY `BOOST_BINARY`]] -[def __in_place_factory__ [link sec:in_place_factory `in_place_factory`]] +[def __BOOST_BINARY__ [link utility.utilities.BOOST_BINARY `BOOST_BINARY`]] +[def __in_place_factory__ [link utility.utilities.in_place_factory `in_place_factory`]] -[def __boost_base_from_member__ [link boost.base_from_member `boost::base_from_member`]] -[def __boost_call_traits__ [link boost.call_traits `boost::call_traits`]] -[def __boost_result_of__ [link boost.result_of `boost::result_of`]] -[def __boost_tr1_result_of__ [link boost.tr1_result_of `boost::tr1_result_of`]] -[def __boost_string_view__ [link boost.basic_string_view `boost::string_view`]] -[def __boost_basic_string_view__ [link boost.basic_string_view `boost::basic_string_view`]] +[def __boost_base_from_member__ [classref boost::base_from_member `boost::base_from_member`]] +[def __boost_call_traits__ [classref boost::call_traits `boost::call_traits`]] +[def __boost_result_of__ [classref boost::result_of `boost::result_of`]] +[def __boost_tr1_result_of__ [classref boost::tr1_result_of `boost::tr1_result_of`]] +[def __boost_string_view__ [classref boost::basic_string_view `boost::string_view`]] +[def __boost_basic_string_view__ [classref boost::basic_string_view `boost::basic_string_view`]] -[def __additive1__ [link sec:arithmetic `additive1`]] -[def __additive2__ [link sec:arithmetic `additive2`]] -[def __arithmetic1__ [link sec:arithmetic `arithmetic1`]] -[def __arithmetic2__ [link sec:arithmetic `arithmetic2`]] -[def __base_from_member__ [link boost.base_from_member `base_from_member`]] -[def __basic_string_ref__ [link boost.basic_string_view `basic_string_ref`]] -[def __basic_string_view__ [link boost.basic_string_view `basic_string_view`]] -[def __bidirectional_iteratable__ [link sec:arithmetic `bidirectional_iteratable`]] -[def __bidirectional_iterator_helper__ [link sec:arithmetic `bidirectional_iterator_helper`]] -[def __bitwise1__ [link sec:arithmetic `bitwise1`]] -[def __bitwise2__ [link sec:arithmetic `bitwise2`]] -[def __call_traits__ [link boost.call_traits `call_traits`]] -[def __call_traits_T__ [link boost.call_traits `call_traits`]] -[def __call_traits_lt__T___ [link boost.call_traits `call_traits`]] -[def __call_traits_lt__T_lb_N_rb__gt___ [link boost.call_traits `call_traits< T[N]>`]] -[def __call_traits_lt__const_T_lb_N_rb__gt___ [link boost.call_traits `call_traits< const T[N]>`]] -[def __compressed_pair__ [link boost.compressed_pair `compressed_pair`]] -[def __decrementable__ [link sec:arithmetic `decrementable`]] -[def __dereferenceable__ [link sec:arithmetic `dereferenceable`]] -[def __equal_pointees__ [link sec:arithmetic `equal_pointees`]] -[def __equal_pointees_t__ [link sec:arithmetic `equal_pointees_t`]] -[def __equality_comparable1__ [link sec:arithmetic `equality_comparable1`]] -[def __equality_comparable2__ [link sec:arithmetic `equality_comparable2`]] -[def __equivalent1__ [link sec:arithmetic `equivalent1`]] -[def __equivalent2__ [link sec:arithmetic `equivalent2`]] -[def __euclidean_ring_operators1__ [link sec:arithmetic `euclidean_ring_operators1`]] -[def __euclidean_ring_operators2__ [link sec:arithmetic `euclidean_ring_operators2`]] -[def __field_operators1__ [link sec:arithmetic `field_operators1`]] -[def __field_operators2__ [link sec:arithmetic `field_operators2`]] -[def __forward_iteratable__ [link sec:arithmetic `forward_iteratable`]] -[def __forward_iterator_helper__ [link sec:arithmetic `forward_iterator_helper`]] -[def __get__ [link boost.get `get`]] -[def __hash_range__ [link boost.hash_range `hash_range`]] -[def __hash_value__ [link boost.hash_value `hash_value`]] -[def __in_place_factory_base__ [link boost.in_place_factory_base `in_place_factory_base`]] -[def __incrementable__ [link sec:arithmetic `incrementable`]] -[def __indexable__ [link sec:arithmetic `indexable`]] -[def __initialized__ [link boost.initialized `initialized`]] -[def __initialized_value__ [link boost.initialized_value `initialized_value`]] -[def __initialized_value_t__ [link boost.initialized_value_t `initialized_value_t`]] -[def __input_iteratable__ [link sec:arithmetic `input_iteratable`]] -[def __input_iterator_helper__ [link sec:arithmetic `input_iterator_helper`]] -[def __integer_arithmetic1__ [link sec:arithmetic `integer_arithmetic1`]] -[def __integer_arithmetic2__ [link sec:arithmetic `integer_arithmetic2`]] -[def __integer_multiplicative1__ [link sec:arithmetic `integer_multiplicative1`]] -[def __integer_multiplicative2__ [link sec:arithmetic `integer_multiplicative2`]] -[def __is_chained_base__ [link sec:arithmetic `is_chained_base`]] -[def __less_pointees__ [link boost.less_pointees `less_pointees`]] -[def __less_pointees_t__ [link boost.less_pointees_t `less_pointees_t`]] -[def __less_than_comparable1__ [link sec:arithmetic `less_than_comparable1`]] -[def __less_than_comparable2__ [link sec:arithmetic `less_than_comparable2`]] -[def __multiplicative1__ [link sec:arithmetic `multiplicative1`]] -[def __multiplicative2__ [link sec:arithmetic `multiplicative2`]] -[def __operator_eq__eq__ [link sec:arithmetic `operator==`]] -[def __operator_gt__ [link sec:arithmetic `operator_gt_`]] -[def __operator_gt__eq__ [link sec:arithmetic `operator>`]] -[def __operator_lt__ [link sec:arithmetic `operator<`]] -[def __operator_lt__eq__ [link sec:arithmetic `operator<=`]] -[def __operator_lt__lt__ [link sec:arithmetic `operator<<`]] -[def __operator_not__eq__ [link sec:arithmetic `operator!=`]] -[def __operators2__ [link sec:arithmetic `operators2`]] -[def __operators__ [link sec:arithmetic `operators`]] -[def __operators_lt_T__ [link sec:arithmetic `operators`]] -[def __ordered_euclidean_ring_operators1__ [link sec:arithmetic `ordered_euclidean_ring_operators1`]] -[def __ordered_euclidean_ring_operators2__ [link sec:arithmetic `ordered_euclidean_ring_operators2`]] -[def __ordered_euclidian_ring_operators1__ [link sec:arithmetic `ordered_euclidian_ring_operators1`]] -[def __ordered_euclidian_ring_operators2__ [link sec:arithmetic `ordered_euclidian_ring_operators2`]] -[def __ordered_field_operators1__ [link sec:arithmetic `ordered_field_operators1`]] -[def __ordered_field_operators2__ [link sec:arithmetic `ordered_field_operators2`]] -[def __ordered_ring_operators1__ [link sec:arithmetic `ordered_ring_operators1`]] -[def __ordered_ring_operators2__ [link sec:arithmetic `ordered_ring_operators2`]] -[def __output_iteratable__ [link sec:arithmetic `output_iteratable`]] -[def __output_iterator_helper__ [link sec:arithmetic `output_iterator_helper`]] -[def __partially_ordered1__ [link sec:arithmetic `partially_ordered1`]] -[def __partially_ordered2__ [link sec:arithmetic `partially_ordered2`]] -[def __random_access_iteratable__ [link sec:arithmetic `random_access_iteratable`]] -[def __random_access_iterator_helper__ [link sec:arithmetic `random_access_iterator_helper`]] -[def __result_of__ [link boost.result_of `result_of`]] -[def __ring_operators1__ [link sec:arithmetic `ring_operators1`]] -[def __ring_operators2__ [link sec:arithmetic `ring_operators2`]] -[def __shiftable1__ [link sec:arithmetic `shiftable1`]] -[def __shiftable2__ [link sec:arithmetic `shiftable2`]] -[def __string_ref__ [link boost.basic_string_view `string_ref`]] -[def __string_view__ [link boost.basic_string_view `string_view`]] -[def __swap__ [link sec:arithmetic `swap`]] -[def __totally_ordered1__ [link sec:arithmetic `totally_ordered1`]] -[def __totally_ordered2__ [link sec:arithmetic `totally_ordered2`]] -[def __tr1_result_of__ [link boost.tr1_result_of `tr1_result_of`]] -[def __typed_in_place_factory_base__ [link boost.typed_in_place_factory_base `typed_in_place_factory_base`]] -[def __u16string_ref__ [link boost.basic_string_view `u16string_ref`]] -[def __u16string_view__ [link boost.basic_string_view `u16string_view`]] -[def __u32string_ref__ [link boost.basic_string_view `u32string_ref`]] -[def __u32string_view__ [link boost.basic_string_view `u32string_view`]] -[def __unit_steppable__ [link sec:arithmetic `unit_steppable`]] -[def __value_initialized__ [link boost.value_initialized `value_initialized`]] -[def __wstring_ref__ [link boost.basic_string_view `wstring_ref`]] -[def __wstring_view__ [link boost.basic_string_view `wstring_view`]] +[def __additive1__ [link utility.utilities.operators.arithmetic `additive1`]] +[def __additive2__ [link utility.utilities.operators.arithmetic `additive2`]] +[def __arithmetic1__ [link utility.utilities.operators.arithmetic `arithmetic1`]] +[def __arithmetic2__ [link utility.utilities.operators.arithmetic `arithmetic2`]] +[def __base_from_member__ [classref boost::base_from_member `base_from_member`]] +[def __basic_string_ref__ [classref boost::basic_string_ref `basic_string_ref`]] +[def __basic_string_view__ [classref boost::basic_string_view `basic_string_view`]] +[def __bidirectional_iteratable__ [link utility.utilities.operators.arithmetic `bidirectional_iteratable`]] +[def __bidirectional_iterator_helper__ [link utility.utilities.operators.arithmetic `bidirectional_iterator_helper`]] +[def __bitwise1__ [link utility.utilities.operators.arithmetic `bitwise1`]] +[def __bitwise2__ [link utility.utilities.operators.arithmetic `bitwise2`]] +[def __call_traits__ [classref boost::call_traits `call_traits`]] +[def __call_traits_T__ [classref boost::call_traits `call_traits`]] +[def __call_traits_lt__T___ [classref boost::call_traits `call_traits`]] +[def __call_traits_lt__T_lb_N_rb__gt___ [classref boost::call_traits `call_traits< T[N]>`]] +[def __call_traits_lt__const_T_lb_N_rb__gt___ [classref boost::call_traits `call_traits< const T[N]>`]] +[def __compressed_pair__ [classref boost::compressed_pair `compressed_pair`]] +[def __decrementable__ [link utility.utilities.operators.arithmetic `decrementable`]] +[def __dereferenceable__ [link utility.utilities.operators.arithmetic `dereferenceable`]] +[def __equal_pointees__ [link utility.utilities.operators.arithmetic `equal_pointees`]] +[def __equal_pointees_t__ [link utility.utilities.operators.arithmetic `equal_pointees_t`]] +[def __equality_comparable1__ [link utility.utilities.operators.arithmetic `equality_comparable1`]] +[def __equality_comparable2__ [link utility.utilities.operators.arithmetic `equality_comparable2`]] +[def __equivalent1__ [link utility.utilities.operators.arithmetic `equivalent1`]] +[def __equivalent2__ [link utility.utilities.operators.arithmetic `equivalent2`]] +[def __euclidean_ring_operators1__ [link utility.utilities.operators.arithmetic `euclidean_ring_operators1`]] +[def __euclidean_ring_operators2__ [link utility.utilities.operators.arithmetic `euclidean_ring_operators2`]] +[def __field_operators1__ [link utility.utilities.operators.arithmetic `field_operators1`]] +[def __field_operators2__ [link utility.utilities.operators.arithmetic `field_operators2`]] +[def __forward_iteratable__ [link utility.utilities.operators.arithmetic `forward_iteratable`]] +[def __forward_iterator_helper__ [link utility.utilities.operators.arithmetic `forward_iterator_helper`]] +[def __get__ [funcref boost::get `get`]] +[def __hash_range__ [funcref boost::hash_range `hash_range`]] +[def __hash_value__ [funcref boost::hash_value `hash_value`]] +[def __in_place_factory_base__ [classref boost::in_place_factory_base `in_place_factory_base`]] +[def __incrementable__ [link utility.utilities.operators.arithmetic `incrementable`]] +[def __indexable__ [link utility.utilities.operators.arithmetic `indexable`]] +[def __initialized__ [classref boost::initialized `initialized`]] +[def __initialized_value__ [globalref boost::initialized_value `initialized_value`]] +[def __initialized_value_t__ [classref boost::initialized_value_t `initialized_value_t`]] +[def __input_iteratable__ [link utility.utilities.operators.arithmetic `input_iteratable`]] +[def __input_iterator_helper__ [link utility.utilities.operators.arithmetic `input_iterator_helper`]] +[def __integer_arithmetic1__ [link utility.utilities.operators.arithmetic `integer_arithmetic1`]] +[def __integer_arithmetic2__ [link utility.utilities.operators.arithmetic `integer_arithmetic2`]] +[def __integer_multiplicative1__ [link utility.utilities.operators.arithmetic `integer_multiplicative1`]] +[def __integer_multiplicative2__ [link utility.utilities.operators.arithmetic `integer_multiplicative2`]] +[def __is_chained_base__ [link utility.utilities.operators.arithmetic `is_chained_base`]] +[def __less_pointees__ [funcref boost::less_pointees `less_pointees`]] +[def __less_pointees_t__ [class boost::less_pointees_t `less_pointees_t`]] +[def __less_than_comparable1__ [link utility.utilities.operators.arithmetic `less_than_comparable1`]] +[def __less_than_comparable2__ [link utility.utilities.operators.arithmetic `less_than_comparable2`]] +[def __multiplicative1__ [link utility.utilities.operators.arithmetic `multiplicative1`]] +[def __multiplicative2__ [link utility.utilities.operators.arithmetic `multiplicative2`]] +[def __operator_eq__eq__ [link utility.utilities.operators.arithmetic `operator==`]] +[def __operator_gt__ [link utility.utilities.operators.arithmetic `operator_gt_`]] +[def __operator_gt__eq__ [link utility.utilities.operators.arithmetic `operator>`]] +[def __operator_lt__ [link utility.utilities.operators.arithmetic `operator<`]] +[def __operator_lt__eq__ [link utility.utilities.operators.arithmetic `operator<=`]] +[def __operator_lt__lt__ [link utility.utilities.operators.arithmetic `operator<<`]] +[def __operator_not__eq__ [link utility.utilities.operators.arithmetic `operator!=`]] +[def __operators2__ [link utility.utilities.operators.arithmetic `operators2`]] +[def __operators__ [link utility.utilities.operators.arithmetic `operators`]] +[def __operators_lt_T__ [link utility.utilities.operators.arithmetic `operators`]] +[def __ordered_euclidean_ring_operators1__ [link utility.utilities.operators.arithmetic `ordered_euclidean_ring_operators1`]] +[def __ordered_euclidean_ring_operators2__ [link utility.utilities.operators.arithmetic `ordered_euclidean_ring_operators2`]] +[def __ordered_euclidian_ring_operators1__ [link utility.utilities.operators.arithmetic `ordered_euclidian_ring_operators1`]] +[def __ordered_euclidian_ring_operators2__ [link utility.utilities.operators.arithmetic `ordered_euclidian_ring_operators2`]] +[def __ordered_field_operators1__ [link utility.utilities.operators.arithmetic `ordered_field_operators1`]] +[def __ordered_field_operators2__ [link utility.utilities.operators.arithmetic `ordered_field_operators2`]] +[def __ordered_ring_operators1__ [link utility.utilities.operators.arithmetic `ordered_ring_operators1`]] +[def __ordered_ring_operators2__ [link utility.utilities.operators.arithmetic `ordered_ring_operators2`]] +[def __output_iteratable__ [link utility.utilities.operators.arithmetic `output_iteratable`]] +[def __output_iterator_helper__ [link utility.utilities.operators.arithmetic `output_iterator_helper`]] +[def __partially_ordered1__ [link utility.utilities.operators.arithmetic `partially_ordered1`]] +[def __partially_ordered2__ [link utility.utilities.operators.arithmetic `partially_ordered2`]] +[def __random_access_iteratable__ [link utility.utilities.operators.arithmetic `random_access_iteratable`]] +[def __random_access_iterator_helper__ [link utility.utilities.operators.arithmetic `random_access_iterator_helper`]] +[def __result_of__ [classref boost::result_of `result_of`]] +[def __ring_operators1__ [link utility.utilities.operators.arithmetic `ring_operators1`]] +[def __ring_operators2__ [link utility.utilities.operators.arithmetic `ring_operators2`]] +[def __shiftable1__ [link utility.utilities.operators.arithmetic `shiftable1`]] +[def __shiftable2__ [link utility.utilities.operators.arithmetic `shiftable2`]] +[def __string_ref__ [classref boost::basic_string_ref `string_ref`]] +[def __string_view__ [classref boost::basic_string_view `string_view`]] +[def __swap__ [link utility.utilities.operators.arithmetic `swap`]] +[def __totally_ordered1__ [link utility.utilities.operators.arithmetic `totally_ordered1`]] +[def __totally_ordered2__ [link utility.utilities.operators.arithmetic `totally_ordered2`]] +[def __tr1_result_of__ [classref boost::tr1_result_of `tr1_result_of`]] +[def __typed_in_place_factory_base__ [classref boost::typed_in_place_factory_base `typed_in_place_factory_base`]] +[def __u16string_ref__ [classref boost::basic_string_ref `u16string_ref`]] +[def __u16string_view__ [classref boost::basic_string_view `u16string_view`]] +[def __u32string_ref__ [classref boost::basic_string_ref `u32string_ref`]] +[def __u32string_view__ [classref boost::basic_string_view `u32string_view`]] +[def __unit_steppable__ [link utility.utilities.operators.arithmetic `unit_steppable`]] +[def __value_initialized__ [classref boost::value_initialized `value_initialized`]] +[def __wstring_ref__ [classref boost::basic_string_ref `wstring_ref`]] +[def __wstring_view__ [classref boost::basic_string_view `wstring_view`]] [/ std:: types ] @@ -219,8 +219,7 @@ [include other.qbk] -[#sec:reference] -[section:ref Quick Reference] +[section:reference Quick Reference] [/ Reference table ] [xinclude quickref.xml] diff --git a/doc/operators.qbk b/doc/operators.qbk index 0e68f17..590a05a 100644 --- a/doc/operators.qbk +++ b/doc/operators.qbk @@ -7,8 +7,7 @@ /] [/===============] -[#sec:operators] -[section Operators] +[section:operators Operators] [/===============] [section Introduction] @@ -20,8 +19,7 @@ operators provided by the class. [endsect] -[#sec:rationale] -[section Rationale] +[section:rationale Rationale] Overloaded operators for class types typically occur in groups. If you can write `x + y`, you probably also want to be able to write `x += y`. @@ -60,23 +58,22 @@ class MyInt then the __operators__<> template adds more than a dozen additional operators, such as `operator>`, `operator<=`, `operator>=`, and the binary `operator+`. -[link sec:two_arg Two-argument forms] of the templates are also provided to allow interaction with other types. +[link utility.utilities.operators.usage.two_arg Two-argument forms] of the templates are also provided to allow interaction with other types. -[#sec:semantics] +[#utility.utilities.operators.rationale.semantics] This is a ['Summary of Template Semantics]: # Each operator template completes the concept(s) it describes by defining overloaded operators for its target class. -# The name of an operator class template indicates the [link sec:concepts_note concept] that its target class will model. +# The name of an operator class template indicates the [link utility.utilities.operators.rationale.concepts_note concept] that its target class will model. # Usually, the target class uses an instantiation of the operator class template as a base class. Some operator templates support an - [link sec:explicit_instantiation alternate method]. + [link utility.utilities.operators.usage.explicit_instantiation alternate method]. # The concept can be compound, i.e. it may represent a common combination of other, simpler concepts. # Most operator templates require their target class to support operations related to the operators supplied by the template. In accordance with widely accepted [@http://www.gotw.ca/gotw/004.htm coding style recommendations], the target class is often required to supply the assignment counterpart operator of the concept's "main operator." For example, the `addable` template requires `operator+=(T const&)` and in turn supplies `operator+(T const&, T const&)`. -[#sec:concepts_note] - +[#utility.utilities.operators.rationale.concepts_note] ['Note on the use of concepts]: The discussed concepts are not necessarily the standard library's concepts, such as __CopyConstructible__, although some of them could be; they are what we call ['concepts with a small 'c']. In @@ -94,10 +91,9 @@ target classes from different domains, i.e. eventually more useful. [endsect] -[#sec:example] -[section Example] +[section:example Example] -This example shows how some of the [link sec:arithmetic arithmetic +This example shows how some of the [link utility.utilities.operators.arithmetic arithmetic operator templates] can be used with a geometric point class template. @@ -151,17 +147,13 @@ const point pi_over_4_normalized = pi_over_4 / length(pi_over_4); [endsect] -[#sec:usage] -[section Usage] +[section:usage Usage] -[#sec:two_arg] -[h5 Two-Argument Template Forms] - -[#sec:two_arg_gen] +[section:two_arg Two-Argument Template Forms] The arguments to a binary operator commonly have identical types, but it is not unusual to want to define operators which combine different -types. For [link sec:example example], one might want to multiply a +types. For [link utility.utilities.operators.example example], one might want to multiply a mathematical vector by a scalar. The two-argument template forms of the arithmetic operator templates are supplied for this purpose. When applying the two-argument form of a template, the desired return type of @@ -169,22 +161,21 @@ the operators typically determines which of the two types in question should be derived from the operator template. For example, if the result of `T + U` is of type `T`, then `T` (not `U`) -should be derived from [link table:addable2 `addable`]. The comparison -templates [link table:less_than_comparable2 `less_than_comparable`], -[link table:equality_comparable2 `equality_comparable`], -[link table:equivalent2 `equivalent`], and -[link table:partially_ordered2 `partially_ordered`] are exceptions to +should be derived from [link utility.utilities.operators.arithmetic.smpl_oprs.addable2 `addable`]. The comparison +templates [link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable2 `less_than_comparable`], +[link utility.utilities.operators.arithmetic.smpl_oprs.equality_comparable2 `equality_comparable`], +[link utility.utilities.operators.arithmetic.smpl_oprs.equivalent2 `equivalent`], and +[link utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered2 `partially_ordered`] are exceptions to this guideline, since the return type of the operators they define is `bool`. On compilers which do not support partial specialization, the two-argument forms must be specified by using the names shown below with the trailing `'2'`. The single-argument forms with the trailing `'1'` are provided for symmetry and to enable certain -applications of the [link sec:chaining base class chaining] +applications of the [link utility.utilities.operators.usage.chaining base class chaining] technique. -[#sec:mixed_arithmetics] - +[#utility.utilities.operators.usage.two_arg.mixed_arithmetics] ['Mixed Arithmetics]: Another application of the two-argument template forms is for mixed arithmetics between a type `T` and a type `U` that @@ -205,9 +196,9 @@ be different from the user's intention. To define a complete set of operator signatures, additional 'left' forms of the two-argument template forms are provided -[link table:subtractable2_left `subtractable2_left`], -[link table:dividable2_left `dividable2_left`], and -[link table:modable2_left `modable2_left`] that +[link utility.utilities.operators.arithmetic.smpl_oprs.subtractable2_left `subtractable2_left`], +[link utility.utilities.operators.arithmetic.smpl_oprs.dividable2_left `dividable2_left`], and +[link utility.utilities.operators.arithmetic.smpl_oprs.modable2_left `modable2_left`] that define the signatures for non-commutative operators where `U` appears on the left hand side (`operator-(const U&, const T&)`, `operator/(const U&, const T&)`, `operator%(const U&, const T&)`). @@ -226,21 +217,22 @@ conversion from `U` to `T` and have an implementation equivalent to the code that would be automatically created by the compiler if it considered the single type binary operator to be the best match. -[#sec:chaining] -[h5 Base Class Chaining and Object Size] +[endsect] -Every operator class template, except the [link sec:ex_oprs arithmetic examples] -and the [link sec:iterator iterator helpers], has an additional, but optional, +[section:chaining Base Class Chaining and Object Size] + +Every operator class template, except the [link utility.utilities.operators.arithmetic.ex_oprs arithmetic examples] +and the [link utility.utilities.operators.deref.iterator iterator helpers], has an additional, but optional, template type parameter `B`. This parameter will be a publicly-derived base class of the instantiated template. This means it must be a class type. It can be used to avoid the bloating of object sizes that is commonly associated with multiple-inheritance from several empty base classes. See the -[link sec:old_lib_note note for users of older versions] for more +[link utility.utilities.operators.old_lib_note note for users of older versions] for more details. To provide support for a group of operators, use the `B` parameter to chain operator templates into a single-base -class hierarchy, demostrated in the [link sec:example usage example]. +class hierarchy, demostrated in the [link utility.utilities.operators.example usage example]. The technique is also used by the composite operator templates to group operator definitions. If a chain becomes too long for the compiler to support, try replacing some of the operator templates with a single @@ -249,14 +241,15 @@ length limit only applies to the number of templates directly in the chain, not those hidden in group templates. ['Caveat]: to chain to a base class which is ['not] a Boost operator -template when using the [link sec:two_arg single-argument form] of a Boost +template when using the [link utility.utilities.operators.usage.two_arg single-argument form] of a Boost operator template, you must specify the operator template with the trailing `'1'` in its name. Otherwise the library will assume you mean to define a binary operation combining the class you intend to use as a base class and the class you're deriving. -[#sec:explicit_instantiation] -[h5 Separate Explicit Instantiation] +[endsect] + +[section:explicit_instantiation Separate Explicit Instantiation] On some compilers (e.g. Borland, GCC) even single-inheritance seems to cause an increase in object size in some cases. If you are not @@ -279,16 +272,14 @@ template struct addable; template struct subtractable; ``` - - Note that some operator templates cannot use this workaround and must be a base class of their primary operand type. Those templates define operators which must be member functions, and the workaround needs the operators to be independent `friend` functions. The relevant templates are: -* [link table:dereferenceable `dereferenceable<>`] -* [link table:indexable `indexable<>`] +* [link utility.utilities.operators.deref.dereference.dereferenceable `dereferenceable<>`] +* [link utility.utilities.operators.deref.dereference.indexable `indexable<>`] * Any composite operator template that includes at least one of the above As Daniel Krugler pointed out, this technique violates C++11 [sect]14.6.5/2 \[temp.inject\] @@ -298,23 +289,25 @@ rules given by C++11 [sect]3.4.2/2 \[basic.lookup.argdep\], since `my_class` is an associated class of `less_than_comparable`. Thus only use this technique if all else fails. -[#sec:portability] -[h5 Requirement Portability] +[endsect] + +[section:portability Requirement Portability] Many compilers (e.g. MSVC 6.3, GCC 2.95.2) will not enforce the requirements in the operator template tables unless the operations which depend on them are actually used. This is not standard-conforming behavior. In particular, although it would be convenient to derive all -your classes which need binary operators from the [link table:operators1 `operators<>`] -and [link table:operators2 `operators2<>`] templates, regardless of +your classes which need binary operators from the [link utility.utilities.operators.arithmetic.ex_oprs.operators1 `operators<>`] +and [link utility.utilities.operators.arithmetic.ex_oprs.operators2 `operators2<>`] templates, regardless of whether they implement all the requirements of those templates, this shortcut is not portable. Even if this currently works with your compiler, it may not work later. [endsect] -[#sec:arithmetic] -[section Arithmetic Operators] +[endsect] + +[section:arithmetic Arithmetic Operators] The arithmetic operator templates ease the task of creating a custom numeric type. Given a core set of operators, the templates add related @@ -332,13 +325,12 @@ what other templates they use. The supplied operations and requirements of the composite operator templates can be inferred from the operations and requirements of the listed components. -[#sec:smpl_oprs] -[h5 Simple Arithmetic Operators] +[section:smpl_oprs Simple Arithmetic Operators] These templates are "simple" since they provide operators based on a single operation the base type has to provide. They have an additional optional template parameter `B`, which is not shown, for the -[link sec:chaining base class chaining] technique. +[link utility.utilities.operators.usage.chaining base class chaining] technique. The primary operand type `T` needs to be of class type, built-in types are not supported. @@ -355,7 +347,7 @@ built-in types are not supported. [[Template] [Supplied Operations] [Requirements] [Propagates constexpr]] [ [ - [#table:less_than_comparable1] `less_than_comparable` + [#utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable1] `less_than_comparable` __less_than_comparable1__`` ] @@ -371,7 +363,7 @@ built-in types are not supported. [ `t < t1`. - Return convertible to `bool`. See the [link sec:ordering Ordering Note] + Return convertible to `bool`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.ordering Ordering Note] ] [ @@ -381,7 +373,7 @@ built-in types are not supported. [ [ - [#table:less_than_comparable2]`less_than_comparable` + [#utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable2]`less_than_comparable` __less_than_comparable2__`` ] @@ -403,7 +395,7 @@ built-in types are not supported. [ `t < u`. `t > u`. - Returns convertible to `bool`. See the [link sec:ordering Ordering Note]. + Returns convertible to `bool`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.ordering Ordering Note]. ] [ @@ -413,7 +405,7 @@ built-in types are not supported. [ [ - [#table:equality_comparable1]`equality_comparable` + [#utility.utilities.operators.arithmetic.smpl_oprs.equality_comparable1]`equality_comparable` __equality_comparable1__`` ] @@ -435,7 +427,7 @@ built-in types are not supported. [ [ - [#table:equality_comparable2]`equality_comparable` + [#utility.utilities.operators.arithmetic.smpl_oprs.equality_comparable2]`equality_comparable` __equality_comparable2__`` ] @@ -461,7 +453,7 @@ built-in types are not supported. [ [ - [#table:addable1]`addable` + [#utility.utilities.operators.arithmetic.smpl_oprs.addable1]`addable` `addable1` ] @@ -473,7 +465,7 @@ built-in types are not supported. [ `T temp(t); temp += t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -481,7 +473,7 @@ built-in types are not supported. [ [ - [#table:addable2]`addable` + [#utility.utilities.operators.arithmetic.smpl_oprs.addable2]`addable` `addable2` ] @@ -495,7 +487,7 @@ built-in types are not supported. [ `T temp(t); temp += u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -503,7 +495,7 @@ built-in types are not supported. [ [ - [#table:subtractable1]`subtractable` + [#utility.utilities.operators.arithmetic.smpl_oprs.subtractable1]`subtractable` `subtractable1` ] @@ -515,7 +507,7 @@ built-in types are not supported. [ `T temp(t); temp -= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -523,7 +515,7 @@ built-in types are not supported. [ [ - [#table:subtractable2]`subtractable` + [#utility.utilities.operators.arithmetic.smpl_oprs.subtractable2]`subtractable` `subtractable2` ] @@ -535,7 +527,7 @@ built-in types are not supported. [ `T temp(t); temp -= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -543,7 +535,7 @@ built-in types are not supported. [ [ - [#table:subtractable2_left]`subtractable2_left` + [#utility.utilities.operators.arithmetic.smpl_oprs.subtractable2_left]`subtractable2_left` ] [ @@ -561,7 +553,7 @@ built-in types are not supported. [ [ - [#table:multipliable1]`multipliable` + [#utility.utilities.operators.arithmetic.smpl_oprs.multipliable1]`multipliable` `multipliable1` ] @@ -573,7 +565,7 @@ built-in types are not supported. [ `T temp(t); temp *= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -581,7 +573,7 @@ built-in types are not supported. [ [ - [#table:multipliable2]`multipliable` + [#utility.utilities.operators.arithmetic.smpl_oprs.multipliable2]`multipliable` `multipliable2` ] @@ -595,7 +587,7 @@ built-in types are not supported. [ `T temp(t); temp *= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -603,7 +595,7 @@ built-in types are not supported. [ [ - [#table:dividable1]`dividable` + [#utility.utilities.operators.arithmetic.smpl_oprs.dividable1]`dividable` `dividable1` ] @@ -615,7 +607,7 @@ built-in types are not supported. [ `T temp(t); temp /= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -623,7 +615,7 @@ built-in types are not supported. [ [ - [#table:dividable2]`dividable` + [#utility.utilities.operators.arithmetic.smpl_oprs.dividable2]`dividable` `dividable2` ] @@ -635,7 +627,7 @@ built-in types are not supported. [ `T temp(t); temp /= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -643,7 +635,7 @@ built-in types are not supported. [ [ - [#table:dividable2_left]`dividable2_left` + [#utility.utilities.operators.arithmetic.smpl_oprs.dividable2_left]`dividable2_left` ] [ @@ -661,7 +653,7 @@ built-in types are not supported. [ [ - [#table:modable1]`modable` + [#utility.utilities.operators.arithmetic.smpl_oprs.modable1]`modable` `modable1` ] @@ -673,7 +665,7 @@ built-in types are not supported. [ `T temp(t); temp %= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -681,7 +673,7 @@ built-in types are not supported. [ [ - [#table:modable2]`modable` + [#utility.utilities.operators.arithmetic.smpl_oprs.modable2]`modable` `modable2` ] @@ -693,7 +685,7 @@ built-in types are not supported. [ `T temp(t); temp %= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -701,7 +693,7 @@ built-in types are not supported. [ [ - [#table:modable2_left]`modable2_left` + [#utility.utilities.operators.arithmetic.smpl_oprs.modable2_left]`modable2_left` ] [ @@ -719,7 +711,7 @@ built-in types are not supported. [ [ - [#table:orable1]`orable` + [#utility.utilities.operators.arithmetic.smpl_oprs.orable1]`orable` `orable1` ] @@ -731,7 +723,7 @@ built-in types are not supported. [ `T temp(t); temp |= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -739,7 +731,7 @@ built-in types are not supported. [ [ - [#table:orable2]`orable` + [#utility.utilities.operators.arithmetic.smpl_oprs.orable2]`orable` `orable2` ] @@ -753,7 +745,7 @@ built-in types are not supported. [ `T temp(t); temp |= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -761,7 +753,7 @@ built-in types are not supported. [ [ - [#table:andable1]`andable` + [#utility.utilities.operators.arithmetic.smpl_oprs.andable1]`andable` `andable1` ] @@ -773,7 +765,7 @@ built-in types are not supported. [ `T temp(t); temp &= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -781,7 +773,7 @@ built-in types are not supported. [ [ - [#table:andable2]`andable` + [#utility.utilities.operators.arithmetic.smpl_oprs.andable2]`andable` `andable2` ] @@ -795,7 +787,7 @@ built-in types are not supported. [ `T temp(t); temp &= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -803,7 +795,7 @@ built-in types are not supported. [ [ - [#table:xorable1]`xorable` + [#utility.utilities.operators.arithmetic.smpl_oprs.xorable1]`xorable` `xorable1` ] @@ -815,7 +807,7 @@ built-in types are not supported. [ `T temp(t); temp ^= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -823,7 +815,7 @@ built-in types are not supported. [ [ - [#table:xorable2]`xorable` + [#utility.utilities.operators.arithmetic.smpl_oprs.xorable2]`xorable` `xorable2` ] @@ -837,7 +829,7 @@ built-in types are not supported. [ `T temp(t); temp ^= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -845,7 +837,7 @@ built-in types are not supported. [ [ - [#table:incrementable]`incrementable` + [#utility.utilities.operators.arithmetic.smpl_oprs.incrementable]`incrementable` ] [ @@ -863,7 +855,7 @@ built-in types are not supported. [ [ - [#table:decrementable]`decrementable` + [#utility.utilities.operators.arithmetic.smpl_oprs.decrementable]`decrementable` ] [ @@ -881,7 +873,7 @@ built-in types are not supported. [ [ - [#table:left_shiftable1]`left_shiftable` + [#utility.utilities.operators.arithmetic.smpl_oprs.left_shiftable1]`left_shiftable` `left_shiftable1` ] @@ -893,7 +885,7 @@ built-in types are not supported. [ `T temp(t); temp <<= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -901,7 +893,7 @@ built-in types are not supported. [ [ - [#table:left_shiftable2]`left_shiftable` + [#utility.utilities.operators.arithmetic.smpl_oprs.left_shiftable2]`left_shiftable` `left_shiftable2` ] @@ -913,7 +905,7 @@ built-in types are not supported. [ `T temp(t); temp <<= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -921,7 +913,7 @@ built-in types are not supported. [ [ - [#table:right_shiftable1]`right_shiftable` + [#utility.utilities.operators.arithmetic.smpl_oprs.right_shiftable1]`right_shiftable` `right_shiftable1` ] @@ -933,7 +925,7 @@ built-in types are not supported. [ `T temp(t); temp >>= t1`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -941,7 +933,7 @@ built-in types are not supported. [ [ - [#table:right_shiftable2]`right_shiftable` + [#utility.utilities.operators.arithmetic.smpl_oprs.right_shiftable2]`right_shiftable` `right_shiftable2` ] @@ -953,7 +945,7 @@ built-in types are not supported. [ `T temp(t); temp >>= u`. - Return convertible to `T`. See the [link sec:symmetry Symmetry Note]. + Return convertible to `T`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.symmetry Symmetry Note]. ] [No] @@ -961,7 +953,7 @@ built-in types are not supported. [ [ - [#table:equivalent1]`equivalent` + [#utility.utilities.operators.arithmetic.smpl_oprs.equivalent1]`equivalent` __equivalent1__`` ] @@ -973,7 +965,7 @@ built-in types are not supported. [ `t < t1`. - Return convertible to `bool`. See the [link sec:ordering Ordering Note]. + Return convertible to `bool`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.ordering Ordering Note]. ] [ @@ -983,7 +975,7 @@ built-in types are not supported. [ [ - [#table:equivalent2]`equivalent` + [#utility.utilities.operators.arithmetic.smpl_oprs.equivalent2]`equivalent` __equivalent2__`` ] @@ -995,7 +987,7 @@ built-in types are not supported. [ `t < u`. `t > u`. - Returns convertible to `bool`. See the [link sec:ordering Ordering Note]. + Returns convertible to `bool`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.ordering Ordering Note]. ] [ @@ -1005,7 +997,7 @@ built-in types are not supported. [ [ - [#table:partially_ordered1]`partially_ordered` + [#utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered1]`partially_ordered` __partially_ordered1__`` ] @@ -1021,7 +1013,7 @@ built-in types are not supported. [ `t < t1`. `t == t1`. - Returns convertible to `bool`. See the [link sec:ordering Ordering Note]. + Returns convertible to `bool`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.ordering Ordering Note]. ] [ @@ -1031,7 +1023,7 @@ built-in types are not supported. [ [ - [#table:partially_ordered2]`partially_ordered` + [#utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered2]`partially_ordered` __partially_ordered2__`` ] @@ -1053,7 +1045,7 @@ built-in types are not supported. [ `t < u`. `t > u`. `t == u`. - Returns convertible to `bool`. See the [link sec:ordering Ordering Note]. + Returns convertible to `bool`. See the [link utility.utilities.operators.arithmetic.smpl_oprs.ordering Ordering Note]. ] [ @@ -1062,24 +1054,24 @@ built-in types are not supported. ] ] -[#sec:ordering] -['Ordering Note]: The [link table:less_than_comparable1 `less_than_comparable`] and -[link table:partially_ordered1 `partially_ordered`] templates provide the same set -of operations. However, the workings of [link table:less_than_comparable1 `less_than_comparable`] assume +[#utility.utilities.operators.arithmetic.smpl_oprs.ordering] +['Ordering Note]: The [link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable1 `less_than_comparable`] and +[link utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered1 `partially_ordered`] templates provide the same set +of operations. However, the workings of [link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable1 `less_than_comparable`] assume that all values of type `T` can be placed in a total order. If that is not true (e.g. Not-a-Number values in IEEE floating point -arithmetic), then [link table:partially_ordered1 `partially_ordered`] should be -used. The [link table:partially_ordered1 `partially_ordered`] template can +arithmetic), then [link utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered1 `partially_ordered`] should be +used. The [link utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered1 `partially_ordered`] template can be used for a totally-ordered type, but it is not as efficient as -[link table:less_than_comparable1 `less_than_comparable`]. This -rule also applies for [link table:less_than_comparable2 `less_than_comparable`] and -[link table:partially_ordered2 `partially_ordered`] with respect to the ordering +[link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable1 `less_than_comparable`]. This +rule also applies for [link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable2 `less_than_comparable`] and +[link utility.utilities.operators.arithmetic.smpl_oprs.partially_ordered2 `partially_ordered`] with respect to the ordering of all `T` and `U` values, and for both versions of -[link table:equivalent1 `equivalent<>`]. The solution for -[link table:equivalent1 `equivalent<>`] is to write a custom +[link utility.utilities.operators.arithmetic.smpl_oprs.equivalent1 `equivalent<>`]. The solution for +[link utility.utilities.operators.arithmetic.smpl_oprs.equivalent1 `equivalent<>`] is to write a custom `operator==` for the target class. -[#sec:symmetry] +[#utility.utilities.operators.arithmetic.smpl_oprs.symmetry] ['Symmetry Note]: Before talking about symmetry, we need to talk about optimizations to understand the reasons for the different implementation styles of operators. Let's have a look at `operator+` for a class @@ -1163,15 +1155,16 @@ signature or a strict symmetric behaviour, you should set will force the NRVO-friendly implementation to be used even for compilers that do not implement the NRVO. -[#sec:grpd_oprs] -[h5 Grouped Arithmetic Operators] +[endsect] + +[section:grpd_oprs Grouped Arithmetic Operators] The following templates provide common groups of related operations. For example, since a type which is addable is usually also subtractable, -the [link table:additive1 `additive`] template provides the +the [link utility.utilities.operators.arithmetic.grpd_oprs.additive1 `additive`] template provides the combined operators of both. The grouped operator templates have an additional optional template parameter `B`, which is not -shown, for the [link sec:chaining base class chaining] technique. +shown, for the [link utility.utilities.operators.usage.chaining base class chaining] technique. [table Notation [[Key] [Description]] @@ -1187,364 +1180,364 @@ shown, for the [link sec:chaining base class chaining] technique. ] [ [ - [#table:totally_ordered1] `totally_ordered` + [#utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered1] `totally_ordered` __totally_ordered1__`` ] [ - [link table:less_than_comparable1 `less_than_comparable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable1 `less_than_comparable`] - [link table:equality_comparable1 `equality_comparable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.equality_comparable1 `equality_comparable`] ] ] [ [ - [#table:totally_ordered2]`totally_ordered` + [#utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered2]`totally_ordered` __totally_ordered2__`` ] [ - [link table:less_than_comparable2 `less_than_comparable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.less_than_comparable2 `less_than_comparable`] - [link table:equality_comparable2 `equality_comparable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.equality_comparable2 `equality_comparable`] ] ] [ [ - [#table:additive1]`additive` + [#utility.utilities.operators.arithmetic.grpd_oprs.additive1]`additive` __additive1__`` ] [ - [link table:addable1 `addable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.addable1 `addable`] - [link table:subtractable1 `subtractable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.subtractable1 `subtractable`] ] ] [ [ - [#table:additive2]`additive` + [#utility.utilities.operators.arithmetic.grpd_oprs.additive2]`additive` __additive2__`` ] [ - [link table:addable2 `addable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.addable2 `addable`] - [link table:subtractable2 `subtractable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.subtractable2 `subtractable`] ] ] [ [ - [#table:multiplicative1] `multiplicative` + [#utility.utilities.operators.arithmetic.grpd_oprs.multiplicative1] `multiplicative` __multiplicative1__`` ] [ - [link table:multipliable1 `multipliable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.multipliable1 `multipliable`] - [link table:dividable1 `dividable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable1 `dividable`] ] ] [ [ - [#table:multiplicative2]`multiplicative` + [#utility.utilities.operators.arithmetic.grpd_oprs.multiplicative2]`multiplicative` __multiplicative2__`` ] [ - [link table:multipliable2 `multipliable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.multipliable2 `multipliable`] - [link table:dividable2 `dividable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable2 `dividable`] ] ] [ [ - [#table:integer_multiplicative1] `integer_multiplicative` + [#utility.utilities.operators.arithmetic.grpd_oprs.integer_multiplicative1] `integer_multiplicative` __integer_multiplicative1__`` ] [ - [link table:multiplicative1 `multiplicative`] + [link utility.utilities.operators.arithmetic.grpd_oprs.multiplicative1 `multiplicative`] - [link table:modable1 `modable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.modable1 `modable`] ] ] [ [ - [#table:integer_multiplicative2] `integer_multiplicative` + [#utility.utilities.operators.arithmetic.grpd_oprs.integer_multiplicative2] `integer_multiplicative` __integer_multiplicative2__`` ] [ - [link table:multiplicative2 `multiplicative`] + [link utility.utilities.operators.arithmetic.grpd_oprs.multiplicative2 `multiplicative`] - [link table:modable2 `modable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.modable2 `modable`] ] ] [ [ - [#table:arithmetic1]`arithmetic` + [#utility.utilities.operators.arithmetic.grpd_oprs.arithmetic1]`arithmetic` __arithmetic1__`` ] [ - [link table:additive1 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive1 `additive`] - [link table:multiplicative1 `multiplicative`] + [link utility.utilities.operators.arithmetic.grpd_oprs.multiplicative1 `multiplicative`] ] ] [ [ - [#table:arithmetic2]`arithmetic` + [#utility.utilities.operators.arithmetic.grpd_oprs.arithmetic2]`arithmetic` __arithmetic2__`` ] [ - [link table:additive2 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive2 `additive`] - [link table:multiplicative2 `multiplicative`] + [link utility.utilities.operators.arithmetic.grpd_oprs.multiplicative2 `multiplicative`] ] ] [ [ - [#table:integer_arithmetic1] `integer_arithmetic` + [#utility.utilities.operators.arithmetic.grpd_oprs.integer_arithmetic1] `integer_arithmetic` __integer_arithmetic1__`` ] [ - [link table:additive1 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive1 `additive`] - [link table:integer_multiplicative1 `integer_multiplicative`] + [link utility.utilities.operators.arithmetic.grpd_oprs.integer_multiplicative1 `integer_multiplicative`] ] ] [ [ - [#table:integer_arithmetic2]`integer_arithmetic` + [#utility.utilities.operators.arithmetic.grpd_oprs.integer_arithmetic2]`integer_arithmetic` __integer_arithmetic2__`` ] [ - [link table:additive2 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive2 `additive`] - [link table:integer_multiplicative2 `integer_multiplicative`] + [link utility.utilities.operators.arithmetic.grpd_oprs.integer_multiplicative2 `integer_multiplicative`] ] ] [ [ - [#table:bitwise1]`bitwise` + [#utility.utilities.operators.arithmetic.grpd_oprs.bitwise1]`bitwise` __bitwise1__`` ] [ - [link table:xorable1 `xorable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.xorable1 `xorable`] - [link table:andable1 `andable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.andable1 `andable`] - [link table:orable1 `orable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.orable1 `orable`] ] ] [ [ - [#table:bitwise2]`bitwise` + [#utility.utilities.operators.arithmetic.grpd_oprs.bitwise2]`bitwise` __bitwise2__`` ] [ - [link table:xorable2 `xorable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.xorable2 `xorable`] - [link table:andable2 `andable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.andable2 `andable`] - [link table:orable2 `orable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.orable2 `orable`] ] ] [ [ - [#table:unit_steppable] `unit_steppable` + [#utility.utilities.operators.arithmetic.grpd_oprs.unit_steppable] `unit_steppable` ] [ - [link table:incrementable `incrementable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.incrementable `incrementable`] - [link table:decrementable `decrementable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.decrementable `decrementable`] ] ] [ [ - [#table:shiftable1]`shiftable` + [#utility.utilities.operators.arithmetic.grpd_oprs.shiftable1]`shiftable` __shiftable1__`` ] [ - [link table:left_shiftable1 `left_shiftable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.left_shiftable1 `left_shiftable`] - [link table:right_shiftable1 `right_shiftable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.right_shiftable1 `right_shiftable`] ] ] [ [ - [#table:shiftable2]`shiftable` + [#utility.utilities.operators.arithmetic.grpd_oprs.shiftable2]`shiftable` __shiftable2__`` ] [ - [link table:left_shiftable2 `left_shiftable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.left_shiftable2 `left_shiftable`] - [link table:right_shiftable2 `right_shiftable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.right_shiftable2 `right_shiftable`] ] ] [ [ - [#table:ring_operators1] `ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ring_operators1] `ring_operators` __ring_operators1__`` ] [ - [link table:additive1 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive1 `additive`] - [link table:multipliable1 `multipliable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.multipliable1 `multipliable`] ] ] [ [ - [#table:ring_operators2]`ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ring_operators2]`ring_operators` __ring_operators2__`` ] [ - [link table:additive2 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive2 `additive`] - [link table:subtractable2_left `subtractable2_left`] + [link utility.utilities.operators.arithmetic.smpl_oprs.subtractable2_left `subtractable2_left`] - [link table:multipliable2 `multipliable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.multipliable2 `multipliable`] ] ] [ [ - [#table:ordered_ring_operators1] `ordered_ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ordered_ring_operators1] `ordered_ring_operators` __ordered_ring_operators1__`` ] [ - [link table:ring_operators1 `ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.ring_operators1 `ring_operators`] - [link table:totally_ordered1 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered1 `totally_ordered`] ] ] [ [ - [#table:ordered_ring_operators2] `ordered_ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ordered_ring_operators2] `ordered_ring_operators` __ordered_ring_operators2__`` ] [ - [link table:ring_operators2 `ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.ring_operators2 `ring_operators`] - [link table:totally_ordered2 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered2 `totally_ordered`] ] ] [ [ - [#table:field_operators1]`field_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.field_operators1]`field_operators` __field_operators1__`` ] [ - [link table:ring_operators1 `ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.ring_operators1 `ring_operators`] - [link table:dividable1 `dividable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable1 `dividable`] ] ] [ [ - [#table:field_operators2]`field_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.field_operators2]`field_operators` __field_operators2__`` ] [ - [link table:ring_operators2 `ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.ring_operators2 `ring_operators`] - [link table:dividable2 `dividable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable2 `dividable`] - [link table:dividable2_left `dividable2_left`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable2_left `dividable2_left`] ] ] [ [ - [#table:ordered_field_operators1]`ordered_field_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ordered_field_operators1]`ordered_field_operators` __ordered_field_operators1__`` ] [ - [link table:field_operators1 `field_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.field_operators1 `field_operators`] - [link table:totally_ordered1 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered1 `totally_ordered`] ] ] [ [ - [#table:ordered_field_operators2]`ordered_field_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ordered_field_operators2]`ordered_field_operators` __ordered_field_operators2__`` ] [ - [link table:field_operators2 `field_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.field_operators2 `field_operators`] - [link table:totally_ordered2 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered2 `totally_ordered`] ] ] [ [ - [#table:euclidean_ring_operators1]`euclidean_ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.euclidean_ring_operators1]`euclidean_ring_operators` __euclidean_ring_operators1__`` ] [ - [link table:ring_operators1 `ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.ring_operators1 `ring_operators`] - [link table:dividable1 `dividable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable1 `dividable`] - [link table:modable1 `modable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.modable1 `modable`] ] ] [ [ - [#table:euclidean_ring_operators2] `euclidean_ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.euclidean_ring_operators2] `euclidean_ring_operators` __euclidean_ring_operators2__`` ] [ - [link table:ring_operators2 `ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.ring_operators2 `ring_operators`] - [link table:dividable2 `dividable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable2 `dividable`] - [link table:dividable2_left `dividable2_left`] + [link utility.utilities.operators.arithmetic.smpl_oprs.dividable2_left `dividable2_left`] - [link table:modable2 `modable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.modable2 `modable`] - [link table:modable2_left `modable2_left`] + [link utility.utilities.operators.arithmetic.smpl_oprs.modable2_left `modable2_left`] ] ] [ [ - [#table:ordered_euclidean_ring_operators1] `ordered_euclidean_ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ordered_euclidean_ring_operators1] `ordered_euclidean_ring_operators` __ordered_euclidean_ring_operators1__`` ] [ - [link table:euclidean_ring_operators1 `euclidean_ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.euclidean_ring_operators1 `euclidean_ring_operators`] - [link table:totally_ordered1 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered1 `totally_ordered`] ] ] [ [ - [#table:ordered_euclidean_ring_operators2]`ordered_euclidean_ring_operators` + [#utility.utilities.operators.arithmetic.grpd_oprs.ordered_euclidean_ring_operators2]`ordered_euclidean_ring_operators` __ordered_euclidean_ring_operators2__`` ] [ - [link table:euclidean_ring_operators2 `euclidean_ring_operators`] + [link utility.utilities.operators.arithmetic.grpd_oprs.euclidean_ring_operators2 `euclidean_ring_operators`] - [link table:totally_ordered2 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered2 `totally_ordered`] ] ] ] @@ -1554,13 +1547,14 @@ Boost.Operators library used "`euclidian`", but it was pointed out that "`euclidean`" is the more common spelling. To be compatible with older version, the library now supports both spellings. -[#sec:ex_oprs] -[h5 Example Templates] +[endsect] -The arithmetic operator class templates [link table:operators1 `operators<>`] and -[link table:operators2 `operators2<>`] are examples of non-extensible operator +[section:ex_oprs Example Templates] + +The arithmetic operator class templates [link utility.utilities.operators.arithmetic.ex_oprs.operators1 `operators<>`] and +[link utility.utilities.operators.arithmetic.ex_oprs.operators2 `operators2<>`] are examples of non-extensible operator grouping classes. These legacy class templates, from previous versions -of the header, cannot be used for [link sec:chaining base class chaining]. +of the header, cannot be used for [link utility.utilities.operators.usage.chaining base class chaining]. [table Notation [[Key] [Description]] @@ -1576,35 +1570,35 @@ of the header, cannot be used for [link sec:chaining base class chaining]. ] [ [ - [#table:operators1]__operators__`` + [#utility.utilities.operators.arithmetic.ex_oprs.operators1]__operators__`` ] [ - [link table:totally_ordered1 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered1 `totally_ordered`] - [link table:integer_arithmetic1 `integer_arithmetic`] + [link utility.utilities.operators.arithmetic.grpd_oprs.integer_arithmetic1 `integer_arithmetic`] - [link table:bitwise1 `bitwise`] + [link utility.utilities.operators.arithmetic.grpd_oprs.bitwise1 `bitwise`] - [link table:unit_steppable `unit_steppable`] + [link utility.utilities.operators.arithmetic.grpd_oprs.unit_steppable `unit_steppable`] ] ] [ [ - [#table:operators2]__operators__`` + [#utility.utilities.operators.arithmetic.ex_oprs.operators2]__operators__`` __operators2__`` ] [ - [link table:totally_ordered2 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered2 `totally_ordered`] - [link table:integer_arithmetic2 `integer_arithmetic`] + [link utility.utilities.operators.arithmetic.grpd_oprs.integer_arithmetic2 `integer_arithmetic`] - [link table:bitwise2 `bitwise`] + [link utility.utilities.operators.arithmetic.grpd_oprs.bitwise2 `bitwise`] ] ] ] -[#sec:a_demo] +[#utility.utilities.operators.arithmetic.grpd_oprs.a_demo] ['Arithmetic Operators Demonstration and Test Program]: The [@../../../test/operators_test.cpp `operators_test.cpp`] program demonstrates the use of the arithmetic operator templates, and @@ -1613,16 +1607,17 @@ report for the test results with selected platforms. [endsect] -[#sec:deref] -[section Dereference Operators and Iterator Helpers] +[endsect] -The [link sec:iterator iterator helper] templates ease the task of +[section:deref Dereference Operators and Iterator Helpers] + +The [link utility.utilities.operators.deref.iterator iterator helper] templates ease the task of creating a custom iterator. Similar to arithmetic types, a complete iterator has many operators that are "redundant" and can be implemented in terms of the core set of operators. -The [link sec:dereference dereference operators] were motivated by -the [link sec:iterator iterator helpers], but are often useful in +The [link utility.utilities.operators.deref.dereference dereference operators] were motivated by +the [link utility.utilities.operators.deref.iterator iterator helpers], but are often useful in non-iterator contexts as well. Many of the redundant iterator operators are also arithmetic operators, so the iterator helper classes borrow many of the operators defined above. In fact, only two new operators need to @@ -1635,12 +1630,11 @@ their return type. The composite operator templates list their component templates, which the instantiating type must support, and possibly other requirements. -[#sec:dereference] -[h5 Dereference Operators] +[section:dereference Dereference Operators] All the dereference operator templates in this table accept an optional template parameter (not shown) to be used for -[link sec:chaining base class chaining]. +[link utility.utilities.operators.usage.chaining base class chaining]. [table Notation [[Key] [Description]] @@ -1662,7 +1656,7 @@ optional template parameter (not shown) to be used for ] [ [ - [#table:dereferenceable]__dereferenceable__`` + [#utility.utilities.operators.deref.dereference.dereferenceable]__dereferenceable__`` ] [ `P operator->() const` @@ -1673,7 +1667,7 @@ optional template parameter (not shown) to be used for ] [ [ - [#table:indexable]__indexable__`` + [#utility.utilities.operators.deref.dereference.indexable]__indexable__`` ] [ `R operator[](D n) const` @@ -1684,14 +1678,15 @@ optional template parameter (not shown) to be used for ] ] -[#sec:grpd_iter_oprs] -[h5 Grouped Iterator Operators] +[endsect] + +[section:grpd_iter_oprs Grouped Iterator Operators] There are five iterator operator class templates, each for a different category of iterator. The following table shows the operator groups for any category that a custom iterator could define. These class templates have an additional optional template parameter `B`, which is -not shown, to support [link sec:chaining base class chaining]. +not shown, to support [link utility.utilities.operators.usage.chaining base class chaining]. [table Notation [[Key] [Description]] @@ -1710,66 +1705,67 @@ not shown, to support [link sec:chaining base class chaining]. ] [ [ - [#table:input_iteratable]__input_iteratable__`` + [#utility.utilities.operators.deref.grpd_iter_oprs.input_iteratable]__input_iteratable__`` ] [ - [link table:equality_comparable1 `equality_comparable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.equality_comparable1 `equality_comparable`] - [link table:incrementable `incrementable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.incrementable `incrementable`] - [link table:dereferenceable `dereferenceable`] + [link utility.utilities.operators.deref.dereference.dereferenceable `dereferenceable`] ] ] [ [ - [#table:output_iteratable]__output_iteratable__`` + [#utility.utilities.operators.deref.grpd_iter_oprs.output_iteratable]__output_iteratable__`` ] [ - [link table:incrementable `incrementable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.incrementable `incrementable`] ] ] [ [ - [#table:forward_iteratable]__forward_iteratable__`` + [#utility.utilities.operators.deref.grpd_iter_oprs.forward_iteratable]__forward_iteratable__`` ] [ - [link table:input_iteratable `input_iteratable`] + [link utility.utilities.operators.deref.grpd_iter_oprs.input_iteratable `input_iteratable`] ] ] [ [ - [#table:bidirectional_iteratable] __bidirectional_iteratable__`` + [#utility.utilities.operators.deref.grpd_iter_oprs.bidirectional_iteratable] __bidirectional_iteratable__`` ] [ - [link table:forward_iteratable `forward_iteratable`] + [link utility.utilities.operators.deref.grpd_iter_oprs.forward_iteratable `forward_iteratable`] - [link table:decrementable `decrementable`] + [link utility.utilities.operators.arithmetic.smpl_oprs.decrementable `decrementable`] ] ] [ [ - [#table:random_access_iteratable] __random_access_iteratable__`` + [#utility.utilities.operators.deref.grpd_iter_oprs.random_access_iteratable] __random_access_iteratable__`` ] [ - [link table:bidirectional_iteratable `bidirectional_iteratable`] + [link utility.utilities.operators.deref.grpd_iter_oprs.bidirectional_iteratable `bidirectional_iteratable`] - [link table:totally_ordered1 `totally_ordered`] + [link utility.utilities.operators.arithmetic.grpd_oprs.totally_ordered1 `totally_ordered`] - [link table:additive2 `additive`] + [link utility.utilities.operators.arithmetic.grpd_oprs.additive2 `additive`] - [link table:indexable `indexable`] + [link utility.utilities.operators.deref.dereference.indexable `indexable`] ] ] ] -[#sec:iterator] -[h5 Iterator Helpers] +[endsect] + +[section:iterator Iterator Helpers] There are also five iterator helper class templates, each corresponding to a different iterator category. These classes cannot be -used for [link sec:chaining base class chaining]. The following +used for [link utility.utilities.operators.usage.chaining base class chaining]. The following summaries show that these class templates supply both the iterator -operators from the [link sec:grpd_iter_oprs iterator operator class +operators from the [link utility.utilities.operators.deref.grpd_iter_oprs iterator operator class templates] and the iterator `typedef`s required by the C++ standard, such as `iterator_category` and `value_type`. @@ -1791,52 +1787,51 @@ such as `iterator_category` and `value_type`. ] [ [ - [#table:input_iterator_helper]__input_iterator_helper__`` + [#utility.utilities.operators.deref.iterator.input_iterator_helper]__input_iterator_helper__`` ] [ - Supports the operations and has the requirements of [link table:input_iteratable `input_iteratable`] + Supports the operations and has the requirements of [link utility.utilities.operators.deref.grpd_iter_oprs.input_iteratable `input_iteratable`] ] ] [ [ - [#table:output_iterator_helper]__output_iterator_helper__`` + [#utility.utilities.operators.deref.iterator.output_iterator_helper]__output_iterator_helper__`` ] [ - Supports the operations and has the requirements of [link table:output_iteratable `output_iteratable`] + Supports the operations and has the requirements of [link utility.utilities.operators.deref.grpd_iter_oprs.output_iteratable `output_iteratable`] See also \[[link note:1 1]\], \[[link note:2 2]\]. ] ] [ [ - [#table:forward_iterator_helper] __forward_iterator_helper__`` + [#utility.utilities.operators.deref.iterator.forward_iterator_helper] __forward_iterator_helper__`` ] [ - Supports the operations and has the requirements of [link table:forward_iteratable `forward_iteratable`] + Supports the operations and has the requirements of [link utility.utilities.operators.deref.grpd_iter_oprs.forward_iteratable `forward_iteratable`] ] ] [ [ - [#table:bidirectional_iterator_helper] __bidirectional_iterator_helper__`` + [#utility.utilities.operators.deref.iterator.bidirectional_iterator_helper] __bidirectional_iterator_helper__`` ] [ - Supports the operations and has the requirements of [link table:bidirectional_iteratable `bidirectional_iteratable`] + Supports the operations and has the requirements of [link utility.utilities.operators.deref.grpd_iter_oprs.bidirectional_iteratable `bidirectional_iteratable`] ] ] [ [ - [#table:random_access_iterator_helper]__random_access_iterator_helper__`` + [#utility.utilities.operators.deref.iterator.random_access_iterator_helper]__random_access_iterator_helper__`` ] [ - Supports the operations and has the requirements of [link table:random_access_iteratable `random_access_iteratable`] + Supports the operations and has the requirements of [link utility.utilities.operators.deref.grpd_iter_oprs.random_access_iteratable `random_access_iteratable`] To satisfy __RandomAccessIterator__, `x1 - x2` with return convertible to `D` is also required. ] ] ] -[#sec:iterator_helpers_notes] - +[#utility.utilities.operators.deref.iterator.iterator_helpers_notes] ['Iterator Helper Notes]: # [#note:1] Unlike other iterator helpers templates, __output_iterator_helper__ takes only one template parameter - @@ -1880,8 +1875,9 @@ definition of `operator*` or/and `operator++`, then these operators will get used and the ones supplied by __output_iterator_helper__ will never be instantiated. -[#sec:i_demo] -[h5 Iterator Demonstration and Test Program] +[endsect] + +[section:i_demo Iterator Demonstration and Test Program] The [@../../../test/iterators_test.cpp `iterators_test.cpp`] program demonstrates the use of the iterator templates, and can also be @@ -1922,23 +1918,24 @@ test results with selected platforms. [endsect] -[#sec:old_lib_note] -[section Note for Users of Older Versions] +[endsect] -The [link sec:chaining changes in the library interface and +[section:old_lib_note Note for Users of Older Versions] + +The [link utility.utilities.operators.usage.chaining changes in the library interface and recommended usage] were motivated by some practical issues described below. The new version of the library is still backward-compatible with the former one, so you are not ['forced] to change any existing code, but the old usage is deprecated. Though it was arguably simpler and more intuitive than using -[link sec:chaining base class chaining], it has been discovered +[link utility.utilities.operators.usage.chaining base class chaining], it has been discovered that the old practice of deriving from multiple operator templates can cause the resulting classes to be much larger than they should be. Most modern C++ compilers significantly bloat the size of classes derived from multiple empty base classes, even though the base classes themselves have no state. For instance, the size of -`point` from the [link sec:example example] +`point` from the [link utility.utilities.operators.example example] above was 12-24 bytes on various compilers for the Win32 platform, instead of the expected 8 bytes. @@ -1972,20 +1969,19 @@ library to remain backward-compatible. [endsect] -[#sec:contributors] -[section Acknowledgments] +[section:contributors Acknowledgments] * [@http://www.boost.org/people/dave_abrahams.htm Dave Abrahams]: Started the library and contributed the arithmetic operators in [@../../../../boost/operators.hpp `boost/operators.hpp`]. * [@http://www.boost.org/people/jeremy_siek.htm Jeremy Siek]: - Contributed the [link sec:deref dereference operators and iterator + Contributed the [link utility.utilities.operators.deref dereference operators and iterator helpers] in [@../../../../boost/operators.hpp boost/operators.hpp]. Also contributed [@../../../test/iterators_test.cpp iterators_test.cpp]. * [@http://www.boost.org/people/aleksey_gurtovoy.htm Aleksey Gurtovoy]: - Contributed the code to support [link sec:chaining base class + Contributed the code to support [link utility.utilities.operators.usage.chaining base class chaining] while remaining backward-compatible with old versions of the library. diff --git a/doc/other.qbk b/doc/other.qbk index 239e682..66ff002 100644 --- a/doc/other.qbk +++ b/doc/other.qbk @@ -7,7 +7,7 @@ Official repository: https://github.com/boostorg/utility ] -[section:utilities More Utilities] +[section:more_utilities More Utilities] Some utilities have been moved from Boost.Utilities to more appropriate Boost libraries: diff --git a/doc/overview.qbk b/doc/overview.qbk index f790fb0..6259b73 100644 --- a/doc/overview.qbk +++ b/doc/overview.qbk @@ -20,14 +20,14 @@ Over time, When the component has moved to another Boost library, Boost.Utility headers still lead to the appropriate headers in other libraries. -[table:id Components +[table Components [[Boost.Utility] [Moved to Boost] [C++ Standard variant]] [[[@boost:/libs/core/doc/html/core/addressof.html `addressof`]] [[@boost:/libs/core/index.html Boost.Core]] [C++11 __std_addressof__]] - [[__base_from_member__] [] []] + [[[link utility.utilities.base_from_member `base_from_member`]] [] []] [[__BOOST_BINARY__] [] [C++14 [@https://en.cppreference.com/w/cpp/language/integer_literal Binary integer literal]]] - [[__call_traits__] [] []] + [[[link utility.utilities.call_traits `call_traits`]] [] []] [[[@boost:/libs/core/doc/html/core/checked_delete.html `checked_delete`]] [[@boost:/libs/core/index.html Boost.Core]] []] - [[__compressed_pair__] [] []] + [[[link utility.utilities.compressed_pair `compressed_pair`]] [] []] [[[@boost:/libs/type_traits/doc/html/boost_typetraits/reference/declval.html `declval`]] [[@boost:/libs/type_traits/index.html Boost.TypeTraits]] [C++11 __std_declval__]] [[[@boost:/libs/core/doc/html/core/enable_if.html `enable_if`]] [[@boost:/libs/core/index.html Boost.Core]] [C++11 __std_enable_if__]] [[[@boost:/libs/iterator/doc/generator_iterator.htm generator iterator adaptors]] [[@boost:/libs/iterator/index.html Boost.Iterator]] []] @@ -35,12 +35,12 @@ in other libraries. [[[@boost:/libs/iterator/index.html `iterator_adaptors`]] [[@boost:/libs/iterator/index.html Boost.Iterator]] []] [[[@boost:/libs/iterator/doc/html/iterator/algorithms/next_prior.html `next` / `prior`]] [[@boost:/libs/iterator/index.html Boost.Iterator]] [C++11 __std_next__ / __std_prev__]] [[[@boost:/libs/core/doc/html/core/noncopyable.html `noncopyable`]] [[@boost:/libs/core/index.html Boost.Core]] []] - [[[link sec:operators `operators`]] [] []] + [[[link utility.utilities.operators `operators`]] [] []] [[[@boost:/libs/io/doc/html/io.html `ostream_string`]] [[@boost:/libs/io/index.html Boost.IO]] []] - [[__result_of__] [] [C++11 __std_result_of__]] - [[__string_view__] [] [C++17 __std_string_view__]] + [[[link utility.utilities.result_of `result_of`]] [] [C++11 __std_result_of__]] + [[[link utility.utilities.string_view `string_view`]] [] [C++17 __std_string_view__]] [[[@boost:/libs/throw_exception/doc/html/throw_exception.html#using_boost_throw_exception `throw_exception`]] [[@boost:/libs/throw_exception/index.html Boost.ThrowException]] []] - [[[link sec:value_init `value_init`]] [] [C++11 [@https://en.cppreference.com/w/cpp/language/list_initialization List initialization]]] + [[[link utility.utilities.value_init `value_init`]] [] [C++11 [@https://en.cppreference.com/w/cpp/language/list_initialization List initialization]]] ] [endsect] diff --git a/doc/quickref.xml b/doc/quickref.xml index 953421f..dd2c31b 100644 --- a/doc/quickref.xml +++ b/doc/quickref.xml @@ -43,7 +43,7 @@ Classes - base_from_member + base_from_member @@ -53,19 +53,16 @@ Type Traits - call_traits + call_traits - call_traits<T&> + call_traits<T&> - call_traits<T[N]> - + call_traits<T[N]> - call_traits<const - T[N]> - + call_traits<const T[N]> @@ -75,14 +72,14 @@ Classes - compressed_pair + compressed_pair Functions - swap + swap @@ -92,11 +89,10 @@ Classes - in_place_factory_base + in_place_factory_base - typed_in_place_factory_base - + typed_in_place_factory_base @@ -126,45 +122,45 @@ Classes (1 of 5) - additive1 + additive1 - additive2 + additive2 - arithmetic1 + arithmetic1 - arithmetic2 + arithmetic2 - bidirectional_iteratable + bidirectional_iteratable - + bidirectional_iterator_helper - bitwise1 + bitwise1 - bitwise2 + bitwise2 - decrementable + decrementable - dereferenceable + dereferenceable - equality_comparable1 + equality_comparable1 - equality_comparable2 + equality_comparable2 - equivalent1 + equivalent1 @@ -173,45 +169,45 @@ Classes (2 of 5) - equivalent2 + equivalent2 - euclidean_ring_operators1 + euclidean_ring_operators1 - euclidean_ring_operators2 + euclidean_ring_operators2 - field_operators1 + field_operators1 - field_operators2 + field_operators2 - forward_iteratable + forward_iteratable - forward_iterator_helper + forward_iterator_helper - incrementable + incrementable - indexable + indexable - input_iteratable + input_iteratable - input_iterator_helper + input_iterator_helper - integer_arithmetic1 + integer_arithmetic1 - integer_arithmetic2 + integer_arithmetic2 @@ -220,49 +216,47 @@ Classes (3 of 5) - integer_multiplicative1 + integer_multiplicative1 - integer_multiplicative2 + integer_multiplicative2 - is_chained_base + less_than_comparable1 - less_than_comparable1 + less_than_comparable2 - less_than_comparable2 + multiplicative1 - multiplicative1 + multiplicative2 - multiplicative2 + operators1 - operators + operators2 - operators2 + operators<T,T> - operators<T,T> - - - + ordered_euclidean_ring_operators1 - + ordered_euclidean_ring_operators2 - - ordered_euclidian_ring_operators1 - + ordered_field_operators1 + + + ordered_field_operators2 @@ -271,47 +265,45 @@ Classes (4 of 5) - - ordered_euclidian_ring_operators2 - + ordered_ring_operators1 - ordered_field_operators1 + ordered_ring_operators2 - ordered_field_operators2 + output_iteratable - ordered_ring_operators1 + output_iterator_helper - ordered_ring_operators2 + partially_ordered1 - output_iteratable + partially_ordered2 - output_iterator_helper + random_access_iteratable - partially_ordered1 - - - partially_ordered2 - - - random_access_iteratable - - - + random_access_iterator_helper - ring_operators1 + ring_operators1 - ring_operators2 + ring_operators2 + + + shiftable1 + + + shiftable2 + + + totally_ordered1 @@ -320,25 +312,10 @@ Classes (5 of 5) - shiftable1 + totally_ordered2 - shiftable2 - - - totally_ordered1 - - - totally_ordered2 - - - unit_steppable - - - Type Traits - - - is_chained_base + unit_steppable @@ -374,10 +351,10 @@ Type Traits - result_of + result_of - tr1_result_of + tr1_result_of @@ -387,28 +364,28 @@ Aliases - string_view + string_view - u16string_ref + u16string_ref - u16string_view + u16string_view - u32string_ref + u32string_ref - u32string_view + u32string_view - wstring_ref + wstring_ref - wstring_view + wstring_view - string_ref + string_ref @@ -417,19 +394,19 @@ Classes - basic_string_ref + basic_string_ref - basic_string_view + basic_string_view Functions - hash_range + hash_range - hash_value + hash_value @@ -438,58 +415,58 @@ Operators - operator== + operator== - operator!= + operator!= - operator< + operator< - operator<= + operator<= - operator> + operator> - operator>= + operator>= - operator<< + operator<< - Classes - - - initialized - - - initialized_value_t - - - value_initialized - - - Functions - - - get - - - swap - - - Constants - - - initialized_value - - + Classes + + + initialized + + + initialized_value_t + + + value_initialized + + + Functions + + + get + + + swap + + + Constants + + + initialized_value + + diff --git a/doc/result_of.qbk b/doc/result_of.qbk index 4542c58..4147e13 100644 --- a/doc/result_of.qbk +++ b/doc/result_of.qbk @@ -7,7 +7,7 @@ /] [/===============] -[section Result of] +[section:result_of Result of] [/===============] [section Introduction] @@ -122,7 +122,7 @@ and is not implemented by some compilers. the actual result type deduced by __decltype__, then using TR1 with a __decltype__ fallback will allow you to work with both your existing TR1 function objects and new C++11 function object. This situation could occur if your legacy function objects -misused the TR1 protocol. See the documentation on known [link sec:result_of_tr1_diff differences] +misused the TR1 protocol. See the documentation on known [link utility.utilities.result_of.result_of_tr1_diff differences] between __boost_result_of__ and TR1. * [#BOOST_NO_RESULT_OF] This implementation of __result_of__ requires class template @@ -138,8 +138,7 @@ or, for motivation and design rationale, the __result_of__ [endsect] -[#sec:result_of_guidelines] -[section Usage guidelines for __boost_result_of__] +[section:result_of_guidelines Usage guidelines for __boost_result_of__] The following are general suggestions about when and how to use __boost_result_of__. @@ -151,7 +150,7 @@ there's no reason to stop using it. # If you are targeting C++11 but may port your code to legacy compilers at some time in the future, then use __boost_result_of__ with __decltype__. When __decltype__ is used __boost_result_of__ and `__std_result_of__` are usually -interchangeable. See the documentation on known [link sec:result_of_cxx11_diff differences] +interchangeable. See the documentation on known [link utility.utilities.result_of.result_of_cxx11_diff differences] between __boost_result_of__ and C++11 __std_result_of__. # If compiler portability is required, use __boost_result_of__ with the TR1 protocol @@ -195,8 +194,7 @@ typedef __boost_result_of__< [endsect] -[#sec:result_of_tr1_protocol_guidelines] -[section Usage guidelines for the TR1 result_of protocol] +[section:result_of_tr1_protocol_guidelines Usage guidelines for the TR1 result_of protocol] On compliant C++11 compilers, __boost_result_of__ can use __decltype__ to deduce the type of any @@ -212,7 +210,7 @@ argument types or the cv-qualification of the function object, simply define `result_type`. There is no need to use the `result` template unless the -return type varies. +return type varies. * Use the protocol specified type when defining function prototypes. This can help ensure the @@ -274,8 +272,7 @@ struct functor { [endsect] -[#sec:result_of_tr1_diff] -[section Known differences between __boost_result_of__ and __boost_tr1_result_of__] +[section:result_of_tr1_diff Known differences between __boost_result_of__ and __boost_tr1_result_of__] When using __decltype__, __boost_result_of__ ignores the TR1 protocol and instead deduces the return type of function objects directly via __decltype__. In most situations, users @@ -399,8 +396,7 @@ BOOST_STATIC_ASSERT(( [endsect] -[#sec:result_of_cxx11_diff] -[section Known differences between __boost_result_of__ and C++11 result_of] +[section:result_of_cxx11_diff Known differences between __boost_result_of__ and C++11 result_of] When using __decltype__, __boost_result_of__ implements most of the C++11 __std_result_of__ specification. One known exception is that __boost_result_of__ does not implement the diff --git a/doc/string_view.qbk b/doc/string_view.qbk index be79a98..e5035bb 100644 --- a/doc/string_view.qbk +++ b/doc/string_view.qbk @@ -7,7 +7,7 @@ /] [/===============] -[section String View] +[section:string_view String View] [/===============] [section Introduction] diff --git a/doc/value_init.qbk b/doc/value_init.qbk index 8586850..7a07418 100644 --- a/doc/value_init.qbk +++ b/doc/value_init.qbk @@ -7,9 +7,7 @@ /] [/===============] -[#sec:value_init] -[section Value Init] - +[section:value_init Value Init] [/===============] [section Introduction] @@ -61,7 +59,7 @@ the syntax did not allow for a class that has an explicitly declared constructor The fourth form is the most generic form of them, as it can be used to initialize arithmetic types, class types, aggregates, pointers, and other types. The declaration, `T4 var4 = T4()`, should be read as follows: First a temporary -object is created, by `T4()`. This object is [link sec:valueinit value-initialized]. +object is created, by `T4()`. This object is [link utility.utilities.value_init.details.value_initialization value-initialized]. Next the temporary object is copied to the named variable, `var4`. Afterwards, the temporary is destroyed. While the copying and the destruction are likely to be optimized away, C++ still requires the type `T4` to be __CopyConstructible__. @@ -69,11 +67,11 @@ So `T4` needs to be ['both] __DefaultConstructible__ ['and] __CopyConstructible_ A class may not be CopyConstructible, for example because it may have a private and undefined copy constructor, or because it may be derived from -`boost::noncopyable`. Scott Meyers \[[link sec:references 2]\] explains why a +`boost::noncopyable`. Scott Meyers \[[link utility.utilities.value_init.references 2]\] explains why a class would be defined like that. There is another, less obvious disadvantage to the fourth form, `T4 var4 = T4()`: -It suffers from various [link sec:compiler_issues compiler issues], causing +It suffers from various [link utility.utilities.value_init.details.compiler_issues compiler issues], causing a variable to be left uninitialized in some compiler specific cases. The template __value_initialized__ offers a generic way to initialize @@ -103,13 +101,12 @@ but robust against the aforementioned compiler issues. [endsect] -[#sec:details] -[section Details] +[section:details Details] -The C++ standard \[[link sec:references 3]\] contains the definitions +The C++ standard \[[link utility.utilities.value_init.references 3]\] contains the definitions of `zero-initialization` and `default-initialization`. Informally, zero-initialization means that the object is given the initial value `0` converted to the type and -default-initialization means that [@https://en.cppreference.com/w/cpp/named_req/PODType POD] \[[link sec:references 4]\] types are zero-initialized, +default-initialization means that [@https://en.cppreference.com/w/cpp/named_req/PODType POD] \[[link utility.utilities.value_init.references 4]\] types are zero-initialized, while non-POD class types are initialized with their corresponding default constructors. A ['declaration] can contain an ['initializer], which specifies the @@ -136,8 +133,7 @@ foo ( __std_string__() ) ; // as indicated by the initializer () ``` -[#sec:valueinit] -[h5 value-initialization] +[section:value_initialization value-initialization] The first [@http://www.open-std.org/JTC1/SC22/WG21/docs/cwg_defects.html Technical Corrigendum for the C++ Standard] (TC1), whose draft was released to the public in @@ -173,8 +169,9 @@ eat ( int() ) ; // value-initialized eat ( __std_string__() ) ; // value-initialized ``` -[#sec:valueinitsyn] -[h5 value-initialization syntax] +[endsect] + +[section:syntax value-initialization syntax] Value initialization is specified using `()`. However, the empty set of parentheses is not permitted by the syntax of initializers because it is @@ -224,8 +221,9 @@ This is the solution as it was supplied by earlier versions of the `__value_initialized__` template class. Unfortunately this approach suffered from various compiler issues. -[#sec:compiler_issues] -[h5 Compiler issues] +[endsect] + +[section:compiler_issues Compiler issues] Various compilers have not yet fully implemented value-initialization. So when an object should be ['value-initialized] according to the C++ Standard, @@ -242,8 +240,6 @@ go wrong on various compilers. At the moment of writing, May 2010, the following reported issues regarding value-initialization are still there in current compiler releases: - - * [@https://connect.microsoft.com/VisualStudio/feedback/details/100744 Microsoft Visual Studio Feedback ID 100744, Value-initialization in new-expression]: Reported by Pavel Kuznetsov (MetaCommunications Engineering), 2005. * [@http://connect.microsoft.com/VisualStudio/feedback/details/484295 Microsoft Visual Studio Feedback ID 484295, VC++ does not value-initialize members of derived classes without user-declared constructor] Reported by Sylvester Hesp, 2009. * [@https://connect.microsoft.com/VisualStudio/feedback/details/499606 Microsoft Visual Studio Feedback ID 499606, Presence of copy constructor breaks member class initialization] Reported by Alex Vakulenko, 2009 @@ -267,11 +263,11 @@ compiler defect macro] `BOOST_NO_COMPLETE_VALUE_INITIALIZATION`. [endsect] -[#sec:types] -[section Types and objects] +[endsect] -[#sec:val_init] -[section `template class value_initialized`] +[section:types Types and objects] + +[section:val_init `template class value_initialized`] ``` namespace boost { @@ -323,7 +319,7 @@ void swap ( __value_initialized__& lhs, __value_initialized__& rhs ) ``` An object of this template class is a `T`-wrapper convertible to `'T&'` whose -wrapped object (data member of type `T`) is [link sec:valueinit value-initialized] upon default-initialization +wrapped object (data member of type `T`) is [link utility.utilities.value_init.details.value_initialization value-initialized] upon default-initialization of this wrapper class: ``` @@ -338,7 +334,7 @@ assert( y == def ) ; The purpose of this wrapper is to provide a consistent syntax for value initialization of scalar, union and class types (POD and non-POD) since the correct syntax for value -initialization varies (see [link sec:valueinitsyn value-initialization syntax]). +initialization varies (see [link utility.utilities.value_init.details.syntax value-initialization syntax]). The wrapped object can be accessed either through the conversion operator `T&`, the member function `data()`, or the non-member function `get()`: @@ -404,7 +400,7 @@ supports the idea of logical constness. ] -[h5 Recommended practice: The non-member get() idiom] +[section Recommended practice: The non-member get() idiom] The obscure behavior of being able to modify a non-`const` wrapped object from within a constant wrapper (as was supported by previous @@ -426,8 +422,9 @@ get(cx_c) = 1; // ERROR: Cannot modify a const object [endsect] -[#sec:initialized] -[section `template class initialized`] +[endsect] + +[section:initialized `template class initialized`] ``` @@ -491,8 +488,7 @@ direct-initialized, none of the two wrappers really needs to be used. [endsect] -[#sec:initialized_value] -[section `initialized_value`] +[section:initialized_value `initialized_value`] ``` namespace boost { @@ -538,8 +534,7 @@ T var = __initialized_value__; [endsect] [endsect] -[#sec:references] -[section References] +[section:references References] # Bjarne Stroustrup, Gabriel Dos Reis, and J. Stephen Adamczyk wrote various papers, proposing to extend the support for brace-enclosed ['initializer lists] @@ -561,8 +556,7 @@ compiler-generated functions you do not want], [@http://www.aristeia.com/books.h [xinclude tmp/value_init_reference.xml] [/===============] -[#sec:acknowledgements] -[section Acknowledgements] +[section:acknowledgements Acknowledgements] __value_initialized__ was developed by Fernando Cacciola, with help and suggestions from David Abrahams and Darin Adler.