feedc0de/boost_endian
1
0
Fork 0
forked from boostorg/endian
Code Pull Requests Activity

Update documentation

Browse Source
This commit is contained in:
Peter Dimov
2020-05-03 04:46:35 +03:00
parent 3e2890c243
commit 9d248e0f5e
4 changed files with 53 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/endian/arithmetic.adoc
View File

@@ -39,6 +39,7 @@ Implicit conversion to the underlying value type is provided. An implicit
constructor converting from the underlying value type is provided. constructor converting from the underlying value type is provided.
## Example ## Example
The `endian_example.cpp` program writes a binary file containing four-byte, The `endian_example.cpp` program writes a binary file containing four-byte,
big-endian and little-endian integers: big-endian and little-endian integers:
@@ -210,7 +211,7 @@ and to improve code readability and searchability.
## Class template `endian_arithmetic` ## Class template `endian_arithmetic`
An `endian_integer` is an integer byte-holder with user-specified endianness, `endian_arithmetic` is an integer byte-holder with user-specified endianness,
value type, size, and alignment. The usual operations on arithmetic types are value type, size, and alignment. The usual operations on arithmetic types are
supplied. supplied.
@@ -568,6 +569,7 @@ Functions] feature is detected automatically, and will be used if present to
ensure that objects of `class endian_arithmetic` are trivial, and thus PODs. ensure that objects of `class endian_arithmetic` are trivial, and thus PODs.
## Compilation ## Compilation
Boost.Endian is implemented entirely within headers, with no need to link to any Boost.Endian is implemented entirely within headers, with no need to link to any
Boost object libraries. Boost object libraries.

5
doc/endian/changelog.adoc
View File

