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
2023-10-20 02:28:24 +03:00
parent 927c598c84
commit 699cb133e8
5 changed files with 46 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
doc/endian/arithmetic.adoc
View File

@@ -130,16 +130,6 @@ design, implementation, testing, and documentation has only considered issues
related to 8-bit bytes, and there have been no real-world use cases presented related to 8-bit bytes, and there have been no real-world use cases presented
for other sizes. for other sizes.
In {cpp}03, `endian_arithmetic` does not meet the requirements for POD types
because it has constructors, private data members, and a base class. This means
that common use cases are relying on unspecified behavior in that the {cpp}
Standard does not guarantee memory layout for non-POD types. This has not been a
problem in practice since all known {cpp} compilers lay out memory as if
`endian` were a POD type. In {cpp}11, it is possible to specify the default
constructor as trivial, and private data members and base classes no longer
disqualify a type from being a POD type. Thus under {cpp}11, `endian_arithmetic`
will no longer be relying on unspecified behavior.
## Feature set ## Feature set
* Big endian| little endian | native endian byte ordering. * Big endian| little endian | native endian byte ordering.
@@ -224,8 +214,6 @@ namespace boost
{ {
namespace endian namespace endian
{ {
// C++11 features emulated if not available
enum class align { no, yes }; enum class align { no, yes };
template <order Order, class T, std::size_t n_bits, template <order Order, class T, std::size_t n_bits,
@@ -236,8 +224,9 @@ namespace boost
typedef T value_type; typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 PODs are not // if BOOST_ENDIAN_NO_CTORS is defined, these two
// available then these two constructors will not be present // constructors will not be present
endian_arithmetic() noexcept = default; endian_arithmetic() noexcept = default;
endian_arithmetic(T v) noexcept; endian_arithmetic(T v) noexcept;
@@ -408,7 +397,7 @@ When `Nbits` is less than `sizeof(T)*8`, `T` must be a standard integral type
### Members ### Members
``` ```
endian_arithmetic() noexcept = default; // C++03: endian(){} endian_arithmetic() noexcept = default;
``` ```
[none] [none]
* {blank} * {blank}
@@ -508,13 +497,10 @@ integers require no conversion or copying. They are already in the desired
format for binary I/O. Thus they can be read or written in bulk. format for binary I/O. Thus they can be read or written in bulk.
Are endian types PODs?:: Are endian types PODs?::
Yes for {cpp}11. No for {cpp}03, although several Yes for the {cpp}11 definition of POD. No for the {cpp}03 definition of POD,
<<arithmetic_compilation,macros>> are available to force PODness in all cases. although the <<arithmetic_compilation,macro>> `BOOST_ENDIAN_NO_CTORS` can be
used to disable the constructors and to force {cpp}03 PODness (which is
What are the implications of endian integer types not being PODs with {cpp}03 compilers?:: required, for example, by the GCC `++__attribute__((packed))++` extension.)
They can't be used in unions. Also, compilers aren't required to align or lay
out storage in portable ways, although this potential problem hasn't prevented
use of Boost.Endian with real compilers.
What good is native endianness?:: What good is native endianness?::
It provides alignment and size guarantees not available from the built-in It provides alignment and size guarantees not available from the built-in
@@ -579,32 +565,15 @@ library: reading TrueType font files from disk and processing the contents. The
data format has fixed endianness (big) and has unaligned values in various data format has fixed endianness (big) and has unaligned values in various
places. Using Boost.Endian simplifies and cleans the code wonderfully." places. Using Boost.Endian simplifies and cleans the code wonderfully."
## {cpp}11
The availability of the {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions] feature is detected automatically, and will be used if present to
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.
Several macros allow user control over features: The macro `BOOST_ENDIAN_NO_CTORS`, when defined, causes `class endian_buffer`
to have no constructors. The intended use is to guarantee that `endian_buffer`
* BOOST_ENDIAN_NO_CTORS causes `class endian_arithmetic` to have no is a {cpp}03 POD. This is required, for example, by the GCC
constructors. The intended use is for compiling user code that must be portable `++__attribute__((packed))++` extension.
between compilers regardless of {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions] support. Use of constructors will always fail,
* BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if
the compiler does not support {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions]. This is ensures that objects of `class endian_arithmetic` are PODs,
and so can be used in {cpp}03 unions. In {cpp}11, `class endian_arithmetic`
objects are PODs, even though they have constructors, so can always be used in
unions.
## Acknowledgements ## Acknowledgements

51
doc/endian/buffers.adoc
View File

@@ -124,16 +124,6 @@ design, implementation, testing, and documentation has only considered issues
related to 8-bit bytes, and there have been no real-world use cases presented related to 8-bit bytes, and there have been no real-world use cases presented
for other sizes. for other sizes.
In {cpp}03, `endian_buffer` does not meet the requirements for POD types because
it has constructors and a private data member. This means that
common use cases are relying on unspecified behavior in that the {cpp} Standard
does not guarantee memory layout for non-POD types. This has not been a problem
in practice since all known {cpp} compilers lay out memory as if `endian` were
a POD type. In {cpp}11, it is possible to specify the default constructor as
trivial, and private data members and base classes no longer disqualify a type
from being a POD type. Thus under {cpp}11, `endian_buffer` will no longer be
relying on unspecified behavior.
## Feature set ## Feature set
* Big endian| little endian | native endian byte ordering. * Big endian| little endian | native endian byte ordering.
@@ -215,8 +205,6 @@ namespace boost
{ {
namespace endian namespace endian
{ {
// C++11 features emulated if not available
enum class align { no, yes }; enum class align { no, yes };
template <order Order, class T, std::size_t Nbits, template <order Order, class T, std::size_t Nbits,
@@ -227,6 +215,9 @@ namespace boost
typedef T value_type; typedef T value_type;
// if BOOST_ENDIAN_NO_CTORS is defined, these two
// constructors will not be present
endian_buffer() noexcept = default; endian_buffer() noexcept = default;
explicit endian_buffer(T v) noexcept; explicit endian_buffer(T v) noexcept;
@@ -475,13 +466,10 @@ integers require no conversion or copying. They are already in the desired
format for binary I/O. Thus they can be read or written in bulk. format for binary I/O. Thus they can be read or written in bulk.
Are endian types PODs?:: Are endian types PODs?::
Yes for {cpp}11. No for {cpp}03, although several Yes for the {cpp}11 definition of POD. No for the {cpp}03 definition of POD,
<<buffers_compilation,macros>> are available to force PODness in all cases. although the <<buffers_compilation,macro>> `BOOST_ENDIAN_NO_CTORS` can be
used to disable the constructors and to force {cpp}03 PODness (which is
What are the implications of endian integer types not being PODs with {cpp}03 compilers?:: required, for example, by the GCC `++__attribute__((packed))++` extension.)
They can't be used in unions. Also, compilers aren't required to align or lay
out storage in portable ways, although this potential problem hasn't prevented
use of Boost.Endian with real compilers.
What good is native endianness?:: What good is native endianness?::
It provides alignment and size guarantees not available from the built-in It provides alignment and size guarantees not available from the built-in
@@ -513,29 +501,12 @@ when changing machines or compilers. Pessimizations can also happen when
changing compiler switches, compiler versions, or CPU models of the same changing compiler switches, compiler versions, or CPU models of the same
architecture. architecture.
## {cpp}11
The availability of the {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions] feature is detected automatically, and will be used if present to
ensure that objects of `class endian_buffer` are trivial, and thus
PODs.
## Compilation ## Compilation
Boost.Endian is implemented entirely within headers, with no need to link to Boost.Endian is implemented entirely within headers, with no need to link to
any Boost object libraries. any Boost object libraries.
Several macros allow user control over features: The macro `BOOST_ENDIAN_NO_CTORS`, when defined, causes `class endian_buffer`
to have no constructors. The intended use is to guarantee that `endian_buffer`
* `BOOST_ENDIAN_NO_CTORS` causes `class endian_buffer` to have no is a {cpp}03 POD. This is required, for example, by the GCC
constructors. The intended use is for compiling user code that must be `++__attribute__((packed))++` extension.
portable between compilers regardless of {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions] support. Use of constructors will always fail,
* `BOOST_ENDIAN_FORCE_PODNESS` causes `BOOST_ENDIAN_NO_CTORS` to be defined if
the compiler does not support {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions]. This is ensures that objects of `class endian_buffer` are PODs, and
so can be used in {cpp}03 unions. In {cpp}11, `class endian_buffer` objects are
PODs, even though they have constructors, so can always be used in unions.

36
doc/endian/changelog.adoc
View File

@@ -10,32 +10,36 @@ http://www.boost.org/LICENSE_1_0.txt
[#changelog] [#changelog]
# Revision History # Revision History
## Changes in 1.84.0
* {cpp}03 is no longer supported.
## Changes in 1.75.0 ## Changes in 1.75.0
* `endian_arithmetic` no longer inherits from `endian_buffer` * `endian_arithmetic` no longer inherits from `endian_buffer`.
* When `BOOST_ENDIAN_NO_CTORS` is defined, the unaligned `endian_buffer` and * When `BOOST_ENDIAN_NO_CTORS` is defined, the unaligned `endian_buffer` and
`endian_arithmetic` are {cpp}03 PODs, to enable use of `++__attribute__((packed))++` `endian_arithmetic` are {cpp}03 PODs, to enable use of `++__attribute__((packed))++`.
## Changes in 1.74.0 ## Changes in 1.74.0
* Enabled scoped enumeration types in `endian_reverse` * Enabled scoped enumeration types in `endian_reverse`.
* Enabled `bool`, `enum`, `float`, `double` in `endian_reverse_inplace` * Enabled `bool`, `enum`, `float`, `double` in `endian_reverse_inplace`.
* Added an overload of `endian_reverse_inplace` for arrays * Added an overload of `endian_reverse_inplace` for arrays.
## 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`
on GCC and Clang on GCC and Clang.
* Added convenience load and store functions * Added convenience load and store functions.
* Added floating point convenience typedefs * Added floating point convenience typedefs.
* Added a non-const overload of `data()`; changed its return type to `unsigned char*` * Added a non-const overload of `data()`; changed its return type to `unsigned char*`.
* Added `__int128` support to `endian_reverse` when available * Added `__int128` support to `endian_reverse` when available.
* Added a convenience header `boost/endian.hpp` * Added a convenience header `boost/endian.hpp`.
## Changes in 1.71.0 ## Changes in 1.71.0
* Clarified requirements on the value type template parameter * Clarified requirements on the value type template parameter.
* Added support for `float` and `double` to `endian_buffer` and `endian_arithmetic` * Added support for `float` and `double` to `endian_buffer` and `endian_arithmetic`.
* Added `endian_load`, `endian_store` * Added `endian_load`, `endian_store`.
* Updated `endian_reverse` to correctly support all non-`bool` integral types * Updated `endian_reverse` to correctly support all non-`bool` integral types.
* Moved deprecated names to the deprecated header `endian.hpp` * Moved deprecated names to the deprecated header `endian.hpp`.

4
doc/endian/conversion.adoc
View File

@@ -17,9 +17,7 @@ big, or little endian byte ordering. User defined types are also supported.
## Reference ## Reference
Functions are implemented `inline` if appropriate. For {cpp}03 compilers, Functions are implemented `inline` if appropriate.
`noexcept` is elided. Boost scoped enum emulation is used so that the library
still works for compilers that do not support scoped enums.
### Definitions ### Definitions

28
doc/endian/overview.adoc
View File

@@ -110,9 +110,7 @@ sizes and aligned arithmetic types are provided for 16, 32, and 64-bit sizes.
The provided specific types are typedefs for a generic class template that may The provided specific types are typedefs for a generic class template that may
be used directly in generic code of for less common use cases. be used directly in generic code of for less common use cases.
Boost Endian is a header-only library. {cpp}11 features affecting interfaces, Boost Endian is a header-only library and requires {cpp}11.
such as `noexcept`, are used only if available. See
<<overview_cpp03_support,{cpp}03 support for {cpp}11 features>> for details.
[#overview_intrinsics] [#overview_intrinsics]
## Built-in support for Intrinsics ## Built-in support for Intrinsics
@@ -257,28 +255,6 @@ Iterations: 10'000'000'000, Intrinsics: `<cstdlib>` `_byteswap_ushort`, etc.
|64-bit aligned little endian |3.35 s |2.73 s |64-bit aligned little endian |3.35 s |2.73 s
|=== |===
[#overview_cpp03_support]
## {cpp}03 support for {cpp}11 features
[%header,cols=2*]
|===
|{cpp}11 Feature
|Action with {cpp}03 Compilers
|Scoped enums
|Uses header
http://www.boost.org/libs/core/doc/html/core/scoped_enum.html[boost/core/scoped_enum.hpp]
to emulate {cpp}11 scoped enums.
|`noexcept`
|Uses `BOOST_NOEXCEPT` macro, which is defined as null for compilers not
supporting this {cpp}11 feature.
|{cpp}11 PODs
(http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2342.htm[N2342])
|Takes advantage of {cpp}03 compilers that relax {cpp}03 POD rules, but see
Limitations <<buffers_limitations,here>> and <<arithmetic_limitations,here>>.
Also see macros for explicit POD control <<buffers_compilation,here>> and
<<arithmetic_compilation,here>>
|===
[#overview_faq] [#overview_faq]
## Overall FAQ ## Overall FAQ
@@ -286,7 +262,7 @@ Is the implementation header only?::
Yes. Yes.
Are {cpp}03 compilers supported?:: Are {cpp}03 compilers supported?::
Yes. No. {cpp}11 is required since release 1.84.
Does the implementation use compiler intrinsic built-in byte swapping?:: Does the implementation use compiler intrinsic built-in byte swapping?::
Yes, if available. See <<overview_intrinsics,Intrinsic built-in support>>. Yes, if available. See <<overview_intrinsics,Intrinsic built-in support>>.