From a6aaec46f5edb1ddeaf67e048b91bfedd135b543 Mon Sep 17 00:00:00 2001 From: Glen Fernandes Date: Mon, 25 Mar 2019 09:32:54 -0400 Subject: [PATCH] Minor formatting changes in documentation --- doc/endian/arithmetic.adoc | 31 ++++++++---- doc/endian/buffers.adoc | 29 +++++++++--- doc/endian/conversion.adoc | 60 +++++++++++++++++------- doc/endian/mini_review_topics.adoc | 75 +++++++----------------------- 4 files changed, 105 insertions(+), 90 deletions(-) diff --git a/doc/endian/arithmetic.adoc b/doc/endian/arithmetic.adoc index 68e9096..65769f0 100644 --- a/doc/endian/arithmetic.adoc +++ b/doc/endian/arithmetic.adoc @@ -378,34 +378,44 @@ to the endianness of the platform. ``` endian() = default; // C++03: endian(){} ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an uninitialized object of type `endian_arithmetic`. ``` endian(T v); ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an object of type `endian_arithmetic`. Postcondition:: `x == v,` where `x` is the constructed object. ``` endian& operator=(T v); ``` -[horizontal] +[none] +* {blank} ++ Postcondition:: `x == v,` where `x` is the constructed object. Returns:: `*this`. ``` operator T() const; ``` -[horizontal] +[none] +* {blank} ++ Returns:: The current value stored in `*this`, converted to `value_type`. ``` const char* data() const; ``` -[horizontal] +[none] +* {blank} ++ Returns:: A pointer to the first byte of the endian binary value stored in `*this`. @@ -422,8 +432,11 @@ friend std::basic_ostream& operator<<(std::basic_ostream& os, const T& x); ``` -[horizontal] -Returns:: `os << +x`.

+[none] +* {blank} ++ +Returns:: `os << +x`. +[none] ### Stream extractor @@ -432,7 +445,9 @@ template friend std::basic_istream& operator>>(std::basic_istream& is, T& x); ``` -[horizontal] +[none] +* {blank} ++ Effects:: As if: + ``` diff --git a/doc/endian/buffers.adoc b/doc/endian/buffers.adoc index cd85669..df67699 100644 --- a/doc/endian/buffers.adoc +++ b/doc/endian/buffers.adoc @@ -364,14 +364,18 @@ Template parameter `T` is required to be a standard integer type ({cpp}std, ``` endian_buffer() noexcept = default; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an uninitialized object of type `endian_buffer`. ``` explicit endian_buffer(T v) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: Constructs an object of type `endian_buffer`. Postcondition:: `value() == v & mask`, where `mask` is a constant of type `value_type` with `Nbits` low-order bits set to one. @@ -381,7 +385,9 @@ is performed by `boost::endian::endian_reverse`. ``` endian_buffer& operator=(T v) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Postcondition:: `value() == v & mask`, where `mask` is a constant of type `value_type` with `Nbits` low-order bits set to one. Returns:: `*this`. @@ -391,7 +397,9 @@ performed by `boost::endian::endian_reverse`. ``` value_type value() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `endian_value`, converted to `value_type`, if required, and having the endianness of the native platform. Remarks:: If `Align` is `align::yes` then endianness conversion, if required, is @@ -400,8 +408,11 @@ performed by `boost::endian::endian_reverse`. ``` const char* data() const noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: A pointer to the first byte of `endian_value`. +[none] ### Non-member functions @@ -411,7 +422,9 @@ template & operator<<(std::basic_ostream& os, const endian_buffer& x); ``` -[horizontal] +[none] +* {blank} ++ Returns:: `os << x.value()`. ``` @@ -420,7 +433,9 @@ template & operator>>(std::basic_istream& is, endian_buffer& x); ``` -[horizontal] +[none] +* {blank} ++ Effects:: As if: + ``` diff --git a/doc/endian/conversion.adoc b/doc/endian/conversion.adoc index 30a955a..b3348c1 100644 --- a/doc/endian/conversion.adoc +++ b/doc/endian/conversion.adoc @@ -193,10 +193,12 @@ uint16_t endian_reverse(uint16_t x) noexcept; uint32_t endian_reverse(uint32_t x) noexcept; uint64_t endian_reverse(uint64_t x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `x`, with the order of its constituent bytes reversed. Remarks:: The type of `x` meets the `EndianReversible` requirements. - ++ NOTE: The Boost.Endian library does not provide overloads for the {cpp} standard library supplied types. @@ -204,88 +206,111 @@ library supplied types. template EndianReversible big_to_native(EndianReversible x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `conditional_reverse(x)`. ``` template EndianReversible native_to_big(EndianReversible x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `conditional_reverse(x)`. ``` template EndianReversible little_to_native(EndianReversible x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `conditional_reverse(x)`. ``` template EndianReversible native_to_little(EndianReversible x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `conditional_reverse(x)`. ``` template EndianReversible conditional_reverse(EndianReversible x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `x` if `O1 == O2,` otherwise `endian_reverse(x)`. Remarks:: Whether `x` or `endian_reverse(x)` is to be returned shall be determined at compile time. - ``` template EndianReversible conditional_reverse(EndianReversible x, order order1, order order2) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Returns:: `order1 == order2 ? x : endian_reverse(x)`. ``` template void endian_reverse_inplace(EndianReversible& x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `x` `= endian_reverse(x)`. ``` template void big_to_native_inplace(EndianReversibleInplace& x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `conditional_reverse_inplace(x)`. ``` template void native_to_big_inplace(EndianReversibleInplace& x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `conditional_reverse_inplace(x)`. ``` template void little_to_native_inplace(EndianReversibleInplace& x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `conditional_reverse_inplace(x)`. ``` template void native_to_little_inplace(EndianReversibleInplace& x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: `conditional_reverse_inplace(x)`. ``` template void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: None if `O1 == O2,` otherwise `endian_reverse_inplace(x)`. Remarks:: Which effect applies shall be determined at compile time. @@ -294,8 +319,11 @@ template void conditional_reverse_inplace(EndianReversibleInplace& x, order order1, order order2) noexcept; ``` -[horizontal] +[none] +* {blank} ++ Effects:: If `order1 == order2` then `endian_reverse_inplace(x)`. +[none] ## FAQ diff --git a/doc/endian/mini_review_topics.adoc b/doc/endian/mini_review_topics.adoc index 987a868..a614d16 100644 --- a/doc/endian/mini_review_topics.adoc +++ b/doc/endian/mini_review_topics.adoc @@ -14,109 +14,66 @@ resolved before a mini-review. The issues are shown in *bold* below, with the resolution indicated. -*Common use case scenarios should be developed.* - -{blank}:: +Common use case scenarios should be developed.:: Done. The documentation have been refactored. A page is now devoted to <> to endianness. See <> for use case scenarios. -*Example programs should be developed for the common use case scenarios.* - -{blank}:: +Example programs should be developed for the common use case scenarios.:: Done. See <>. Example code has been added throughout. -*Documentation should illuminate the differences between endian -integer/float type and endian conversion approaches to the common use case -scenarios, and provide guidelines for choosing the most appropriate approach in -user's applications.* - -{blank}:: +Documentation should illuminate the differences between endian integer/float type and endian conversion approaches to the common use case scenarios, and provide guidelines for choosing the most appropriate approach in user's applications.:: Done. See <>. -*Conversion functions supplying results via return should be provided.* - -{blank}:: +Conversion functions supplying results via return should be provided.:: Done. See <>. -*Platform specific performance enhancements such as use of compiler -intrinsics or relaxed alignment requirements should be supported.* - -{blank}:: +Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.:: Done. Compiler (Clang, GCC, Visual{cpp}, etc.) intrinsics and built-in functions are used in the implementation where appropriate, as requested. See <>. See <> to gauge the impact of intrinsics. -*Endian integer (and floating) types should be implemented via the -conversion functions. If that can't be done efficiently, consideration should -be given to expanding the conversion function signatures to resolve the -inefficiencies.* - -{blank}:: +Endian integer (and floating) types should be implemented via the conversion functions. If that can't be done efficiently, consideration should be given to expanding the conversion function signatures to resolve the inefficiencies.:: Done. For the endian types, the implementation uses the endian conversion functions, and thus the intrinsics, as requested. -*Benchmarks that measure performance should be provided. It should be -possible to compare platform specific performance enhancements against portable -base implementations, and to compare endian integer approaches against endian -conversion approaches for the common use case scenarios.* - -{blank}:: +Benchmarks that measure performance should be provided. It should be possible to compare platform specific performance enhancements against portable base implementations, and to compare endian integer approaches against endian conversion approaches for the common use case scenarios.:: Done. See <>. The `endian/test` directory also contains several additional benchmark and speed test programs. -*Float (32-bits) and double (64-bits) should be supported. IEEE 754 is -the primary use case.* - -{blank}:: +Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the primary use case.:: Done. The <>, <> and <> now support 32-bit `(float)` and 64-bit `(double)` floating point, as requested. -*Support for user defined types (UDTs) is desirable, and should be -provided where there would be no conflict with the other concerns.* - -{blank}:: +Support for user defined types (UDTs) is desirable, and should be provided where there would be no conflict with the other concerns.:: Done. See <>. -*There is some concern that endian integer/float arithmetic operations -might used inadvertently or inappropriately. The impact of adding an -endian_buffer class without arithmetic operations should be investigated.* - -{blank}:: +There is some concern that endian integer/float arithmetic operations might used inadvertently or inappropriately. The impact of adding an endian_buffer class without arithmetic operations should be investigated.:: Done. The endian types have been decomposed into class template `<>` and class template `<>`. Class `endian_buffer` is a public base class for `endian_arithmetic`, and can also be used by users as a stand-alone class. -*Stream insertion and extraction of the endian integer/float types should -be documented and included in the test coverage.* - -{blank}:: +Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.:: Done. See <> and <>. -*Binary I/O support that was investigated during development of the -Endian library should be put up for mini-review for inclusion in the Boost I/O -library.* - -{blank}:: +Binary I/O support that was investigated during development of the Endian library should be put up for mini-review for inclusion in the Boost I/O library.:: Not done yet. Will be handled as a separate min-review soon after the Endian mini-review. -*Other requested changes.* - -{blank}:: -* In addition to the named-endianness conversion functions, functions that +Other requested changes.:: + In addition to the named-endianness conversion functions, functions that perform compile-time (via template) and run-time (via function argument) dispatch are now provided. -* `order*native` is now a synonym for `order*big` or `order*little` according + `order*native` is now a synonym for `order*big` or `order*little` according to the endianness of the platform. This reduces the number of template specializations required. -* Headers have been reorganized to make them easier to read, with a synopsis + Headers have been reorganized to make them easier to read, with a synopsis at the front and implementation following.