@@ -10,6 +10,11 @@ http://www.boost.org/LICENSE_1_0.txt
[#changelog] [#changelog]
# Revision History # Revision History
## Changes in 1.74.0
* Enabled scoped enumeration types in `endian_reverse`
* Enabled `bool`, `enum`, `float`, `double` in `endian_reverse_inplace`
## Changes in 1.72.0 ## Changes in 1.72.0
* Made `endian_reverse`, `conditional_reverse` and `\*\_to_*` `constexpr` * Made `endian_reverse`, `conditional_reverse` and `\*\_to_*` `constexpr`

65
doc/endian/conversion.adoc
View File

@@ -35,8 +35,20 @@ _http://en.wikipedia.org/wiki/Gulliver's_Travels[Gulliver's Travels]_, where
rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an rival kingdoms opened their soft-boiled eggs at different ends. Wikipedia has an
extensive description of https://en.wikipedia.org/wiki/Endianness[Endianness]. extensive description of https://en.wikipedia.org/wiki/Endianness[Endianness].
The standard integral types ({cpp}std 3.9.1) except `bool` are collectively The standard integral types ({cpp}std [basic.fundamental]) except `bool` and
called the *endian types*. the scoped enumeration types ({cpp}std [dcl.enum]) are collectively called the
*endian types*. In the absence of padding bits, which is true on the platforms
supported by the Boost.Endian library, endian types have the property that all
of their bit patterns are valid values, which means that when an object of an
endian type has its constituent bytes reversed, the result is another valid value.
This allows `endian_reverse` to take and return by value.
Other built-in types, such as `bool`, `float`, or unscoped enumerations, do not
have the same property, which means that reversing their constituent bytes may
produce an invalid value, leading to undefined behavior. These types are therefore
disallowed in `endian_reverse`, but are still allowed in `endian_reverse_inplace`.
Even if an object becomes invalid as a result of reversing its bytes, as long as
its value is never read, there would be no undefined behavior.
### Header `<boost/endian/conversion.hpp>` Synopsis ### Header `<boost/endian/conversion.hpp>` Synopsis
@@ -216,37 +228,37 @@ reversed.
If `T` is a class type, the function: If `T` is a class type, the function:
* Returns the value of `x` with the order of bytes reversed for all data members * Is expected to be implemented by the user, as a non-member function in the same
of types or arrays of types that meet the `EndianReversible` requirements, and; namespace as `T` that can be found by argument dependent lookup (ADL);
* Is a non-member function in the same namespace as `T` that can be found by * Should returns the value of `x` with the order of bytes reversed for all data members
argument dependent lookup (ADL). of types or arrays of types that meet the `EndianReversible` requirements.
|=== |===
[#conversion_endianreversibleinplace] [#conversion_endianreversibleinplace]
##### EndianReversibleInplace requirements (in addition to `CopyConstructible`) ##### EndianReversibleInplace requirements
[%header,cols=2*] [%header,cols=2*]
|=== |===
|Expression |Requirements |Expression |Requirements
|`endian_reverse_inplace(mlx)` |`endian_reverse_inplace(mlx)`
a|`T` is an endian type or a class type. a|`T` is an integral type, an enumeration type, `float`, `double`, or a class type.
If `T` is an endian type, reverses the order of bytes in `mlx`. If `T` is not a class type, reverses the order of bytes in `mlx`.
If `T` is a class type, the function: If `T` is a class type, the function:
* Reverses the order of bytes of all data members of `mlx` that have types or * Is expected to be implemented by the user, as a non-member function in the same
namespace as `T` that can be found by argument dependent lookup (ADL);
* Should reverse the order of bytes of all data members of `mlx` that have types or
arrays of types that meet the `EndianReversible` or `EndianReversibleInplace` arrays of types that meet the `EndianReversible` or `EndianReversibleInplace`
requirements, and; requirements.
* Is a non-member function in the same namespace as `T` that can be found by
argument dependent lookup (ADL).
|=== |===
NOTE: Because there is a function template for `endian_reverse_inplace` that NOTE: Because there is a function template for `endian_reverse_inplace` that
calls `endian_reverse`, only `endian_reverse` is required for a user-defined calls `endian_reverse` for class types, only `endian_reverse` is required for a
type to meet the `EndianReversibleInplace` requirements. Although User-defined user-defined type to meet the `EndianReversibleInplace` requirements. Although
types are not required to supply an `endian_reverse_inplace` function, doing so user-defined types are not required to supply an `endian_reverse_inplace` function,
may improve efficiency. doing so may improve efficiency.
#### Customization points for user-defined types (UDTs) #### Customization points for user-defined types (UDTs)
@@ -273,7 +285,8 @@ Endian endian_reverse(Endian x) noexcept;
[none] [none]
* {blank} * {blank}
+ +
Requires:: `Endian` must be a standard integral type that is not `bool`. Requires:: `Endian` must be a standard integral type that is not `bool`,
or a scoped enumeration type.
Returns:: `x`, with the order of its constituent bytes reversed. Returns:: `x`, with the order of its constituent bytes reversed.
``` ```
@@ -343,7 +356,11 @@ void endian_reverse_inplace(EndianReversible& x) noexcept;
[none] [none]
* {blank} * {blank}
+ +
Effects:: `x = endian_reverse(x)`. Effects:: When `EndianReversible` is a class type,
`x = endian_reverse(x);`. When `EndianReversible` is an integral
type, an enumeration type, `float`, or `double`, reverses the
order of the constituent bytes of `x`. Otherwise, the program is
ill-formed.
``` ```
template <class EndianReversibleInplace> template <class EndianReversibleInplace>
@@ -526,17 +543,15 @@ Effects::
See the <<overview_faq,Overview FAQ>> for a library-wide FAQ. See the <<overview_faq,Overview FAQ>> for a library-wide FAQ.
*Why are both value returning and modify-in-place functions provided?* Why are both value returning and modify-in-place functions provided?::
Returning the result by value is the standard C and {cpp} idiom for functions
* Returning the result by value is the standard C and {cpp} idiom for functions
that compute a value from an argument. Modify-in-place functions allow cleaner that compute a value from an argument. Modify-in-place functions allow cleaner
code in many real-world endian use cases and are more efficient for user-defined code in many real-world endian use cases and are more efficient for user-defined
types that have members such as string data that do not need to be reversed. types that have members such as string data that do not need to be reversed.
Thus both forms are provided. Thus both forms are provided.
*Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?* Why not use the Linux names (htobe16, htole16, be16toh, le16toh, etc.) ?::
Those names are non-standard and vary even between POSIX-like operating
* Those names are non-standard and vary even between POSIX-like operating
systems. A {cpp} library TS was going to use those names, but found they were systems. A {cpp} library TS was going to use those names, but found they were
sometimes implemented as macros. Since macros do not respect scoping and sometimes implemented as macros. Since macros do not respect scoping and
namespace rules, to use them would be very error prone. namespace rules, to use them would be very error prone.

5
doc/endian/overview.adoc
View File

@@ -359,7 +359,8 @@ limitations, support for floating point types was not reliable and was removed.
For example, simply reversing the endianness of a floating point number can For example, simply reversing the endianness of a floating point number can
result in a signaling-NAN. result in a signaling-NAN.
+ +
Support for `float` and `double` has since been reinstated for `endian_buffer` Support for `float` and `double` has since been reinstated for `endian_buffer`,
and `endian_arithmetic`. The conversion functions still do not support floating `endian_arithmetic` and the conversion functions that reverse endianness in place.
The conversion functions that take and return by value still do not support floating
point due to the above issues; reversing the bytes of a floating point number point due to the above issues; reversing the bytes of a floating point number
does not necessarily produce another valid floating point number. does not necessarily produce another valid floating point number.