From a114dd72b5f743ec9bb4754ac7d3086ebe10c950 Mon Sep 17 00:00:00 2001 From: bemandawes Date: Sat, 3 Sep 2011 17:50:46 +0000 Subject: [PATCH] Rename flip() to invert() git-svn-id: http://svn.boost.org/svn/boost/sandbox/endian@74214 b8fc166d-592f-0410-95f2-cb63ce0dd405 --- boost/endian/conversion.hpp | 66 ++++++++--------- libs/endian/doc/conversion.html | 107 ++++++++++++++++++--------- libs/endian/doc/index.html | 36 +++++++-- libs/endian/test/conversion_test.cpp | 104 +++++++++++++------------- libs/endian/test/msvc10/endian.sln | 2 +- 5 files changed, 189 insertions(+), 126 deletions(-) diff --git a/boost/endian/conversion.hpp b/boost/endian/conversion.hpp index 1bb5ed4..c079e07 100644 --- a/boost/endian/conversion.hpp +++ b/boost/endian/conversion.hpp @@ -19,24 +19,24 @@ namespace endian { // unconditional modifying (i.e. in-place) endianness reversal - inline void flip(int16_t& x); - inline void flip(int32_t& x); - inline void flip(int64_t& x); - inline void flip(uint16_t& x); - inline void flip(uint32_t& x); - inline void flip(uint64_t& x); + inline void invert(int16_t& x); + inline void invert(int32_t& x); + inline void invert(int64_t& x); + inline void invert(uint16_t& x); + inline void invert(uint32_t& x); + inline void invert(uint64_t& x); // unconditional non-modifying endianness reversing copy - inline void flip(int16_t source, int16_t& target); - inline void flip(int32_t source, int32_t& target); - inline void flip(int64_t source, int64_t& target); - inline void flip(uint16_t source, uint16_t& target); - inline void flip(uint32_t source, uint32_t& target); - inline void flip(uint64_t source, uint64_t& target); + inline void invert(int16_t source, int16_t& target); + inline void invert(int32_t source, int32_t& target); + inline void invert(int64_t source, int64_t& target); + inline void invert(uint16_t source, uint16_t& target); + inline void invert(uint32_t source, uint32_t& target); + inline void invert(uint64_t source, uint64_t& target); // conditional modifying (i.e. in-place) endianness reversal; - // no effect if native endianness and specified endianness are the same + // no effect if native endianness and indicated endianness are the same template inline void native_to_big(T& x); template inline void native_to_little(T& x); @@ -54,7 +54,7 @@ namespace endian //----------------------------------- implementation -----------------------------------// - inline void flip(int16_t& x) + inline void invert(int16_t& x) { char* rep = reinterpret_cast(&x); char tmp; @@ -63,7 +63,7 @@ namespace endian *(rep+1) = tmp; } - inline void flip(int32_t& x) + inline void invert(int32_t& x) { char* rep = reinterpret_cast(&x); char tmp; @@ -75,7 +75,7 @@ namespace endian *(rep+2) = tmp; } - inline void flip(int64_t& x) + inline void invert(int64_t& x) { char* rep = reinterpret_cast(&x); char tmp; @@ -93,7 +93,7 @@ namespace endian *(rep+4) = tmp; } - inline void flip(uint16_t& x) + inline void invert(uint16_t& x) { char* rep = reinterpret_cast(&x); char tmp; @@ -102,7 +102,7 @@ namespace endian *(rep+1) = tmp; } - inline void flip(uint32_t& x) + inline void invert(uint32_t& x) { char* rep = reinterpret_cast(&x); char tmp; @@ -114,7 +114,7 @@ namespace endian *(rep+2) = tmp; } - inline void flip(uint64_t& x) + inline void invert(uint64_t& x) { char* rep = reinterpret_cast(&x); char tmp; @@ -132,7 +132,7 @@ namespace endian *(rep+4) = tmp; } - inline void flip(int16_t source, int16_t& target) + inline void invert(int16_t source, int16_t& target) { const char* s (reinterpret_cast(&source)); char * t (reinterpret_cast(&target) + sizeof(target) - 1); @@ -140,7 +140,7 @@ namespace endian *--t = *++s; } - inline void flip(int32_t source, int32_t& target) + inline void invert(int32_t source, int32_t& target) { const char* s (reinterpret_cast(&source)); char * t (reinterpret_cast(&target) + sizeof(target) - 1); @@ -150,7 +150,7 @@ namespace endian *--t = *++s; } - inline void flip(int64_t source, int64_t& target) + inline void invert(int64_t source, int64_t& target) { const char* s (reinterpret_cast(&source)); char * t (reinterpret_cast(&target) + sizeof(target) - 1); @@ -164,7 +164,7 @@ namespace endian *--t = *++s; } - inline void flip(uint16_t source, uint16_t& target) + inline void invert(uint16_t source, uint16_t& target) { const char* s (reinterpret_cast(&source)); char * t (reinterpret_cast(&target) + sizeof(target) - 1); @@ -172,7 +172,7 @@ namespace endian *--t = *++s; } - inline void flip(uint32_t source, uint32_t& target) + inline void invert(uint32_t source, uint32_t& target) { const char* s (reinterpret_cast(&source)); char * t (reinterpret_cast(&target) + sizeof(target) - 1); @@ -182,7 +182,7 @@ namespace endian *--t = *++s; } - inline void flip(uint64_t source, uint64_t& target) + inline void invert(uint64_t source, uint64_t& target) { const char* s (reinterpret_cast(&source)); char * t (reinterpret_cast(&target) + sizeof(target) - 1); @@ -197,23 +197,23 @@ namespace endian } #ifdef BOOST_LITTLE_ENDIAN - template inline void native_to_big(T& x) { flip(x); } + template inline void native_to_big(T& x) { invert(x); } template inline void native_to_little(T&) {} - template inline void big_to_native(T& x) { flip(x); } + template inline void big_to_native(T& x) { invert(x); } template inline void little_to_native(T&) {} - template inline void native_to_big(T source, T& target) { flip(source, target); } + template inline void native_to_big(T source, T& target) { invert(source, target); } template inline void native_to_little(T source, T& target) { target = source; } - template inline void big_to_native(T source, T& target) { flip(source, target); } + template inline void big_to_native(T source, T& target) { invert(source, target); } template inline void little_to_native(T source, T& target) { target = source; } #else template inline void native_to_big(T&) {} - template inline void native_to_little(T& x) { flip(x); } + template inline void native_to_little(T& x) { invert(x); } template inline void big_to_native(T&) {} - template inline void little_to_native(T& x) { flip(x); } + template inline void little_to_native(T& x) { invert(x); } template inline void native_to_big(T native, T& big) { target = source; } - template inline void native_to_little(T native, T& little) { flip(source, target); } + template inline void native_to_little(T native, T& little) { invert(source, target); } template inline void big_to_native(T big, T& native) { target = source; } - template inline void little_to_native(T little, T& native) { flip(source, target); } + template inline void little_to_native(T little, T& native) { invert(source, target); } #endif } // namespace endian diff --git a/libs/endian/doc/conversion.html b/libs/endian/doc/conversion.html index 55937e9..acd1071 100644 --- a/libs/endian/doc/conversion.html +++ b/libs/endian/doc/conversion.html @@ -32,62 +32,103 @@

