From ac46dae0cc053c6e1e5bc447256667263ea5436a Mon Sep 17 00:00:00 2001 From: Beman Date: Sat, 18 May 2013 16:53:27 -0400 Subject: [PATCH] Start rework of synopsis. --- doc/conversion.html | 111 +++++++++++++++++++++++++++++++++----------- 1 file changed, 83 insertions(+), 28 deletions(-) diff --git a/doc/conversion.html b/doc/conversion.html index b45bb1c..af1e350 100644 --- a/doc/conversion.html +++ b/doc/conversion.html @@ -56,9 +56,9 @@

Introduction

Header boost/endian/conversion.hpp -provides functions that convert built-in -integers between native byte ordering and big or little endian byte -ordering.

+provides byte reverse and conversion functions that convert built-in +integers, float, and double between native byte ordering and big or little endian byte +ordering. User defined types are also supported.

Reference

@@ -69,37 +69,92 @@ ordering.

{ namespace endian { - // unconditional modifying (i.e. in-place) reverse byte order + enum class order {big, little, native}; - inline void reorder(int16_t& x); - inline void reorder(int32_t& x); - inline void reorder(int64_t& x); - inline void reorder(uint16_t& x); - inline void reorder(uint32_t& x); - inline void reorder(uint64_t& x); + // reverse byte order (i.e. endianness) + // + inline int16_t reverse_value(int16_t x) noexcept; + inline int32_t reverse_value(int32_t x) noexcept; + inline int64_t reverse_value(int64_t x) noexcept; + inline uint16_t reverse_value(uint16_t x) noexcept; + inline uint32_t reverse_value(uint32_t x) noexcept; + inline uint64_t reverse_value(uint64_t x) noexcept; + inline float reverse_value(float x) noexcept; + inline double reverse_value(double x) noexcept; - // unconditional non-modifying reverse byte order copy + // reverse bytes unless native endianness is big + // + template <class ReversibleValue > + inline ReversibleValue big_endian_value(ReversibleValue x) noexcept; - inline void reorder(int16_t source, int16_t& target); - inline void reorder(int32_t source, int32_t& target); - inline void reorder(int64_t source, int64_t& target); - inline void reorder(uint16_t source, uint16_t& target); - inline void reorder(uint32_t source, uint32_t& target); - inline void reorder(uint64_t source, uint64_t& target); + // reverse bytes unless native endianness is little + // + template <class ReversibleValue > + inline ReversibleValue little_endian_value(ReversibleValue x) noexcept; - // conditional modifying (i.e. in-place) reverse byte order + // synonyms, based on names popularized by BSD (e.g. OS X, Linux) + // "h" stands for "host" (i.e. native), "be" for "big endian", "le" for "little endian" + // + template <class T> T bswap(T x) {return reverse_value(x);} + template <class T> T htobe(T host) {return big_endian_value(host);} + template <class T> T htole(T host) {return little_endian_value(host);} + template <class T> T betoh(T big) {return big_endian_value(big);} + template <class T> T letoh(T little) {return little_endian_value(little);} - template <class T> void native_to_big(T& x); - template <class T> void native_to_little(T& x); - template <class T> void big_to_native(T& x); - template <class T> void little_to_native(T& x); + // compile-time generic byte order conversion + template <order From, order To, class ReversibleValue> + ReversibleValue convert_value(ReversibleValue from) noexcept; - // non-modifying conditional reverse byte order copy + // runtime actual byte-order determination + order actual_order(order o) noexcept; - template <class T> void native_to_big(T source, T& target); - template <class T> void native_to_little(T source, T& target); - template <class T> void big_to_native(T source, T& target); - template <class T> void little_to_native(T source, T& target); + // runtime byte-order conversion + template <class ReversibleValue> + ReversibleValue convert_value(ReversibleValue from, + order from_order, order to_order) noexcept; + +//--------------------------------------------------------------------------------------// +// modify in place interface // +//--------------------------------------------------------------------------------------// + +// reverse byte order (i.e. endianness) +// +inline void reverse(int16_t& x) noexcept; +inline void reverse(int32_t& x) noexcept; +inline void reverse(int64_t& x) noexcept; +inline void reverse(uint16_t& x) noexcept; +inline void reverse(uint32_t& x) noexcept; +inline void reverse(uint64_t& x) noexcept; +inline void reverse(float& x) noexcept; +inline void reverse(double& x) noexcept; + +// reverse unless native endianness is big +template <class Reversible> +inline void big_endian(Reversible& x) noexcept; +// Effects: none if native endian order is big, otherwise reverse(x) + +// reverse unless native endianness is little +template <class Reversible> +inline void little_endian(Reversible& x) noexcept; +// Effects: none if native endian order is little, otherwise reverse(x); + +// synonyms based on names popularized by BSD, e.g. OS X, Linux. +// "h" stands for "host" (i.e. native), "be" for "big endian", +// "le" for "little endian", "m" for "modify in place" +template <class T> void mbswap(T& x) {reverse(x);} +template <class T> void mhtobe(T& host_) {big_endian(host_);} +template <class T> void mhtole(T& host_) {little_endian(host_);} +template <class T> void mbetoh(T& big_endian_) {big_endian(big_endian_);} +template <class T> void mletoh(T& little_endian_) {little_endian(little_endian_);} + +// compile-time generic byte order conversion +template <BOOST_SCOPED_ENUM(order) From, BOOST_SCOPED_ENUM(order) To, class Reversible> +void convert(Reversible& x) noexcept; + +// runtime byte-order conversion +template <class Reversible> +void convert(Reversible& x, BOOST_SCOPED_ENUM(order) from_order, +BOOST_SCOPED_ENUM(order) to_order) noexcept; } // namespace endian } // namespace boost @@ -159,7 +214,7 @@ little_to_native(x, y); // if native ordering is big-endian, reorder(x, y), support endian conversion as separate from endian types.

Last revised: -05 September, 2011

+18 May, 2013

© Copyright Beman Dawes, 2011

Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt