From 699cb133e867011ee6df6c8fe6e153568128d8e6 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Fri, 20 Oct 2023 02:28:24 +0300 Subject: [PATCH] Update documentation --- doc/endian/arithmetic.adoc | 55 +++++++++----------------------------- doc/endian/buffers.adoc | 51 ++++++++--------------------------- doc/endian/changelog.adoc | 36 ++++++++++++++----------- doc/endian/conversion.adoc | 4 +-- doc/endian/overview.adoc | 28 ++----------------- 5 files changed, 46 insertions(+), 128 deletions(-) diff --git a/doc/endian/arithmetic.adoc b/doc/endian/arithmetic.adoc index af726df..70a4e48 100644 --- a/doc/endian/arithmetic.adoc +++ b/doc/endian/arithmetic.adoc @@ -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 > 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 <> `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 diff --git a/doc/endian/buffers.adoc b/doc/endian/buffers.adoc index 3150d9b..7f7ab47 100644 --- a/doc/endian/buffers.adoc +++ b/doc/endian/buffers.adoc @@ -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 > 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 <> `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. diff --git a/doc/endian/changelog.adoc b/doc/endian/changelog.adoc index a6a260f..d46d721 100644 --- a/doc/endian/changelog.adoc +++ b/doc/endian/changelog.adoc @@ -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`. diff --git a/doc/endian/conversion.adoc b/doc/endian/conversion.adoc index 569bc6f..364556d 100644 --- a/doc/endian/conversion.adoc +++ b/doc/endian/conversion.adoc @@ -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 diff --git a/doc/endian/overview.adoc b/doc/endian/overview.adoc index 951c81f..066a584 100644 --- a/doc/endian/overview.adoc +++ b/doc/endian/overview.adoc @@ -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 -<> 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: `` `_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 <> and <>. -Also see macros for explicit POD control <> and -<> -|=== - [#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 <>.