Introduction

-

 

+

Header boost/endian/conversion.hpp +provides functions that convert built-in +integers from the native byte ordering to or from big or little endian byte +ordering.

-

Header <boost/endian/conversion> -Synopsis

+

Reference

+ +

+Synopsis

namespace boost
 {
 namespace endian
 {
+  // invert: verb: put upside down or in the opposite position, order, or arrangement.
+
   // unconditional modifying (i.e. in-place) endianness reversal
 
-  inline void flip(int16_t& x);
-  inline void flip(int32_t& x);
-  inline void flip(int64_t& x);
-  inline void flip(uint16_t& x);
-  inline void flip(uint32_t& x);
-  inline void flip(uint64_t& x);
+  inline void invert(int16_t& x);
+  inline void invert(int32_t& x);
+  inline void invert(int64_t& x);
+  inline void invert(uint16_t& x);
+  inline void invert(uint32_t& x);
+  inline void invert(uint64_t& x);
 
   // unconditional non-modifying endianness reversing copy
 
-  inline void flip(int16_t source, int16_t& target);
-  inline void flip(int32_t source, int32_t& target);
-  inline void flip(int64_t source, int64_t& target);
-  inline void flip(uint16_t source, uint16_t& target);
-  inline void flip(uint32_t source, uint32_t& target);
-  inline void flip(uint64_t source, uint64_t& target);
+  inline void invert(int16_t source, int16_t& target);
+  inline void invert(int32_t source, int32_t& target);
+  inline void invert(int64_t source, int64_t& target);
+  inline void invert(uint16_t source, uint16_t& target);
+  inline void invert(uint32_t source, uint32_t& target);
+  inline void invert(uint64_t source, uint64_t& target);
 
-  // conditional modifying (i.e. in-place) endianness reversal;
-  //  no effect if native endianness and specified endianness are the same
+  // conditional modifying (i.e. in-place) endianness reversal
 
-  template <class T> inline void to_big(T& x);       // if different, convert native to big
-  template <class T> inline void to_little(T& x);    // if different, convert native to little
-  template <class T> inline void from_big(T& x);     // if different, convert big to native
-  template <class T> inline void from_little(T& x);  // if different, convert little to native
+  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);
 
-  // non-modifying copy, conditionally reversing endianness;
-  //   copy the first argument to the second argument, converting to or from the
-  //   specified endianness if different than native endianness
+  // non-modifying copy conditionally reversing endianness;
 
-  template <class T> inline void to_big(T native, T& big);
-  template <class T> inline void to_little(T native, T& little);
-  template <class T> inline void from_big(T big, T& native);
-  template <class T> inline void from_little(T little, T& native);
-
-
} // namespace endian
+  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);
+
+} // namespace endian
 } // namespace boost
