boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2025-08-03 14:34:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

Finish conversion.hpp cleanup after name changes. conversion_test.cpp return-by-value tests reorganized and passing. UTD and in-place tests still to come. Add doc/bikeshed.txt to keep record of naming rationale.

Browse Source
This commit is contained in:
Beman
2014-11-24 10:04:23 -05:00
parent 4197f996ac
commit 56103a7bc6
3 changed files with 169 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
doc/bikeshed.txt Normal file
View File

@@ -0,0 +1,51 @@
Conversion function naming bikeshed
return-by-value modify-argument
------------------ ---------------
reverse_endianness reverse_endianness_in_place <-------
" reverse_endianness_arg
reverse reverse_in_place
reverse_endian reverse_endian_in_place
endian_reverse endian_reverse_in_place
swap_endianness swap_endianness_in_place
swap_endian swap_endian_in_place
endian_swap endian_swap_in_place
flip_endianness flip_endianness_in_place
flip_endian flip_endian_in_place
endian_flip endian_flip_in_place
reverse_order reverse_order_in_place
Key points:
* These names are defined in a user namespace as customization points to be found by
ADL, and so cannot depend on the enclosing namespace name to signal readers that they
are related to endianness.
* These functions are rarely called directly by user code, which is more likely to use
the various conditional functions instead. So explicitness is more important than
brevity.
merriam-webster.com/dictionary
reverse [1] (adjective): opposite or contrary to a previous or normal condition <reverse order>
reverse [2] (verb) : to change (something) to an opposite state or condition
swap (verb) : to give something to someone and receive something in return : to trade or exchange (things)
flip (verb)
: to turn (something) over by throwing it up in the air with a quick movement
: to cause (something) to turn or turn over quickly
: to move (something) with a quick light movement

100
include/boost/endian/conversion.hpp
View File

