boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2025-08-01 13:34:39 +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(){}
```
[horizontal]
[none]
* {blank}
+
Effects:: Constructs an uninitialized object of type
`endian_arithmetic<E, T, n_bits, A>`.
```
endian(T v);
```
[horizontal]
[none]
* {blank}
+
Effects:: Constructs an object of type `endian_arithmetic<E, T, n_bits, A>`.
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<charT, traits>&
operator<<(std::basic_ostream<charT, traits>& os, const T& x);
```
[horizontal]
Returns:: `os << +x`.</p>
[none]
* {blank}
+
Returns:: `os << +x`.
[none]
### Stream extractor
@@ -432,7 +445,9 @@ template <class charT, class traits>
friend std::basic_istream<charT, traits>&
operator>>(std::basic_istream<charT, traits>& is, T& x);
```
[horizontal]
[none]
* {blank}
+
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;
```
[horizontal]
[none]
* {blank}
+
Effects:: Constructs an uninitialized object of type `endian_buffer<Order, T,
Nbits, Align>`.
```
explicit endian_buffer(T v) noexcept;
```
[horizontal]
[none]
* {blank}
+
Effects:: Constructs an object of type `endian_buffer<Order, T, Nbits, Align>`.
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</a>() const noexcept;
```
[horizontal]
[none]
* {blank}
+
Returns:: A pointer to the first byte of `endian_value`.
[none]
### 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,
const endian_buffer<Order, T, n_bits, Align>& x);
```
[horizontal]
[none]
* {blank}
+
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,
endian_buffer<Order, T, n_bits, Align>& x);
```
[horizontal]
[none]
* {blank}
+
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;
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 <class EndianReversible>
EndianReversible big_to_native(EndianReversible x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Returns:: `conditional_reverse<order::big, order::native>(x)`.
```
template <class EndianReversible>
EndianReversible native_to_big(EndianReversible x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Returns:: `conditional_reverse<order::native, order::big>(x)`.
```
template <class EndianReversible>
EndianReversible little_to_native(EndianReversible x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Returns:: `conditional_reverse<order::little, order::native>(x)`.
```
template <class EndianReversible>
EndianReversible native_to_little(EndianReversible x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Returns:: `conditional_reverse<order::native, order::little>(x)`.
```
template <order O1, order O2, class EndianReversible>
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 <class EndianReversible>
EndianReversible conditional_reverse(EndianReversible x,
order order1, order order2) noexcept;
```
[horizontal]
[none]
* {blank}
+
Returns:: `order1 == order2 ? x : endian_reverse(x)`.
```
template <class EndianReversible>
void endian_reverse_inplace(EndianReversible& x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Effects:: `x` `= endian_reverse(x)`.
```
template <class EndianReversibleInplace>
void big_to_native_inplace(EndianReversibleInplace& x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::big, order::native>(x)`.
```
template <class EndianReversibleInplace>
void native_to_big_inplace(EndianReversibleInplace& x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::native, order::big>(x)`.
```
template <class EndianReversibleInplace>
void little_to_native_inplace(EndianReversibleInplace& x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::little, order::native>(x)`.
```
template <class EndianReversibleInplace>
void native_to_little_inplace(EndianReversibleInplace& x) noexcept;
```
[horizontal]
[none]
* {blank}
+
Effects:: `conditional_reverse_inplace<order::native, order::little>(x)`.
```
template <order O1, order O2, class EndianReversibleInplace>
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 <class EndianReversibleInplace>
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

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.
*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
<<choosing,Choosing the Approach>> to endianness. See
<<choosing_use_cases,Use cases>> 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 <<choosing,Choosing the Approach>>. 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 <<choosing,Choosing the Approach>>.
*Conversion functions supplying results via return should be provided.*
{blank}::
Conversion functions supplying results via return should be provided.::
Done. See <<conversion,Conversion Functions>>.
*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
<<overview_intrinsic,Built-in support for Intrinsics>>. See
<<overview_timings,Timings for Example 2>> 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 <<overview_timings,Timings for Example 2>>. 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 <<buffers,endian buffer types>>,
<<arithmetic,endian arithmetic types>> and
<<conversion,endian conversion functions>> 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 <<conversion_customization,Customization points for user-defined
types (UDTs)>>.
*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
`<<buffers,endian_buffer>>` and class template
`<<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.
*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 <<buffers_stream_inserter,Stream inserter>> and
<<buffers_stream_extractor,Stream extractor>>.
*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.