+

Members

+
inline void invert(int16_t& x);
+inline void invert(int32_t& x);
+inline void invert(int64_t& x);
+inline void invert(uint16_t& x);
+inline void invert(uint32_t& x);
+inline void invert(uint64_t& x);
+
+

Effects: Reverses the byte order of x.

+
+
inline void invert(int16_t source, int16_t& target);
+inline void invert(int32_t source, int32_t& target);
+inline void invert(int64_t source, int64_t& target);
+inline void invert(uint16_t source, uint16_t& target);
+inline void invert(uint32_t source, uint32_t& target);
+inline void invert(uint64_t source, uint64_t& target);
+
+

Effects: Copies source to target, + reversing the byte order.

+
+
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);
+
+

Effects: If the native byte ordering and indicated byte + ordering are different, invert(x), otherwise no effect.

+
+
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);
+
+

Effects: If the native byte ordering and indicated byte + ordering are different, invert(source, target), otherwise + target = source.

+

Acknowledgements

+

Tomas Puverle was instrumental in identifying and articulating the need to +support endian conversion as separate from endian types.

Last revised: -27 May, 2011

+03 September, 2011

© Copyright Beman Dawes, 2011

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

-

 

- \ No newline at end of file diff --git a/libs/endian/doc/index.html b/libs/endian/doc/index.html index e3fd521..34ff36c 100644 --- a/libs/endian/doc/index.html +++ b/libs/endian/doc/index.html @@ -32,7 +32,7 @@

Introduction

-

The Boost Endian Library provides facilities to deal with endianness. See +

The Boost Endian Library provides facilities to deal with integer endianness. See Introduction to endianness below for the basics of endianness.

@@ -40,17 +40,21 @@ the basics of endianness.

-

Endian conversions for native integers - The application uses the -built-in integer types, and calls the provided conversion functions to swap -bytes as needed. Both mutating and non-mutating conversions are supplied, and +

Endian conversions for native integers - With this approach, the application uses the +built-in integer types, and calls the provided conversion functions to convert +byte ordering as needed. Both mutating and non-mutating conversions are supplied, and each comes in unconditional and conditional variants. This approach is simple and efficient, but is less flexible in terms of size and alignment, and can be -hard to manage in code with many logical paths involving endianness transitions.

+hard-to-manage and error-prone in code with many logical paths involving endianness transitions.

-

Endian integer types

+

Endian integer types - With this approach, the application uses the +provided endian classes which mimic the +built-in integer types. For example, big32_t or little64_t.

+

Boost Endian is header-only library.

+

Introduction to endianness

Consider a C++ program that defines variables x, y, and z as 16, 32, and @@ -190,9 +194,27 @@ details for many processors and operating systems.

External memory, such as disks, generally uses the same endianness as the operating system. Networks traditionally use big endian ordering, so this is sometimes referred as network endianness.

+

Acknowledgements

+

Comments and suggestions were +received from +Benaka Moorthi, +Christopher Kohlhoff, +Cliff Green, +Gennaro Proto, +Giovanni Piero Deretta, dizzy, Jeff Flinn, +John Maddock, +Kim Barrett, +Marsh Ray, +Martin Bonner, +Matias Capeletto, +Neil Mayhew, Phil Endecott, Rene Rivera, +Roland Schwarz, Scott McMurray, +Sebastian Redl, +Tomas Puverle, Vincente Botet, and +Yuval Ronen.

Last revised: -27 May, 2011

+03 September, 2011

© Copyright Beman Dawes, 2011

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

