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
2019-04-28 20:41:55 +03:00
parent ff59429171
commit f2dc045c43
2 changed files with 134 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
doc/endian/arithmetic.adoc
View File

@ -32,7 +32,7 @@ semantics.
Unary arithmetic operators are `+`, `-`, `~`, `!`, plus both prefix and postfix Unary arithmetic operators are `+`, `-`, `~`, `!`, plus both prefix and postfix
`--` and `++`. Binary arithmetic operators are `+`, `+=`, `-`, `-=`, `\*`, `--` and `++`. Binary arithmetic operators are `+`, `+=`, `-`, `-=`, `\*`,
``*=``, `/`, `/=`, `&`, `&=`, `|`, `|=`, `^`, `^=`, `<<`, `<\<=`, `>>`, and ``*=``, `/`, `/=`, `&`, `&=`, `|`, `|=`, `^`, `^=`, `<<`, `<\<=`, `>>`, and
`>>=`. Binary relational operators are `==`, `!=`, `<`, `<=`, `>`, and `>=`. `>>=`. Binary relational operators are `==`, `!=`, `<`, `\<=`, `>`, and `>=`.
Implicit conversion to the underlying value type is provided. An implicit 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.
@ -95,7 +95,7 @@ int main(int, char* [])
return 1; return 1;
} }
if (std::fwrite(&h, sizeof(header), 1, fi)!= 1) if (std::fwrite(&h, sizeof(header), 1, fi) != 1)
{ {
std::cout << "write failure for " << filename << '\n'; std::cout << "write failure for " << filename << '\n';
return 1; return 1;
@ -169,17 +169,17 @@ common use cases:
[%header,cols=5*] [%header,cols=5*]
|=== |===
|Name |Alignment |Endianness |Sign |Sizes in bits (n) |Name |Alignment |Endianness |Sign |Sizes in bits (n)
|big_intn_t |no |big |signed |8,16,24,32,40,48,56,64 |`big_intN_t` |no |big |signed |8,16,24,32,40,48,56,64
|big_uintn_t |no |big |unsigned |8,16,24,32,40,48,56,64 |`big_uintN_t` |no |big |unsigned |8,16,24,32,40,48,56,64
|little_intn_t |no |little |signed |8,16,24,32,40,48,56,64 |`little_intN_t` |no |little |signed |8,16,24,32,40,48,56,64
|little_uintn_t |no |little |unsigned |8,16,24,32,40,48,56,64 |`little_uintN_t` |no |little |unsigned |8,16,24,32,40,48,56,64
|native_intn_t |no |native |signed |8,16,24,32,40,48,56,64 |`native_intN_t` |no |native |signed |8,16,24,32,40,48,56,64
|native_uintn_t |no |native |unsigned |8,16,24,32,40,48,56,64 |`native_uintN_t` |no |native |unsigned |8,16,24,32,40,48,56,64
|big_intn_at |yes |big |signed |8,16,32,64 |`big_intN_at` |yes |big |signed |8,16,32,64
|big_uintn_at |yes |big |unsigned |8,16,32,64 |`big_uintN_at` |yes |big |unsigned |8,16,32,64
|little_intn_at |yes |little |signed |8,16,32,64 |`little_intN_at` |yes |little |signed |8,16,32,64
|little_uintn_at |yes |little |unsigned |8,16,32,64 |`little_uintN_at` |yes |little |unsigned |8,16,32,64
|=== |===
The unaligned types do not cause compilers to insert padding bytes in classes The unaligned types do not cause compilers to insert padding bytes in classes
@ -217,7 +217,6 @@ are supplied.
### Synopsis ### Synopsis
``` ```
#include <boost/endian/conversion.hpp>
#include <boost/endian/buffers.hpp> #include <boost/endian/buffers.hpp>
namespace boost namespace boost
@ -248,76 +247,74 @@ namespace boost
// arithmetic operations // arithmetic operations
// note that additional operations are provided by the value_type // note that additional operations are provided by the value_type
value_type operator+(const endian& x) noexcept; value_type operator+() const noexcept;
endian& operator+=(endian& x, value_type y) noexcept; endian_arithmetic& operator+=(value_type y) noexcept;
endian& operator-=(endian& x, value_type y) noexcept; endian_arithmetic& operator-=(value_type y) noexcept;
endian& operator*=(endian& x, value_type y) noexcept; endian_arithmetic& operator*=(value_type y) noexcept;
endian& operator/=(endian& x, value_type y) noexcept; endian_arithmetic& operator/=(value_type y) noexcept;
endian& operator%=(endian& x, value_type y) noexcept; endian_arithmetic& operator%=(value_type y) noexcept;
endian& operator&=(endian& x, value_type y) noexcept; endian_arithmetic& operator&=(value_type y) noexcept;
endian& operator|=(endian& x, value_type y) noexcept; endian_arithmetic& operator|=(value_type y) noexcept;
endian& operator^=(endian& x, value_type y) noexcept; endian_arithmetic& operator^=(value_type y) noexcept;
endian& operator<<=(endian& x, value_type y) noexcept; endian_arithmetic& operator<<=(value_type y) noexcept;
endian& operator>>=(endian& x, value_type y noexcept; endian_arithmetic& operator>>=(value_type y) noexcept;
value_type operator<<(const endian& x, value_type y) noexcept; endian_arithmetic& operator++() noexcept;
value_type operator>>(const endian& x, value_type y) noexcept; endian_arithmetic& operator--() noexcept;
endian& operator++(endian& x) noexcept; endian_arithmetic operator++(int) noexcept;
endian& operator--(endian& x) noexcept; endian_arithmetic operator--(int) noexcept;
endian operator++(endian& x, int) noexcept;
endian operator--(endian& x, int) noexcept;
// Stream inserter // Stream inserter
template <class charT, class traits> template <class charT, class traits>
friend std::basic_ostream<charT, traits>& friend std::basic_ostream<charT, traits>&
operator<<(std::basic_ostream<charT, traits>& os, const T& x); operator<<(std::basic_ostream<charT, traits>& os, const endian_arithmetic& x);
// Stream extractor // Stream extractor
template <class charT, class traits> template <class charT, class traits>
friend std::basic_istream<charT, traits>& friend std::basic_istream<charT, traits>&
operator>>(std::basic_istream<charT, traits>& is, T& x); operator>>(std::basic_istream<charT, traits>& is, endian_arithmetic& x);
}; };
// typedefs // typedefs
// unaligned big endian signed integer types // unaligned big endian signed integer types
typedef endian<order::big, int_least8_t, 8> big_int8_t; typedef endian_arithmetic<order::big, int_least8_t, 8> big_int8_t;
typedef endian<order::big, int_least16_t, 16> big_int16_t; typedef endian_arithmetic<order::big, int_least16_t, 16> big_int16_t;
typedef endian<order::big, int_least32_t, 24> big_int24_t; typedef endian_arithmetic<order::big, int_least32_t, 24> big_int24_t;
typedef endian<order::big, int_least32_t, 32> big_int32_t; typedef endian_arithmetic<order::big, int_least32_t, 32> big_int32_t;
typedef endian<order::big, int_least64_t, 40> big_int40_t; typedef endian_arithmetic<order::big, int_least64_t, 40> big_int40_t;
typedef endian<order::big, int_least64_t, 48> big_int48_t; typedef endian_arithmetic<order::big, int_least64_t, 48> big_int48_t;
typedef endian<order::big, int_least64_t, 56> big_int56_t; typedef endian_arithmetic<order::big, int_least64_t, 56> big_int56_t;
typedef endian<order::big, int_least64_t, 64> big_int64_t; typedef endian_arithmetic<order::big, int_least64_t, 64> big_int64_t;
// unaligned big endian unsigned integer types // unaligned big endian unsigned integer types
typedef endian<order::big, uint_least8_t, 8> big_uint8_t; typedef endian_arithmetic<order::big, uint_least8_t, 8> big_uint8_t;
typedef endian<order::big, uint_least16_t, 16> big_uint16_t; typedef endian_arithmetic<order::big, uint_least16_t, 16> big_uint16_t;
typedef endian<order::big, uint_least32_t, 24> big_uint24_t; typedef endian_arithmetic<order::big, uint_least32_t, 24> big_uint24_t;
typedef endian<order::big, uint_least32_t, 32> big_uint32_t; typedef endian_arithmetic<order::big, uint_least32_t, 32> big_uint32_t;
typedef endian<order::big, uint_least64_t, 40> big_uint40_t; typedef endian_arithmetic<order::big, uint_least64_t, 40> big_uint40_t;
typedef endian<order::big, uint_least64_t, 48> big_uint48_t; typedef endian_arithmetic<order::big, uint_least64_t, 48> big_uint48_t;
typedef endian<order::big, uint_least64_t, 56> big_uint56_t; typedef endian_arithmetic<order::big, uint_least64_t, 56> big_uint56_t;
typedef endian<order::big, uint_least64_t, 64> big_uint64_t; typedef endian_arithmetic<order::big, uint_least64_t, 64> big_uint64_t;
// unaligned little endian signed integer types // unaligned little endian signed integer types
typedef endian<order::little, int_least8_t, 8> little_int8_t; typedef endian_arithmetic<order::little, int_least8_t, 8> little_int8_t;
typedef endian<order::little, int_least16_t, 16> little_int16_t; typedef endian_arithmetic<order::little, int_least16_t, 16> little_int16_t;
typedef endian<order::little, int_least32_t, 24> little_int24_t; typedef endian_arithmetic<order::little, int_least32_t, 24> little_int24_t;
typedef endian<order::little, int_least32_t, 32> little_int32_t; typedef endian_arithmetic<order::little, int_least32_t, 32> little_int32_t;
typedef endian<order::little, int_least64_t, 40> little_int40_t; typedef endian_arithmetic<order::little, int_least64_t, 40> little_int40_t;
typedef endian<order::little, int_least64_t, 48> little_int48_t; typedef endian_arithmetic<order::little, int_least64_t, 48> little_int48_t;
typedef endian<order::little, int_least64_t, 56> little_int56_t; typedef endian_arithmetic<order::little, int_least64_t, 56> little_int56_t;
typedef endian<order::little, int_least64_t, 64> little_int64_t; typedef endian_arithmetic<order::little, int_least64_t, 64> little_int64_t;
// unaligned little endian unsigned integer types // unaligned little endian unsigned integer types
typedef endian<order::little, uint_least8_t, 8> little_uint8_t; typedef endian_arithmetic<order::little, uint_least8_t, 8> little_uint8_t;
typedef endian<order::little, uint_least16_t, 16> little_uint16_t; typedef endian_arithmetic<order::little, uint_least16_t, 16> little_uint16_t;
typedef endian<order::little, uint_least32_t, 24> little_uint24_t; typedef endian_arithmetic<order::little, uint_least32_t, 24> little_uint24_t;
typedef endian<order::little, uint_least32_t, 32> little_uint32_t; typedef endian_arithmetic<order::little, uint_least32_t, 32> little_uint32_t;
typedef endian<order::little, uint_least64_t, 40> little_uint40_t; typedef endian_arithmetic<order::little, uint_least64_t, 40> little_uint40_t;
typedef endian<order::little, uint_least64_t, 48> little_uint48_t; typedef endian_arithmetic<order::little, uint_least64_t, 48> little_uint48_t;
typedef endian<order::little, uint_least64_t, 56> little_uint56_t; typedef endian_arithmetic<order::little, uint_least64_t, 56> little_uint56_t;
typedef endian<order::little, uint_least64_t, 64> little_uint64_t; typedef endian_arithmetic<order::little, uint_least64_t, 64> little_uint64_t;
// unaligned native endian signed integer types // unaligned native endian signed integer types
typedef implementation-defined_int8_t native_int8_t; typedef implementation-defined_int8_t native_int8_t;
@ -340,28 +337,28 @@ namespace boost
typedef implementation-defined_uint64_t native_uint64_t; typedef implementation-defined_uint64_t native_uint64_t;
// aligned big endian signed integer types // aligned big endian signed integer types
typedef endian<order::big, int8_t, 8, align::yes> big_int8_at; typedef endian_arithmetic<order::big, int8_t, 8, align::yes> big_int8_at;
typedef endian<order::big, int16_t, 16, align::yes> big_int16_at; typedef endian_arithmetic<order::big, int16_t, 16, align::yes> big_int16_at;
typedef endian<order::big, int32_t, 32, align::yes> big_int32_at; typedef endian_arithmetic<order::big, int32_t, 32, align::yes> big_int32_at;
typedef endian<order::big, int64_t, 64, align::yes> big_int64_at; typedef endian_arithmetic<order::big, int64_t, 64, align::yes> big_int64_at;
// aligned big endian unsigned integer types // aligned big endian unsigned integer types
typedef endian<order::big, uint8_t, 8, align::yes> big_uint8_at; typedef endian_arithmetic<order::big, uint8_t, 8, align::yes> big_uint8_at;
typedef endian<order::big, uint16_t, 16, align::yes> big_uint16_at; typedef endian_arithmetic<order::big, uint16_t, 16, align::yes> big_uint16_at;
typedef endian<order::big, uint32_t, 32, align::yes> big_uint32_at; typedef endian_arithmetic<order::big, uint32_t, 32, align::yes> big_uint32_at;
typedef endian<order::big, uint64_t, 64, align::yes> big_uint64_at; typedef endian_arithmetic<order::big, uint64_t, 64, align::yes> big_uint64_at;
// aligned little endian signed integer types // aligned little endian signed integer types
typedef endian<order::little, int8_t, 8, align::yes> little_int8_at; typedef endian_arithmetic<order::little, int8_t, 8, align::yes> little_int8_at;
typedef endian<order::little, int16_t, 16, align::yes> little_int16_at; typedef endian_arithmetic<order::little, int16_t, 16, align::yes> little_int16_at;
typedef endian<order::little, int32_t, 32, align::yes> little_int32_at; typedef endian_arithmetic<order::little, int32_t, 32, align::yes> little_int32_at;
typedef endian<order::little, int64_t, 64, align::yes> little_int64_at; typedef endian_arithmetic<order::little, int64_t, 64, align::yes> little_int64_at;
// aligned little endian unsigned integer types // aligned little endian unsigned integer types
typedef endian<order::little, uint8_t, 8, align::yes> little_uint8_at; typedef endian_arithmetic<order::little, uint8_t, 8, align::yes> little_uint8_at;
typedef endian<order::little, uint16_t, 16, align::yes> little_uint16_at; typedef endian_arithmetic<order::little, uint16_t, 16, align::yes> little_uint16_at;
typedef endian<order::little, uint32_t, 32, align::yes> little_uint32_at; typedef endian_arithmetic<order::little, uint32_t, 32, align::yes> little_uint32_at;
typedef endian<order::little, uint64_t, 64, align::yes> little_uint64_at; typedef endian_arithmetic<order::little, uint64_t, 64, align::yes> little_uint64_at;
// aligned native endian typedefs are not provided because // aligned native endian typedefs are not provided because
// <cstdint> types are superior for that use case // <cstdint> types are superior for that use case
@ -373,10 +370,26 @@ namespace boost
The `implementation-defined` text above is either `big` or `little` according The `implementation-defined` text above is either `big` or `little` according
to the endianness of the platform. to the endianness of the platform.
The only supported value of `CHAR_BIT` is 8.
The valid values of `Nbits` are as follows:
* When `sizeof(T)` is 1, `Nbits` shall be 8;
* When `sizeof(T)` is 2, `Nbits` shall be 16;
* When `sizeof(T)` is 4, `Nbits` shall be 24 or 32;
* When `sizeof(T)` is 8, `Nbits` shall be 40, 48, 56, or 64.
Other values of `sizeof(T)` are not supported.
When `Nbits` is equal to `sizeof(T)*8`, `T` must be a standard arithmetic type.
When `Nbits` is less than `sizeof(T)*8`, `T` must be a standard integral type
({cpp}std, [basic.fundamental]) that is not `bool`.
### Members ### Members
``` ```
endian() = default; // C++03: endian(){} endian_arithmetic() = default; // C++03: endian(){}
``` ```
[none] [none]
* {blank} * {blank}
@ -385,7 +398,7 @@ Effects:: Constructs an uninitialized object of type
`endian_arithmetic<E, T, n_bits, A>`. `endian_arithmetic<E, T, n_bits, A>`.
``` ```
endian(T v); endian_arithmetic(T v);
``` ```
[none] [none]
* {blank} * {blank}
@ -394,7 +407,7 @@ Effects:: Constructs an object of type `endian_arithmetic<E, T, n_bits, A>`.
Postcondition:: `x == v,` where `x` is the constructed object. Postcondition:: `x == v,` where `x` is the constructed object.
``` ```
endian& operator=(T v); endian_arithmetic& operator=(T v);
``` ```
[none] [none]
* {blank} * {blank}
@ -429,7 +442,7 @@ Other operators on endian objects are forwarded to the equivalent operator on
``` ```
template <class charT, class traits> template <class charT, class traits>
friend std::basic_ostream<charT, traits>& friend std::basic_ostream<charT, traits>&
operator<<(std::basic_ostream<charT, traits>& os, const T& x); operator<<(std::basic_ostream<charT, traits>& os, const endian_arithmetic& x);
``` ```
[none] [none]
@ -443,7 +456,7 @@ Returns:: `os << +x`.
``` ```
template <class charT, class traits> template <class charT, class traits>
friend std::basic_istream<charT, traits>& friend std::basic_istream<charT, traits>&
operator>>(std::basic_istream<charT, traits>& is, T& x); operator>>(std::basic_istream<charT, traits>& is, endian_arithmetic& x);
``` ```
[none] [none]
* {blank} * {blank}

59
doc/endian/buffers.adoc
View File

@ -54,10 +54,10 @@ namespace
struct header struct header
{ {
big_int32_`buf_`t file_code; big_int32_buf_t file_code;
big_int32_`buf_`t file_length; big_int32_buf_t file_length;
little_int32_`buf_`t version; little_int32_buf_t version;
little_int32_`buf_`t shape_type; little_int32_buf_t shape_type;
}; };
const char* filename = "test.dat"; const char* filename = "test.dat";
@ -90,7 +90,7 @@ int main(int, char* [])
return 1; return 1;
} }
if (std::fwrite(&h, sizeof(header), 1, fi)!= 1) if (std::fwrite(&h, sizeof(header), 1, fi) != 1)
{ {
std::cout << "write failure for " << filename << '\n'; std::cout << "write failure for " << filename << '\n';
return 1; return 1;
@ -165,16 +165,16 @@ common use cases:
[%header,cols=5*] [%header,cols=5*]
|=== |===
|Name |Alignment |Endianness |Sign |Sizes in bits (n) |Name |Alignment |Endianness |Sign |Sizes in bits (n)
|big_intn_buf_t |no |big |signed |8,16,24,32,40,48,56,64 |`big_intN_buf_t` |no |big |signed |8,16,24,32,40,48,56,64
|big_uintn_buf_t |no |big |unsigned |8,16,24,32,40,48,56,64 |`big_uintN_buf_t` |no |big |unsigned |8,16,24,32,40,48,56,64
|little_intn_buf_t |no |little |signed |8,16,24,32,40,48,56,64 |`little_intN_buf_t` |no |little |signed |8,16,24,32,40,48,56,64
|little_uintn_buf_t |no |little |unsigned |8,16,24,32,40,48,56,64 |`little_uintN_buf_t` |no |little |unsigned |8,16,24,32,40,48,56,64
|native_intn_buf_t |no |native |signed |8,16,24,32,40,48,56,64 |`native_intN_buf_t` |no |native |signed |8,16,24,32,40,48,56,64
|native_uintn_buf_t |no |native |unsigned |8,16,24,32,40,48,56,64 |`native_uintN_buf_t` |no |native |unsigned |8,16,24,32,40,48,56,64
|big_intn_buf_at |yes |big |signed |8,16,32,64 |`big_intN_buf_at` |yes |big |signed |8,16,32,64
|big_uintn_buf_at |yes |big |unsigned |8,16,32,64 |`big_uintN_buf_at` |yes |big |unsigned |8,16,32,64
|little_intn_buf_at |yes |little |signed |8,16,32,64 |`little_intN_buf_at` |yes |little |signed |8,16,32,64
|little_uintn_buf_at |yes |little |unsigned |8,16,32,64 |`little_uintN_buf_at` |yes |little |unsigned |8,16,32,64
|=== |===
The unaligned types do not cause compilers to insert padding bytes in classes The unaligned types do not cause compilers to insert padding bytes in classes
@ -211,8 +211,6 @@ user-specified <<buffers_endianness,endianness>>, value type, size, and
### Synopsis ### Synopsis
``` ```
#include <boost/endian/conversion.hpp
namespace boost namespace boost
{ {
namespace endian namespace endian
@ -234,7 +232,8 @@ namespace boost
endian_buffer& operator=(T v) noexcept; endian_buffer& operator=(T v) noexcept;
value_type value() const noexcept; value_type value() const noexcept;
const char* data() const noexcept; const char* data() const noexcept;
protected:
private:
implementaton-defined endian_value; // for exposition only implementaton-defined endian_value; // for exposition only
}; };
@ -356,8 +355,20 @@ requirements imposed by the `Nbits` and `Align` template parameters. The
`CHAR_BIT` macro is defined in `<climits>`. The only value of `CHAR_BIT` macro is defined in `<climits>`. The only value of
`CHAR_BIT` that is required to be supported is 8. `CHAR_BIT` that is required to be supported is 8.
Template parameter `T` is required to be a standard integer type ({cpp}std, The valid values of `Nbits` are as follows:
3.9.1) and `sizeof(T)*CHAR_BIT` is required to be greater or equal to `Nbits`.
* When `sizeof(T)` is 1, `Nbits` shall be 8;
* When `sizeof(T)` is 2, `Nbits` shall be 16;
* When `sizeof(T)` is 4, `Nbits` shall be 24 or 32;
* When `sizeof(T)` is 8, `Nbits` shall be 40, 48, 56, or 64.
Other values of `sizeof(T)` are not supported.
When `Nbits` is equal to `sizeof(T)*8`, `T` must be a trivially copyable type
(such as `float`) that is assumed to have the same endianness as `uintNbits_t`.
When `Nbits` is less than `sizeof(T)*8`, `T` must be either a standard integral
type ({cpp}std, [basic.fundamental]) or an `enum`.
### Members ### Members
@ -406,7 +417,7 @@ Remarks:: If `Align` is `align::yes` then endianness conversion, if required, is
performed by `boost::endian::endian_reverse`. performed by `boost::endian::endian_reverse`.
``` ```
const char* data</a>() const noexcept; const char* data() const noexcept;
``` ```
[none] [none]
* {blank} * {blank}
@ -508,13 +519,13 @@ any Boost object libraries.
Several macros allow user control over features: Several macros allow user control over features:
* BOOST_ENDIAN_NO_CTORS causes `class endian_buffer` to have no * `BOOST_ENDIAN_NO_CTORS` causes `class endian_buffer` to have no
constructors. The intended use is for compiling user code that must be constructors. The intended use is for compiling user code that must be
portable between compilers regardless of {cpp}11 portable between compilers regardless of {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted
Functions] support. Use of constructors will always fail, Functions] support. Use of constructors will always fail,
* BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if the * `BOOST_ENDIAN_FORCE_PODNESS` causes `BOOST_ENDIAN_NO_CTORS` to be defined if
compiler does not support {cpp}11 the compiler does not support {cpp}11
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm[Defaulted 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 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 so can be used in {cpp}03 unions. In {cpp}11, `class endian_buffer` objects are