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
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
* Big endian| little endian | native endian byte ordering.
@@ -224,8 +214,6 @@ namespace boost
{
namespace endian
{
// C++11 features emulated if not available
enum class align { no, yes };
template <order Order, class T, std::size_t n_bits,
@@ -236,8 +224,9 @@ namespace boost
typedef T value_type;
// if BOOST_ENDIAN_FORCE_PODNESS is defined && C++11 PODs are not
// available then these two constructors will not be present
// if BOOST_ENDIAN_NO_CTORS is defined, these two
// constructors will not be present
endian_arithmetic() noexcept = default;
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
```
endian_arithmetic() noexcept = default; // C++03: endian(){}
endian_arithmetic() noexcept = default;
```
[none]
* {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.
Are endian types PODs?::
Yes for {cpp}11. No for {cpp}03, although several
<<arithmetic_compilation,macros>> are available to force PODness in all cases.
What are the implications of endian integer types not being PODs with {cpp}03 compilers?::
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.
Yes for the {cpp}11 definition of POD. No for the {cpp}03 definition of POD,
although the <<arithmetic_compilation,macro>> `BOOST_ENDIAN_NO_CTORS` can be
used to disable the constructors and to force {cpp}03 PODness (which is
required, for example, by the GCC `++__attribute__((packed))++` extension.)
What good is native endianness?::
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
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
Boost.Endian is implemented entirely within headers, with no need to link to any
Boost object libraries.
Several macros allow user control over features:
* BOOST_ENDIAN_NO_CTORS causes `class endian_arithmetic` to have no
constructors. The intended use is for compiling user code that must be 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_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.
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`
is a {cpp}03 POD. This is required, for example, by the GCC
`++__attribute__((packed))++` extension.
## 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
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
* Big endian| little endian | native endian byte ordering.
@@ -215,8 +205,6 @@ namespace boost
{
namespace endian
{
// C++11 features emulated if not available
enum class align { no, yes };
template <order Order, class T, std::size_t Nbits,
@@ -227,6 +215,9 @@ namespace boost
typedef T value_type;
// if BOOST_ENDIAN_NO_CTORS is defined, these two
// constructors will not be present
endian_buffer() noexcept = default;
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.
Are endian types PODs?::
Yes for {cpp}11. No for {cpp}03, although several
<<buffers_compilation,macros>> are available to force PODness in all cases.
What are the implications of endian integer types not being PODs with {cpp}03 compilers?::
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.
Yes for the {cpp}11 definition of POD. No for the {cpp}03 definition of POD,
although the <<buffers_compilation,macro>> `BOOST_ENDIAN_NO_CTORS` can be
used to disable the constructors and to force {cpp}03 PODness (which is
required, for example, by the GCC `++__attribute__((packed))++` extension.)
What good is native endianness?::
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
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
Boost.Endian is implemented entirely within headers, with no need to link to
any Boost object libraries.
Several macros allow user control over features:
* `BOOST_ENDIAN_NO_CTORS` causes `class endian_buffer` to have no
constructors. The intended use is for compiling user code that must be
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.
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`
is a {cpp}03 POD. This is required, for example, by the GCC
`++__attribute__((packed))++` extension.

36
doc/endian/changelog.adoc
View File

@@ -10,32 +10,36 @@ http://www.boost.org/LICENSE_1_0.txt
[#changelog]
# Revision History
## Changes in 1.84.0
* {cpp}03 is no longer supported.
## 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
`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
* Enabled scoped enumeration types in `endian_reverse`
* Enabled `bool`, `enum`, `float`, `double` in `endian_reverse_inplace`
* Added an overload of `endian_reverse_inplace` for arrays
* Enabled scoped enumeration types in `endian_reverse`.
* Enabled `bool`, `enum`, `float`, `double` in `endian_reverse_inplace`.
* Added an overload of `endian_reverse_inplace` for arrays.
## Changes in 1.72.0
* Made `endian_reverse`, `conditional_reverse` and `\*\_to_*` `constexpr`
on GCC and Clang
* Added convenience load and store functions
* Added floating point convenience typedefs
* Added a non-const overload of `data()`; changed its return type to `unsigned char*`
* Added `__int128` support to `endian_reverse` when available
* Added a convenience header `boost/endian.hpp`
on GCC and Clang.
* Added convenience load and store functions.
* Added floating point convenience typedefs.
* Added a non-const overload of `data()`; changed its return type to `unsigned char*`.
* Added `__int128` support to `endian_reverse` when available.
* Added a convenience header `boost/endian.hpp`.
## Changes in 1.71.0
* Clarified requirements on the value type template parameter
* Added support for `float` and `double` to `endian_buffer` and `endian_arithmetic`
* Added `endian_load`, `endian_store`
* Updated `endian_reverse` to correctly support all non-`bool` integral types
* Moved deprecated names to the deprecated header `endian.hpp`
* Clarified requirements on the value type template parameter.
* Added support for `float` and `double` to `endian_buffer` and `endian_arithmetic`.
* Added `endian_load`, `endian_store`.
* Updated `endian_reverse` to correctly support all non-`bool` integral types.
* 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
Functions are implemented `inline` if appropriate. For {cpp}03 compilers,
`noexcept` is elided. Boost scoped enum emulation is used so that the library
still works for compilers that do not support scoped enums.
Functions are implemented `inline` if appropriate.
### 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
be used directly in generic code of for less common use cases.
Boost Endian is a header-only library. {cpp}11 features affecting interfaces,
such as `noexcept`, are used only if available. See
<<overview_cpp03_support,{cpp}03 support for {cpp}11 features>> for details.
Boost Endian is a header-only library and requires {cpp}11.
[#overview_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
|===
[#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]
## Overall FAQ
@@ -286,7 +262,7 @@ Is the implementation header only?::
Yes.
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?::
Yes, if available. See <<overview_intrinsics,Intrinsic built-in support>>.