@@ -82,18 +82,21 @@ namespace endian
// Returns: x if native endian order is little, otherwise reverse_endianness(x) // Returns: x if native endian order is little, otherwise reverse_endianness(x)
// generic conditional reverse byte order // generic conditional reverse byte order
template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible>
class Reversible > inline Reversible conditional_reverse(Reversible from) BOOST_NOEXCEPT;
Reversible reverse_endianness(Reversible from) BOOST_NOEXCEPT; // Returns: If From == To have different values, from.
// Otherwise reverse_endianness(from).
// Remarks: The From == To test, and as a consequence which form the return takes, is
// is determined at compile time.
// runtime byte order determination
inline BOOST_SCOPED_ENUM(order) effective_order(BOOST_SCOPED_ENUM(order) o) BOOST_NOEXCEPT;
// Return: o if o != native, otherwise big or little depending on native ordering
// runtime conditional reverse byte order // runtime conditional reverse byte order
template <class Reversible > template <class Reversible >
Reversible reverse_endianness(Reversible from, BOOST_SCOPED_ENUM(order) from_order, inline Reversible runtime_conditional_reverse(Reversible from,
BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT; BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT;
// Returns: from_order == to_order ? from : reverse_endianness(from).
//------------------------------------------------------------------------------------//
// Q: What happended to bswap, htobe, and the other synonym functions based on names // Q: What happended to bswap, htobe, and the other synonym functions based on names
// popularized by BSD, OS X, and Linux? // popularized by BSD, OS X, and Linux?
@@ -147,26 +150,27 @@ namespace endian
inline void native_to_little_in_place(Reversible& x) BOOST_NOEXCEPT; inline void native_to_little_in_place(Reversible& x) BOOST_NOEXCEPT;
// Effects: none if native byte-order is little, otherwise reverse_endianness_in_place(x); // Effects: none if native byte-order is little, otherwise reverse_endianness_in_place(x);
// fully generic conditional reverse in place // generic conditional reverse in place
template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible> template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible>
void reverse_endianness_in_place(Reversible& x) BOOST_NOEXCEPT; inline void conditional_reverse_in_place(Reversible& x) BOOST_NOEXCEPT;
// runtime reverse in place // runtime reverse in place
template <class Reversible> template <class Reversible>
void reverse_endianness_in_place(Reversible& x, BOOST_SCOPED_ENUM(order) from_order, inline void runtime_conditional_reverse_in_place(Reversible& x,
BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT; BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order)
BOOST_NOEXCEPT;
//----------------------------------- end synopsis -------------------------------------// //----------------------------------- end synopsis -------------------------------------//
//--------------------------------------------------------------------------------------// //--------------------------------------------------------------------------------------//
// // // //
// implementation // // return-by-value implementation //
// // // //
// -- reverse portable approach suggested by tymofey, with avoidance of // // -- portable approach suggested by tymofey, with avoidance of undefined behavior //
// undefined behavior as suggested by Giovanni Piero Deretta, and a further // // as suggested by Giovanni Piero Deretta, with a further refinement suggested //
// refinement suggested by Pyry Jahkola. // // by Pyry Jahkola. //
// -- reverse intrinsic approach suggested by reviewers, and by David Stone, // // -- intrinsic approach suggested by reviewers, and by David Stone, who provided //
// who provided his Boost licensed macro implementation (detail/intrinsic.hpp) // // his Boost licensed macro implementation (detail/intrinsic.hpp) //
// // // //
//--------------------------------------------------------------------------------------// //--------------------------------------------------------------------------------------//
@@ -257,9 +261,13 @@ namespace endian
namespace detail namespace detail
{ {
// generic reverse function template implementation approach using std::reverse // generic reverse function template implementation approach using std::reverse
// suggested by Mathias Gaunard. // suggested by Mathias Gaunard. Primary motivation for inclusion is to have an
// independent implementation to test against. Secondary motivation is use by
// floating-point reverse_endianness, but that use is likely to be replace by a
// more tailored floating-point algorithm.
template <class T> template <class T>
inline T generic_reverse_endianness(T x) BOOST_NOEXCEPT inline T std_reverse_endianness(T x) BOOST_NOEXCEPT
{ {
T tmp(x); T tmp(x);
std::reverse( std::reverse(
@@ -272,15 +280,17 @@ namespace endian
inline float reverse_endianness(float x) BOOST_NOEXCEPT inline float reverse_endianness(float x) BOOST_NOEXCEPT
{ {
BOOST_STATIC_ASSERT_MSG(sizeof(float) == sizeof(uint32_t), BOOST_STATIC_ASSERT_MSG(sizeof(float) == sizeof(uint32_t),
"boost::endian only supprts sizeof(float) == 4; please report error to boost mailing list"); "boost::endian currently supports only sizeof(float) == 4;"
return detail::generic_reverse_endianness(x); " please report static_assert failure to the boost mailing list");
return detail::std_reverse_endianness(x);
} }
inline double reverse_endianness(double x) BOOST_NOEXCEPT inline double reverse_endianness(double x) BOOST_NOEXCEPT
{ {
BOOST_STATIC_ASSERT_MSG(sizeof(double) == sizeof(uint64_t), BOOST_STATIC_ASSERT_MSG(sizeof(double) == sizeof(uint64_t),
"boost::endian only supprts sizeof(double) == 8; please report error to boost mailing list"); "boost::endian currently supports only sizeof(double) == 8;"
return detail::generic_reverse_endianness(x); " please report static_assert failure to the boost mailing list");
return detail::std_reverse_endianness(x);
} }
template <class Reversible > template <class Reversible >
@@ -339,42 +349,29 @@ namespace endian
{public: T operator()(T x) BOOST_NOEXCEPT {return reverse_endianness(x);}}; {public: T operator()(T x) BOOST_NOEXCEPT {return reverse_endianness(x);}};
} }
// compile-time generic convert return by value // generic conditional reverse
template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible> template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible>
Reversible reverse_endianness(Reversible x) BOOST_NOEXCEPT inline Reversible conditional_reverse(Reversible from) BOOST_NOEXCEPT {
{
// work around lack of function template partial specialization by instantiating // work around lack of function template partial specialization by instantiating
// a function object of a class that is partially specialized on the two order // a function object of a class that is partially specialized on the two order
// template parameters, and then calling its operator(). // template parameters, and then calling its operator().
detail::value_converter <From, To, Reversible> tmp; detail::value_converter <From, To, Reversible> tmp;
return tmp(x); return tmp(from);
}
inline BOOST_SCOPED_ENUM(order)
effective_order(BOOST_SCOPED_ENUM(order) o) BOOST_NOEXCEPT
{
return o != order::native ? o :
# ifdef BOOST_LITTLE_ENDIAN
order::little
# else
order::big
# endif
;
} }
// runtime conditional reverse
template <class Reversible > template <class Reversible >
Reversible reverse_endianness(Reversible from, inline Reversible runtime_conditional_reverse(Reversible from,
BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT
{ {
return effective_order(from_order) == effective_order(to_order) return from_order == to_order ? from : reverse_endianness(from);
? from : reverse_endianness(from);
} }
//--------------------------------------------------------------------------------------// //--------------------------------------------------------------------------------------//
// reverse in place implementation // // reverse-in-place implementation //
//--------------------------------------------------------------------------------------// //--------------------------------------------------------------------------------------//
// reverse byte-order in place (i.e. flip endianness) // customization for built-in arithmetic types
inline void reverse_endianness_in_place(int8_t& x) BOOST_NOEXCEPT inline void reverse_endianness_in_place(int8_t& x) BOOST_NOEXCEPT
{ x = reverse_endianness(x); } { x = reverse_endianness(x); }
inline void reverse_endianness_in_place(int16_t& x) BOOST_NOEXCEPT inline void reverse_endianness_in_place(int16_t& x) BOOST_NOEXCEPT
@@ -449,9 +446,9 @@ namespace endian
{public: void operator()(T& x) BOOST_NOEXCEPT { reverse_endianness_in_place(x); }}; {public: void operator()(T& x) BOOST_NOEXCEPT { reverse_endianness_in_place(x); }};
} // namespace detail } // namespace detail
// fully generic conditional reverse in place // generic conditional reverse in place
template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible> template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible>
void reverse_endianness_in_place(Reversible& x) BOOST_NOEXCEPT inline void conditional_reverse_in_place(Reversible& x) BOOST_NOEXCEPT
{ {
// work around lack of function template partial specialization by instantiating // work around lack of function template partial specialization by instantiating
// a function object of a class that is partially specialized on the two order // a function object of a class that is partially specialized on the two order
@@ -462,10 +459,11 @@ namespace endian
// runtime reverse in place // runtime reverse in place
template <class Reversible> template <class Reversible>
void reverse_endianness_in_place(Reversible& x, BOOST_SCOPED_ENUM(order) from_order, inline void runtime_conditional_reverse_in_place(Reversible& x,
BOOST_SCOPED_ENUM(order) to_order) BOOST_NOEXCEPT BOOST_SCOPED_ENUM(order) from_order, BOOST_SCOPED_ENUM(order) to_order)
BOOST_NOEXCEPT
{ {
if (effective_order(from_order) != effective_order(to_order)) if (from_order != to_order)
reverse_endianness_in_place(x); reverse_endianness_in_place(x);
} }

126
test/conversion_test.cpp
View File

@@ -134,85 +134,97 @@ namespace
big_value(big); big_value(big);
little_value(little); little_value(little);
// one-way tests // validate the values used by the tests below
# ifdef BOOST_BIG_ENDIAN
BOOST_TEST_EQ(native, big);
BOOST_TEST_EQ(be::detail::std_reverse_endianness(native), little);
# else
BOOST_TEST_EQ(be::detail::std_reverse_endianness(native), big);
BOOST_TEST_EQ(native, little);
# endif
// unconditional reverse
BOOST_TEST_EQ(be::reverse_endianness(big), little); BOOST_TEST_EQ(be::reverse_endianness(big), little);
BOOST_TEST_EQ(be::reverse_endianness(little), big); BOOST_TEST_EQ(be::reverse_endianness(little), big);
// BOOST_TEST_EQ(be::reverse<T>(big), little);
// BOOST_TEST_EQ(be::reverse<T>(little), big);
// conditional reverse
BOOST_TEST_EQ(be::native_to_big(native), big); BOOST_TEST_EQ(be::native_to_big(native), big);
// BOOST_TEST_EQ(be::native_to_big<T>(native), big);
BOOST_TEST_EQ(be::native_to_little(native), little); BOOST_TEST_EQ(be::native_to_little(native), little);
// BOOST_TEST_EQ(be::native_to_little<T>(native), little); BOOST_TEST_EQ(be::big_to_native(big), native);
BOOST_TEST_EQ(be::little_to_native(little), native);
// round-trip tests // generic conditional reverse
BOOST_TEST_EQ(be::big_to_native(be::native_to_big(native)), native); BOOST_TEST_EQ((be::conditional_reverse<be::order::big, be::order::big>(big)), big);
BOOST_TEST_EQ(be::native_to_big(be::big_to_native(big)), big); BOOST_TEST_EQ((be::conditional_reverse<be::order::little,
BOOST_TEST_EQ(be::big_to_native(be::native_to_big(little)), little);
BOOST_TEST_EQ(be::little_to_native(be::native_to_little(native)), native);
BOOST_TEST_EQ(be::little_to_native(be::native_to_little(big)), big);
BOOST_TEST_EQ(be::little_to_native(be::native_to_little(little)), little);
# ifdef BOOST_BIG_ENDIAN
BOOST_TEST_EQ(be::reverse_endianness(native), little);
// BOOST_TEST_EQ(be::detail::reverse<T>(native), little);
BOOST_TEST_EQ(be::big_to_native(big), big);
// BOOST_TEST_EQ(be::big_endian<T>(big), big);
BOOST_TEST_EQ(be::little_to_native(little), little);
// BOOST_TEST_EQ(be::big_endian<T>(little), little);
# else
BOOST_TEST_EQ(be::reverse_endianness(native), big);
// BOOST_TEST_EQ(be::detail::reverse<T>(native), big);
BOOST_TEST_EQ(be::big_to_native(big), little);
// BOOST_TEST_EQ(be::big_endian<T>(big), little);
BOOST_TEST_EQ(be::native_to_big(little), big);
// BOOST_TEST_EQ(be::big_endian<T>(little), big);
# endif
// compile time order determination test
BOOST_TEST_EQ((be::reverse_endianness<be::order::big, be::order::big>(big)), big);
BOOST_TEST_EQ((be::reverse_endianness<be::order::little,
be::order::little>(little)), little); be::order::little>(little)), little);
BOOST_TEST_EQ((be::reverse_endianness<be::order::native, BOOST_TEST_EQ((be::conditional_reverse<be::order::native,
be::order::native>(native)), native); be::order::native>(native)), native);
BOOST_TEST_EQ((be::reverse_endianness<be::order::big, BOOST_TEST_EQ((be::conditional_reverse<be::order::big,
be::order::little>(big)), little); be::order::little>(big)), little);
BOOST_TEST_EQ((be::reverse_endianness<be::order::big, BOOST_TEST_EQ((be::conditional_reverse<be::order::big,
be::order::native>(big)), native); be::order::native>(big)), native);
BOOST_TEST_EQ((be::reverse_endianness<be::order::little, BOOST_TEST_EQ((be::conditional_reverse<be::order::little,
be::order::big>(little)), big); be::order::big>(little)), big);
BOOST_TEST_EQ((be::reverse_endianness<be::order::little, BOOST_TEST_EQ((be::conditional_reverse<be::order::little,
be::order::native>(little)), native); be::order::native>(little)), native);
BOOST_TEST_EQ((be::reverse_endianness<be::order::native, BOOST_TEST_EQ((be::conditional_reverse<be::order::native,
be::order::big>(native)), big); be::order::big>(native)), big);
BOOST_TEST_EQ((be::reverse_endianness<be::order::native, BOOST_TEST_EQ((be::conditional_reverse<be::order::native,
be::order::little>(native)), little); be::order::little>(native)), little);
// runtime order determination test // runtime conditional reverse
BOOST_TEST_EQ((be::reverse_endianness(big, be::order::big, be::order::big)), big); BOOST_TEST_EQ((be::runtime_conditional_reverse(big, be::order::big, be::order::big)),
BOOST_TEST_EQ((be::reverse_endianness(little, be::order::little, big);
BOOST_TEST_EQ((be::runtime_conditional_reverse(little, be::order::little,
be::order::little)), little); be::order::little)), little);
BOOST_TEST_EQ((be::reverse_endianness(native, be::order::native, BOOST_TEST_EQ((be::runtime_conditional_reverse(native, be::order::native,
be::order::native)), native); be::order::native)), native);
BOOST_TEST_EQ((be::reverse_endianness(big, be::order::big, be::order::little)), BOOST_TEST_EQ((be::runtime_conditional_reverse(big, be::order::big,
little); be::order::little)), little);
BOOST_TEST_EQ((be::reverse_endianness(big, be::order::big, be::order::native)), BOOST_TEST_EQ((be::runtime_conditional_reverse(big, be::order::big,
native); be::order::native)), native);
BOOST_TEST_EQ((be::reverse_endianness(little, be::order::little, be::order::big)), BOOST_TEST_EQ((be::runtime_conditional_reverse(little, be::order::little,
big); be::order::big)), big);
BOOST_TEST_EQ((be::reverse_endianness(little, be::order::little, be::order::native)), BOOST_TEST_EQ((be::runtime_conditional_reverse(little, be::order::little,
native); be::order::native)), native);
BOOST_TEST_EQ((be::reverse_endianness(native, be::order::native, be::order::big)), BOOST_TEST_EQ((be::runtime_conditional_reverse(native, be::order::native,
big); be::order::big)), big);
BOOST_TEST_EQ((be::reverse_endianness(native, be::order::native, be::order::little)), BOOST_TEST_EQ((be::runtime_conditional_reverse(native, be::order::native,
little); be::order::little)), little);
// // round-trip tests
//
// BOOST_TEST_EQ(be::big_to_native(be::native_to_big(native)), native);
// BOOST_TEST_EQ(be::native_to_big(be::big_to_native(big)), big);
// BOOST_TEST_EQ(be::big_to_native(be::native_to_big(little)), little);
//
// BOOST_TEST_EQ(be::little_to_native(be::native_to_little(native)), native);
// BOOST_TEST_EQ(be::little_to_native(be::native_to_little(big)), big);
// BOOST_TEST_EQ(be::little_to_native(be::native_to_little(little)), little);
//
//# ifdef BOOST_BIG_ENDIAN
// BOOST_TEST_EQ(be::reverse_endianness(native), little);
// BOOST_TEST_EQ(be::detail::reverse<T>(native), little);
// BOOST_TEST_EQ(be::big_to_native(big), big);
// BOOST_TEST_EQ(be::big_endian<T>(big), big);
// BOOST_TEST_EQ(be::little_to_native(little), little);
// BOOST_TEST_EQ(be::big_endian<T>(little), little);
//# else // little endian
// BOOST_TEST_EQ(be::reverse_endianness(native), big);
// BOOST_TEST_EQ(be::detail::std_reverse_endianness<T>(native), big);
// BOOST_TEST_EQ(be::big_to_native(big), little);
//// BOOST_TEST_EQ(be::big_endian<T>(big), little);
// BOOST_TEST_EQ(be::native_to_big(little), big);
//// BOOST_TEST_EQ(be::big_endian<T>(little), big);
//# endif
// // light test of modify-in-place functions // // light test of modify-in-place functions
// //