diff --git a/libs/endian/test/conversion_test.cpp b/libs/endian/test/conversion_test.cpp index f69a9f4..b824562 100644 --- a/libs/endian/test/conversion_test.cpp +++ b/libs/endian/test/conversion_test.cpp @@ -19,127 +19,127 @@ namespace be = boost::endian; namespace { - void test_in_place_flip() + void test_in_place_invert() { - std::cout << "test_in_place_flip...\n"; + std::cout << "test_in_place_invert...\n"; boost::int64_t i64 = 0x0102030405060708LL; - be::flip(i64); + be::invert(i64); BOOST_TEST_EQ(i64, 0x0807060504030201LL); - be::flip(i64); + be::invert(i64); BOOST_TEST_EQ(i64, 0x0102030405060708LL); i64 = 0xfefdfcfbfaf9f8f7LL; - be::flip(i64); + be::invert(i64); BOOST_TEST_EQ(i64, static_cast(0xf7f8f9fafbfcfdfeULL)); - be::flip(i64); + be::invert(i64); BOOST_TEST_EQ(i64, static_cast(0xfefdfcfbfaf9f8f7ULL)); boost::int32_t i32 = 0x01020304; - be::flip(i32); + be::invert(i32); BOOST_TEST_EQ(i32, 0x04030201); - be::flip(i32); + be::invert(i32); BOOST_TEST_EQ(i32, 0x01020304); i32 = 0xfefdfcfb; - be::flip(i32); + be::invert(i32); BOOST_TEST_EQ(i32, static_cast(0xfbfcfdfe)); - be::flip(i32); + be::invert(i32); BOOST_TEST_EQ(i32, static_cast(0xfefdfcfb)); boost::int16_t i16 = 0x0102; - be::flip(i16); + be::invert(i16); BOOST_TEST_EQ(i16, 0x0201); - be::flip(i16); + be::invert(i16); BOOST_TEST_EQ(i16, 0x0102); i16 = static_cast(static_cast(0xfefd)); - be::flip(i16); + be::invert(i16); BOOST_TEST_EQ(i16, static_cast(static_cast(0xfdfe))); - be::flip(i16); + be::invert(i16); BOOST_TEST_EQ(i16, static_cast(static_cast(0xfefd))); boost::uint64_t ui64 = 0x0102030405060708ULL; - be::flip(ui64); + be::invert(ui64); BOOST_TEST_EQ(ui64, 0x0807060504030201ULL); - be::flip(ui64); + be::invert(ui64); BOOST_TEST_EQ(ui64, 0x0102030405060708ULL); boost::uint32_t ui32 = 0x01020304; - be::flip(ui32); + be::invert(ui32); BOOST_TEST_EQ(ui32, static_cast(0x04030201)); - be::flip(ui32); + be::invert(ui32); BOOST_TEST_EQ(ui32, static_cast(0x01020304)); boost::uint16_t ui16 = 0x0102; - be::flip(ui16); + be::invert(ui16); BOOST_TEST_EQ(ui16, 0x0201); - be::flip(ui16); + be::invert(ui16); BOOST_TEST_EQ(ui16, static_cast(0x0102)); - std::cout << " test_in_place_flip complete\n"; + std::cout << " test_in_place_invert complete\n"; } - void test_copying_flip() + void test_copying_invert() { - std::cout << "test_copying_flip...\n"; + std::cout << "test_copying_invert...\n"; boost::int64_t i64 = 0x0102030405060708LL, j64, k64; - be::flip(i64, j64); + be::invert(i64, j64); BOOST_TEST_EQ(j64, 0x0807060504030201LL); BOOST_TEST_EQ(i64, 0x0102030405060708LL); - be::flip(j64, k64); + be::invert(j64, k64); BOOST_TEST_EQ(k64, 0x0102030405060708LL); i64 = 0xfefdfcfbfaf9f8f7LL; - be::flip(i64, j64); + be::invert(i64, j64); BOOST_TEST_EQ(j64, static_cast(0xf7f8f9fafbfcfdfeLL)); - be::flip(j64, k64); + be::invert(j64, k64); BOOST_TEST_EQ(k64, static_cast(0xfefdfcfbfaf9f8f7LL)); boost::int32_t i32 = 0x01020304, j32, k32; - be::flip(i32, j32); + be::invert(i32, j32); BOOST_TEST_EQ(j32, 0x04030201); - be::flip(j32, k32); + be::invert(j32, k32); BOOST_TEST_EQ(k32, 0x01020304); i32 = 0xfefdfcfb; - be::flip(i32, j32); + be::invert(i32, j32); BOOST_TEST_EQ(j32, static_cast(0xfbfcfdfe)); - be::flip(j32, k32); + be::invert(j32, k32); BOOST_TEST_EQ(k32, static_cast(0xfefdfcfb)); boost::int16_t i16 = 0x0102, j16, k16; - be::flip(i16, j16); + be::invert(i16, j16); BOOST_TEST_EQ(j16, 0x0201); - be::flip(j16, k16); + be::invert(j16, k16); BOOST_TEST_EQ(k16, 0x0102); i16 = static_cast(static_cast(0xfefd)); - be::flip(i16, j16); + be::invert(i16, j16); BOOST_TEST_EQ(j16, static_cast(static_cast(0xfdfe))); - be::flip(j16, k16); + be::invert(j16, k16); BOOST_TEST_EQ(k16, static_cast(static_cast(0xfefd))); boost::uint64_t ui64 = 0x0102030405060708ULL, uj64, uk64; - be::flip(ui64, uj64); + be::invert(ui64, uj64); BOOST_TEST_EQ(uj64, 0x0807060504030201ULL); - be::flip(uj64, uk64); + be::invert(uj64, uk64); BOOST_TEST_EQ(uk64, 0x0102030405060708ULL); boost::uint32_t ui32 = 0x01020304, uj32, uk32; - be::flip(ui32, uj32); + be::invert(ui32, uj32); BOOST_TEST_EQ(uj32, static_cast(0x04030201)); - be::flip(uj32, uk32); + be::invert(uj32, uk32); BOOST_TEST_EQ(uk32, static_cast(0x01020304)); boost::uint16_t ui16 = 0x0102, uj16, uk16; - be::flip(ui16, uj16); + be::invert(ui16, uj16); BOOST_TEST_EQ(uj16, 0x0201); - be::flip(uj16, uk16); + be::invert(uj16, uk16); BOOST_TEST_EQ(uk16, 0x0102); - std::cout << " test_copying_flip complete\n"; + std::cout << " test_copying_invert complete\n"; } const boost::int64_t ni64 = 0x0102030405060708LL; @@ -196,9 +196,9 @@ namespace const boost::uint16_t lui16 = 0x0102; # endif - void test_in_place_conditional_flip() + void test_in_place_conditional_invert() { - std::cout << "test_in_place_conditional_flip...\n"; + std::cout << "test_in_place_conditional_invert...\n"; boost::int64_t i64; @@ -308,12 +308,12 @@ namespace be::little_to_native(ui16); BOOST_TEST_EQ(ui16, nui16); - std::cout << " test_in_place_conditional_flip complete\n"; + std::cout << " test_in_place_conditional_invert complete\n"; } - void test_copying_conditional_flip() + void test_copying_conditional_invert() { - std::cout << "test_copying_conditional_flip...\n"; + std::cout << "test_copying_conditional_invert...\n"; boost::int64_t i64, ti64; @@ -423,7 +423,7 @@ namespace be::little_to_native(ui16, tui16); BOOST_TEST_EQ(tui16, nui16); - std::cout << " test_copying_conditional_flip complete\n"; + std::cout << " test_copying_conditional_invert complete\n"; } } // unnamed namespace @@ -431,10 +431,10 @@ namespace int cpp_main(int, char * []) { std::cerr << std::hex; - test_in_place_flip(); - test_copying_flip(); - test_in_place_conditional_flip(); - test_copying_conditional_flip(); + test_in_place_invert(); + test_copying_invert(); + test_in_place_conditional_invert(); + test_copying_conditional_invert(); return ::boost::report_errors(); } diff --git a/libs/endian/test/msvc10/endian.sln b/libs/endian/test/msvc10/endian.sln index a24c774..1ac82d4 100644 --- a/libs/endian/test/msvc10/endian.sln +++ b/libs/endian/test/msvc10/endian.sln @@ -15,7 +15,7 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "endian_hello_world", "endia EndProject Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "binary_stream_test", "binary_stream_test\binary_stream_test.vcxproj", "{1382D085-FF3F-4573-8709-E10D3D74D620}" EndProject -Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "binary_stream_example", "binary_stream_example\binary_stream_example.vcxproj", "{06736C67-6305-4A9F-8D10-850FD0CE907D}" +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "bin_manip_example", "binary_stream_example\binary_stream_example.vcxproj", "{06736C67-6305-4A9F-8D10-850FD0CE907D}" EndProject Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "conversion_test", "conversion_test\conversion_test.vcxproj", "{9FA33B0B-2B00-49E8-A892-E049D86076A9}" EndProject