boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2025-08-01 21:44:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Minor formatting changes in documentation

Browse Source
This commit is contained in:
Glen Fernandes
2019-03-25 09:32:54 -04:00
parent 9ffe32f740
commit a6aaec46f5
4 changed files with 105 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
doc/endian/arithmetic.adoc
View File

@@ -378,34 +378,44 @@ to the endianness of the platform.
``` ```
endian() = default; // C++03: endian(){} endian() = default; // C++03: endian(){}
``` ```
[horizontal] [none]
* {blank}
+
Effects:: Constructs an uninitialized object of type Effects:: Constructs an uninitialized object of type
`endian_arithmetic<E, T, n_bits, A>`. `endian_arithmetic<E, T, n_bits, A>`.
``` ```
endian(T v); endian(T v);
``` ```
[horizontal] [none]
* {blank}
+
Effects:: Constructs an object of type `endian_arithmetic<E, T, n_bits, A>`. Effects:: Constructs an object of type `endian_arithmetic<E, T, n_bits, A>`.
Postcondition:: `x == v,` where `x` is the constructed object. Postcondition:: `x == v,` where `x` is the constructed object.
``` ```
endian& operator=(T v); endian& operator=(T v);
``` ```
[horizontal] [none]
* {blank}
+
Postcondition:: `x == v,` where `x` is the constructed object. Postcondition:: `x == v,` where `x` is the constructed object.
Returns:: `*this`. Returns:: `*this`.
``` ```
operator T() const; operator T() const;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: The current value stored in `*this`, converted to `value_type`. Returns:: The current value stored in `*this`, converted to `value_type`.
``` ```
const char* data() const; const char* data() const;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: A pointer to the first byte of the endian binary value stored in Returns:: A pointer to the first byte of the endian binary value stored in
`*this`. `*this`.
@@ -422,8 +432,11 @@ friend std::basic_ostream<charT, traits>&
operator<<(std::basic_ostream<charT, traits>& os, const T& x); operator<<(std::basic_ostream<charT, traits>& os, const T& x);
``` ```
[horizontal] [none]
Returns:: `os << +x`.</p> * {blank}
+
Returns:: `os << +x`.
[none]
### Stream extractor ### Stream extractor
@@ -432,7 +445,9 @@ template <class charT, class traits>
friend std::basic_istream<charT, traits>& friend std::basic_istream<charT, traits>&
operator>>(std::basic_istream<charT, traits>& is, T& x); operator>>(std::basic_istream<charT, traits>& is, T& x);
``` ```
[horizontal] [none]
* {blank}
+
Effects:: As if: Effects:: As if:
+ +
``` ```

29
doc/endian/buffers.adoc
View File

@@ -364,14 +364,18 @@ Template parameter `T` is required to be a standard integer type ({cpp}std,
``` ```
endian_buffer() noexcept = default; endian_buffer() noexcept = default;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: Constructs an uninitialized object of type `endian_buffer<Order, T, Effects:: Constructs an uninitialized object of type `endian_buffer<Order, T,
Nbits, Align>`. Nbits, Align>`.
``` ```
explicit endian_buffer(T v) noexcept; explicit endian_buffer(T v) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: Constructs an object of type `endian_buffer<Order, T, Nbits, Align>`. Effects:: Constructs an object of type `endian_buffer<Order, T, Nbits, Align>`.
Postcondition:: `value() == v & mask`, where `mask` is a constant of type Postcondition:: `value() == v & mask`, where `mask` is a constant of type
`value_type` with `Nbits` low-order bits set to one. `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; endian_buffer& operator=(T v) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Postcondition:: `value() == v & mask`, where `mask` is a constant of type Postcondition:: `value() == v & mask`, where `mask` is a constant of type
`value_type` with `Nbits` low-order bits set to one. `value_type` with `Nbits` low-order bits set to one.
Returns:: `*this`. Returns:: `*this`.
@@ -391,7 +397,9 @@ performed by `boost::endian::endian_reverse`.
``` ```
value_type value() const noexcept; value_type value() const noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `endian_value`, converted to `value_type`, if required, and having the Returns:: `endian_value`, converted to `value_type`, if required, and having the
endianness of the native platform. endianness of the native platform.
Remarks:: If `Align` is `align::yes` then endianness conversion, if required, is 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</a>() const noexcept; const char* data</a>() const noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: A pointer to the first byte of `endian_value`. Returns:: A pointer to the first byte of `endian_value`.
[none]
### Non-member functions ### Non-member functions
@@ -411,7 +422,9 @@ template <class charT, class traits, order Order, class T,
std::basic_ostream<charT, traits>& operator<<(std::basic_ostream<charT, traits>& os, std::basic_ostream<charT, traits>& operator<<(std::basic_ostream<charT, traits>& os,
const endian_buffer<Order, T, n_bits, Align>& x); const endian_buffer<Order, T, n_bits, Align>& x);
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `os << x.value()`. Returns:: `os << x.value()`.
``` ```
@@ -420,7 +433,9 @@ template <class charT, class traits, order Order, class T,
std::basic_istream<charT, traits>& operator>>(std::basic_istream<charT, traits>& is, std::basic_istream<charT, traits>& operator>>(std::basic_istream<charT, traits>& is,
endian_buffer<Order, T, n_bits, Align>& x); endian_buffer<Order, T, n_bits, Align>& x);
``` ```
[horizontal] [none]
* {blank}
+
Effects:: As if: Effects:: As if:
+ +
``` ```

60
doc/endian/conversion.adoc
View File

@@ -193,10 +193,12 @@ uint16_t endian_reverse(uint16_t x) noexcept;
uint32_t endian_reverse(uint32_t x) noexcept; uint32_t endian_reverse(uint32_t x) noexcept;
uint64_t endian_reverse(uint64_t x) noexcept; uint64_t endian_reverse(uint64_t x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `x`, with the order of its constituent bytes reversed. Returns:: `x`, with the order of its constituent bytes reversed.
Remarks:: The type of `x` meets the `EndianReversible` requirements. Remarks:: The type of `x` meets the `EndianReversible` requirements.
+
NOTE: The Boost.Endian library does not provide overloads for the {cpp} standard NOTE: The Boost.Endian library does not provide overloads for the {cpp} standard
library supplied types. library supplied types.
@@ -204,88 +206,111 @@ library supplied types.
template <class EndianReversible> template <class EndianReversible>
EndianReversible big_to_native(EndianReversible x) noexcept; EndianReversible big_to_native(EndianReversible x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `conditional_reverse<order::big, order::native>(x)`. Returns:: `conditional_reverse<order::big, order::native>(x)`.
``` ```
template <class EndianReversible> template <class EndianReversible>
EndianReversible native_to_big(EndianReversible x) noexcept; EndianReversible native_to_big(EndianReversible x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `conditional_reverse<order::native, order::big>(x)`. Returns:: `conditional_reverse<order::native, order::big>(x)`.
``` ```
template <class EndianReversible> template <class EndianReversible>
EndianReversible little_to_native(EndianReversible x) noexcept; EndianReversible little_to_native(EndianReversible x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `conditional_reverse<order::little, order::native>(x)`. Returns:: `conditional_reverse<order::little, order::native>(x)`.
``` ```
template <class EndianReversible> template <class EndianReversible>
EndianReversible native_to_little(EndianReversible x) noexcept; EndianReversible native_to_little(EndianReversible x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `conditional_reverse<order::native, order::little>(x)`. Returns:: `conditional_reverse<order::native, order::little>(x)`.
``` ```
template <order O1, order O2, class EndianReversible> template <order O1, order O2, class EndianReversible>
EndianReversible conditional_reverse(EndianReversible x) noexcept; EndianReversible conditional_reverse(EndianReversible x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `x` if `O1 == O2,` otherwise `endian_reverse(x)`. Returns:: `x` if `O1 == O2,` otherwise `endian_reverse(x)`.
Remarks:: Whether `x` or `endian_reverse(x)` is to be returned shall be Remarks:: Whether `x` or `endian_reverse(x)` is to be returned shall be
determined at compile time. determined at compile time.
``` ```
template <class EndianReversible> template <class EndianReversible>
EndianReversible conditional_reverse(EndianReversible x, EndianReversible conditional_reverse(EndianReversible x,
order order1, order order2) noexcept; order order1, order order2) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Returns:: `order1 == order2 ? x : endian_reverse(x)`. Returns:: `order1 == order2 ? x : endian_reverse(x)`.
``` ```
template <class EndianReversible> template <class EndianReversible>
void endian_reverse_inplace(EndianReversible& x) noexcept; void endian_reverse_inplace(EndianReversible& x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: `x` `= endian_reverse(x)`. Effects:: `x` `= endian_reverse(x)`.
``` ```
template <class EndianReversibleInplace> template <class EndianReversibleInplace>
void big_to_native_inplace(EndianReversibleInplace& x) noexcept; void big_to_native_inplace(EndianReversibleInplace& x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::big, order::native>(x)`. Effects:: `conditional_reverse_inplace<order::big, order::native>(x)`.
``` ```
template <class EndianReversibleInplace> template <class EndianReversibleInplace>
void native_to_big_inplace(EndianReversibleInplace& x) noexcept; void native_to_big_inplace(EndianReversibleInplace& x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::native, order::big>(x)`. Effects:: `conditional_reverse_inplace<order::native, order::big>(x)`.
``` ```
template <class EndianReversibleInplace> template <class EndianReversibleInplace>
void little_to_native_inplace(EndianReversibleInplace& x) noexcept; void little_to_native_inplace(EndianReversibleInplace& x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::little, order::native>(x)`. Effects:: `conditional_reverse_inplace<order::little, order::native>(x)`.
``` ```
template <class EndianReversibleInplace> template <class EndianReversibleInplace>
void native_to_little_inplace(EndianReversibleInplace& x) noexcept; void native_to_little_inplace(EndianReversibleInplace& x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::native, order::little>(x)`. Effects:: `conditional_reverse_inplace<order::native, order::little>(x)`.
``` ```
template <order O1, order O2, class EndianReversibleInplace> template <order O1, order O2, class EndianReversibleInplace>
void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept; void conditional_reverse_inplace(EndianReversibleInplace& x) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: None if `O1 == O2,` otherwise `endian_reverse_inplace(x)`. Effects:: None if `O1 == O2,` otherwise `endian_reverse_inplace(x)`.
Remarks:: Which effect applies shall be determined at compile time. Remarks:: Which effect applies shall be determined at compile time.
@@ -294,8 +319,11 @@ template <class EndianReversibleInplace>
void conditional_reverse_inplace(EndianReversibleInplace& x, void conditional_reverse_inplace(EndianReversibleInplace& x,
order order1, order order2) noexcept; order order1, order order2) noexcept;
``` ```
[horizontal] [none]
* {blank}
+
Effects:: If `order1 == order2` then `endian_reverse_inplace(x)`. Effects:: If `order1 == order2` then `endian_reverse_inplace(x)`.
[none]
## FAQ ## FAQ

75
doc/endian/mini_review_topics.adoc
View File

@@ -14,109 +14,66 @@ resolved before a mini-review.
The issues are shown in *bold* below, with the resolution indicated. The issues are shown in *bold* below, with the resolution indicated.
*Common use case scenarios should be developed.* Common use case scenarios should be developed.::
{blank}::
Done. The documentation have been refactored. A page is now devoted to Done. The documentation have been refactored. A page is now devoted to
<<choosing,Choosing the Approach>> to endianness. See <<choosing,Choosing the Approach>> to endianness. See
<<choosing_use_cases,Use cases>> for use case scenarios. <<choosing_use_cases,Use cases>> for use case scenarios.
*Example programs should be developed for the common use case scenarios.* Example programs should be developed for the common use case scenarios.::
{blank}::
Done. See <<choosing,Choosing the Approach>>. Example code has been added Done. See <<choosing,Choosing the Approach>>. Example code has been added
throughout. throughout.
*Documentation should illuminate the differences between endian 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.::
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}::
Done. See <<choosing,Choosing the Approach>>. Done. See <<choosing,Choosing the Approach>>.
*Conversion functions supplying results via return should be provided.* Conversion functions supplying results via return should be provided.::
{blank}::
Done. See <<conversion,Conversion Functions>>. Done. See <<conversion,Conversion Functions>>.
*Platform specific performance enhancements such as use of compiler Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.::
intrinsics or relaxed alignment requirements should be supported.*
{blank}::
Done. Compiler (Clang, GCC, Visual{cpp}, etc.) intrinsics and built-in Done. Compiler (Clang, GCC, Visual{cpp}, etc.) intrinsics and built-in
functions are used in the implementation where appropriate, as requested. See functions are used in the implementation where appropriate, as requested. See
<<overview_intrinsic,Built-in support for Intrinsics>>. See <<overview_intrinsic,Built-in support for Intrinsics>>. See
<<overview_timings,Timings for Example 2>> to gauge the impact of intrinsics. <<overview_timings,Timings for Example 2>> to gauge the impact of intrinsics.
*Endian integer (and floating) types should be implemented via the 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.::
conversion functions. If that can't be done efficiently, consideration should
be given to expanding the conversion function signatures to resolve the
inefficiencies.*
{blank}::
Done. For the endian types, the implementation uses the endian conversion Done. For the endian types, the implementation uses the endian conversion
functions, and thus the intrinsics, as requested. functions, and thus the intrinsics, as requested.
*Benchmarks that measure performance should be provided. It should be 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.::
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}::
Done. See <<overview_timings,Timings for Example 2>>. The `endian/test` Done. See <<overview_timings,Timings for Example 2>>. The `endian/test`
directory also contains several additional benchmark and speed test programs. directory also contains several additional benchmark and speed test programs.
*Float (32-bits) and double (64-bits) should be supported. IEEE 754 is Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the primary use case.::
the primary use case.*
{blank}::
Done. The <<buffers,endian buffer types>>, Done. The <<buffers,endian buffer types>>,
<<arithmetic,endian arithmetic types>> and <<arithmetic,endian arithmetic types>> and
<<conversion,endian conversion functions>> now support 32-bit `(float)` <<conversion,endian conversion functions>> now support 32-bit `(float)`
and 64-bit `(double)` floating point, as requested. and 64-bit `(double)` floating point, as requested.
*Support for user defined types (UDTs) is desirable, and should be Support for user defined types (UDTs) is desirable, and should be provided where there would be no conflict with the other concerns.::
provided where there would be no conflict with the other concerns.*
{blank}::
Done. See <<conversion_customization,Customization points for user-defined Done. See <<conversion_customization,Customization points for user-defined
types (UDTs)>>. types (UDTs)>>.
*There is some concern that endian integer/float arithmetic operations 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.::
might used inadvertently or inappropriately. The impact of adding an
endian_buffer class without arithmetic operations should be investigated.*
{blank}::
Done. The endian types have been decomposed into class template Done. The endian types have been decomposed into class template
`<<buffers,endian_buffer>>` and class template `<<buffers,endian_buffer>>` and class template
`<<arithmetic,endian_arithmetic>>`. Class `endian_buffer` is a public base `<<arithmetic,endian_arithmetic>>`. Class `endian_buffer` is a public base
class for `endian_arithmetic`, and can also be used by users as a stand-alone class for `endian_arithmetic`, and can also be used by users as a stand-alone
class. class.
*Stream insertion and extraction of the endian integer/float types should Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.::
be documented and included in the test coverage.*
{blank}::
Done. See <<buffers_stream_inserter,Stream inserter>> and Done. See <<buffers_stream_inserter,Stream inserter>> and
<<buffers_stream_extractor,Stream extractor>>. <<buffers_stream_extractor,Stream extractor>>.
*Binary I/O support that was investigated during development of the 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.::
Endian library should be put up for mini-review for inclusion in the Boost I/O
library.*
{blank}::
Not done yet. Will be handled as a separate min-review soon after the Endian Not done yet. Will be handled as a separate min-review soon after the Endian
mini-review. mini-review.
*Other requested changes.* Other requested changes.::
In addition to the named-endianness conversion functions, functions that
{blank}::
* In addition to the named-endianness conversion functions, functions that
perform compile-time (via template) and run-time (via function argument) perform compile-time (via template) and run-time (via function argument)
dispatch are now provided. 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 to the endianness of the platform. This reduces the number of template
specializations required. 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. at the front and implementation following.