| Boost Home + | Endian Home Conversion Functions Arithmetic Types - Buffer Types | + Buffer Types + Choosing Approach
| Boost Home + | Endian Home Conversion Functions Arithmetic Types - Buffer Types | + Buffer Types + Choosing Approach
Header boost/endian/arithmetic.hpp provides integer and floating point binary types with control over @@ -118,10 +109,11 @@ using namespace boost::endian; namespace { - // This is an extract from a very widely used GIS file format. It seems odd - // to mix big and little endians in the same file - but this is a real-world - // format and users wishing to write low level code manipulating these files - // must deal with the mixed endianness. + // This is an extract from a very widely used GIS file format. + // Why the designer decided to mix big and little endians in + // the same file is not known. But this is a real-world format + // and users wishing to write low level code manipulating these + // files have to deal with the mixed endianness. struct header { @@ -145,11 +137,13 @@ int main(int, char* []) h.version = 1; h.shape_type = 0x01020304; - // Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes - // used for binary file operations when ultimate efficiency is important. Such - // I/O is often performed in some C++ wrapper class, but to drive home the - // point that endian integers are often used in fairly low-level code that does - // bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example. + // Low-level I/O such as POSIX read/write or <cstdio> + // fread/fwrite is sometimes used for binary file operations + // when ultimate efficiency is important. Such I/O is often + // performed in some C++ wrapper class, but to drive home the + // point that endian integers are often used in fairly + // low-level code that does bulk I/O operations, <cstdio> + // fopen/fwrite is used for I/O in this example. std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY @@ -214,8 +208,9 @@ enum class align {no, yes};
One class template is provided:
-template <order Order, typename T, std::size_t n_bits, align A = align::no> - class endian_arithmetic; +template <order Order, typename T, std::size_t n_bits, + align Align = align::no> +class endian_arithmetic;
Typedefs, such as big_int32_t, provide convenient naming
@@ -375,9 +370,10 @@ usual operations on integers are supplied.
Last revised: -05 December, 2014
+19 January, 2015© Copyright Beman Dawes, 2006-2009, 2013
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt
diff --git a/buffers.html b/buffers.html index e171fbb..594b941 100644 --- a/buffers.html +++ b/buffers.html @@ -1,4 +1,4 @@ - + @@ -17,7 +17,7 @@
| Boost Home + | Endian Home Conversion Functions Arithmetic Types - Buffer Types | + Buffer Types + Choosing Approach
- <boost/endian/conversion.hpp>
- <boost/endian/buffers.hpp>
- <boost/endian/arithmetic.hpp>
The internal byte order of arithmetic types is traditionally called endianness. See the Wikipedia for a full exploration of endianness, including definitions of big endian and little endian.
-Header boost/endian/buffers.hpp +
Header boost/endian/buffers.hpp
provides endian_buffer, a portable endian integer and floating-point binary buffer
class template with control over
byte order, value type, size, and alignment independent of the platform's native
@@ -93,22 +84,23 @@ base class for the endian_arithmetic
class template, which is aimed at users who wish fully automatic endianness
conversion and direct support for all normal arithmetic operations.
The endian_example.cpp program writes a +
The example/endian_example.cpp program writes a
binary file containing four byte big-endian and little-endian integers:
-#include <iostream> #include <cstdio> -#include <boost/endian/buffers.hpp> +#include <boost/endian/buffers.hpp> // see Synopsis below #include <boost/static_assert.hpp> using namespace boost::endian; namespace { - // This is an extract from a very widely used GIS file format. Why the designer - // decided to mix big and little endians in the same file is not known. But - // this is a real-world format and users wishing to write low level code - // manipulating these files have to deal with the mixed endianness. + // This is an extract from a very widely used GIS file format. + // Why the designer decided to mix big and little endians in + // the same file is not known. But this is a real-world format + // and users wishing to write low level code manipulating these + // files have to deal with the mixed endianness. struct header { @@ -132,11 +124,13 @@ int main(int, char* []) h.version = 1; h.shape_type = 0x01020304; - // Low-level I/O such as POSIX read/write or <cstdio> fread/fwrite is sometimes - // used for binary file operations when ultimate efficiency is important. Such - // I/O is often performed in some C++ wrapper class, but to drive home the - // point that endian integers are often used in fairly low-level code that does - // bulk I/O operations, <cstdio> fopen/fwrite is used for I/O in this example. + // Low-level I/O such as POSIX read/write or <cstdio> + // fread/fwrite is sometimes used for binary file operations + // when ultimate efficiency is important. Such I/O is often + // performed in some C++ wrapper class, but to drive home the + // point that endian integers are often used in fairly + // low-level code that does bulk I/O operations, <cstdio> + // fopen/fwrite is used for I/O in this example. std::FILE* fi = std::fopen(filename, "wb"); // MUST BE BINARY @@ -160,7 +154,7 @@ int main(int, char* []) }
After compiling and executing endian_example.cpp, +
After compiling and executing example/endian_example.cpp,
a hex dump of test.dat shows:
01020304 00000010 01000000 04030201@@ -201,8 +195,9 @@ enum class align {no, yes};
One class template is provided:
-template <order Order, typename T, std::size_t Nbits, align A = align::no> - class endian_buffer; +template <order Order, typename T, std::size_t Nbits, + align Align = align::no> +class endian_buffer;
Typedefs, such as big_int32_buf_t, provide convenient naming
@@ -339,7 +334,7 @@ requirements vary between hardware architectures and because alignment may be
affected by compiler switches or pragmas. For example, alignment of an 64-bit
integer may be to a 32-bit boundary on a 32-bit machine. Furthermore, aligned types
are only available on architectures with 16, 32, and 64-bit integer types.
Note: One-byte types +
Note: One-byte big and little buffer types have identical functionality. They are provided to improve code readability and searchability.
endian_bufferThe implementation-defined text in typedefs above is either
@@ -539,6 +548,30 @@ boost::endian::endian_reverse.
+Returns: A pointer to the first byte of
endian_value.
template <class charT, class traits, order Order, class T, + std::size_t n_bits, align Align> +std::basic_ostream<charT, traits>& operator<<(std::basic_ostream<charT, traits>& os, + const endian_buffer<Order, T, n_bits, Align>& x); ++
++Returns:
+os << x.value().
template <class charT, class traits, order Order, class T, + std::size_t n_bits, align A> +std::basic_istream<charT, traits>& operator>>(std::basic_istream<charT, traits>& is, + endian_buffer<Order, T, n_bits, Align>& x); ++
+Effects: As if:
+++T i; +if (is >> i) + x = i; ++Returns:
+is.
See the Endian home page FAQ for a library-wide @@ -617,7 +650,7 @@ any Boost object libraries.
Last revised: -06 December, 2014
+19 January, 2015© Copyright Beman Dawes, 2006-2009, 2013
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt
diff --git a/conversion.html b/conversion.html index 5ea86b5..c23617b 100644 --- a/conversion.html +++ b/conversion.html @@ -1,4 +1,4 @@ - + @@ -15,7 +15,7 @@
| Boost Home + | Endian Home Conversion Functions Arithmetic Types - Buffer Types | + Buffer Types + Choosing Approach
endian_reverse().
EndianReversibleInplace are required to perform reversal of endianness if needed by making an
unqualified call to endian_reverse_inplace().
-See -udt_conversion_example.cpp for an example user-defined type.
+ See example/udt_conversion_example.cpp for an example user-defined type.
int8_t endian_reverse(int8_t x) noexcept; @@ -371,12 +361,13 @@ portability for both programs and data.Acknowledgements
Tomas Puverle was instrumental in identifying and articulating the need to -support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for boost/endian/detail/intrinsic.hpp. +support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for +
boost/endian/detail/intrinsic.hpp. Pierre Talbot provided theint8_t endian_reverse()and templatedendian_reverse_inplace()implementations.
Last revised: -16 December, 2014
+19 January, 2015© Copyright Beman Dawes, 2011, 2013
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt
diff --git a/index.html b/index.html index 0ccac4e..27e0b10 100644 --- a/index.html +++ b/index.html @@ -15,23 +15,26 @@- - +Endian Library
-
-
Consider the following code:
@@ -181,189 +164,35 @@ integers. The types may be aligned. -Boost Endian is a header-only library.
+Boost Endian is a header-only library. C++03 compilers are supported. C++11 features
+affecting interfaces, such as noexcept, are used only if available.
The best approach to endianness for a particular use case depends on interactions between -the approach characteristics and -the application needs.
- -Recommendation: If you are uncertain, new to endianness, concerned -about security, concerned about reliability, or don't want to invest time making -engineering trade-offs, use the endian arithmetic types. They are safer, easier -to use, and your code will be easier to maintain.
- -The characteristics that differentiate the three approaches to endianness are the endianness -invariants, conversion explicitness, arithmetic operations, sizes available, and -alignment requirements.
- -- -- -Endian conversion functions use objects of the ordinary C++ arithmetic -types like
- -intorunsigned shortto hold values. That -breaks the implicit invariant that the C++ language rules apply. The usual -language rules only apply if the endianness of the object is currently set by -the conversion functions to the native endianness for the platform. That can -make it very hard to reason about complex logic flow, and result in difficult to -find bugs.Endian buffer and arithmetic types hold values internally as arrays of -characters with an invariant that the endianness of the array never changes. -That makes these types easier to use and programs easier to maintain.
- -
- -- -Endian conversion functions and buffer types never perform -implicit conversions. This gives users explicit control of when conversion -occurs, and may help avoid unnecessary conversions.
- -Endian arithmetic types perform conversion implicitly. That makes -these types very easy to use, but can result in unnecessary conversions. Failure -to hoist conversions out of inner loops can bring a performance penalty.
- -
- -- -Endian conversion functions do not supply arithmetic -operations, but this is not a concern since this approach uses ordinary C++ -arithmetic types to hold values.
- -Endian buffer types do not supply arithmetic operations. Although this -approach avoids unnecessary conversions, it can result in the introduction of -additional variables and confuse maintenance programmers.
- -Endian arithmetic types do supply arithmetic operations. They -are very easy to use if lots of arithmetic is involved.
- -
- -- -Endianness conversion functions only support 1, 2, 4, and 8 byte -integers. That's sufficient for many applications.
- -Endian buffer and arithmetic types support 1, 2, 3, 4, 5, 6, 7, and 8 -byte integers. For an application where memory use or I/O speed is the limiting -factor, using sizes tailored to application needs can be useful.
- -
- -- -Endianness conversion functions only support aligned integer and -floating-point types. That's sufficient for most applications.
- -Endian buffer and arithmetic types support both aligned and unaligned -integer and floating-point types. Unaligned types are rarely needed, but when -needed they are often very useful and workarounds are painful. For example,
- --- -Non-portable code like this:
--
struct S {-
- uint16_t a; // big endian
- uint32_t b; // big endian
- } __attribute__ ((packed));Can be replaced with portable code like this:
---
struct S {-
- big_uint16_ut a;
- big_uint32_ut b;
- };
An existing codebase runs on big endian systems. It does not -currently deal with endianness. The codebase needs to be modified so it can run -on little endian systems under various operating systems. To ease -transition and protect value of existing files, external data will continue to -be maintained as big endian.
- -The endian
-arithmetic approach is recommended to meet these needs. A relatively small
-number of header files dealing with binary I/O layouts need to change types like
-short or int16_t to big_int16_t, and
-int or int32_t to bif_int32_t. No
-changes are required for .cpp files.
An existing codebase runs on little-endian Linux systems. It already -deals with endianness via -Linux provided -functions. Because of a business merger, the codebase has to be quickly -modified for Windows and possibly other operating systems, while still -supporting Linux. The codebase is reliable and the programmers are all -well-aware of endian issues.
- -These factors all argue for an endian conversion
-approach that just mechanically changes the calls to htobe32,
-etc. to boost::endian::native_to_big, etc. and replaces <endian.h>
-with <boost/endian/conversion.hpp>.
A new, complex, multi-threaded application is to be developed that must run -on little endian machines, but do big endian network I/O. The developers believe -computational speed for endian variable is critical but have seen numerous bugs -result from inability to reason about endian conversion state. They are also -worried that future maintenance changes could inadvertently introduce a lot of -slow conversions if full-blown endian arithmetic types are used.
- -The endian buffers approach is made-to-order for -this use case.
- -A new, complex, multi-threaded application is to be developed that must run -on little endian machines, but do big endian network I/O. The developers believe -computational speed for endian variables is not critical but have seen -numerous bugs result from inability to reason about endian conversion state. -They are also concerned about ease-of-use both during development and long-term -maintenance.
- -Removing concern about conversion speed and adding concern about ease-of-use -tips the balance strongly in favor the endian -arithmetic approach.
+This section has been moved to its own +Choosing the Approach page.
Supply compilers, including GCC, Clang, and Visual C++, supply built-in support for byte swapping intrinsics. -The library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for release +
Most compilers, including GCC, Clang, and Visual C++, supply built-in support for byte swapping intrinsics. +The Endian library uses these intrinsics when available since they may result in smaller and faster generated code, particularly for release builds.
-Defining BOOST_ENDIAN_NO_INTRINSICS will suppress use
+
Defining the macro BOOST_ENDIAN_NO_INTRINSICS will suppress use
of the intrinsics. Useful when intrinsic headers such as
-byteswap.h are not being found on your platform.
byteswap.h are not being found by your compiler, perhaps because it
+is an older release or has very limited supporting libraries.
The macro BOOST_ENDIAN_INTRINSIC_MSG is defined as
either "no byte swap intrinsics" or a string describing the
-particular set of intrinsics being used.
Consider this problem:
+| @@ -404,15 +233,20 @@ native_to_big_inplace(x); |
There will be no performance difference between the two approaches in release builds, -regardless of the native endianness of the machine. That's because optimizing compilers will likely -generate exactly the same code for each. That conclusion was confirmed by +regardless of the native endianness of the machine. That's because optimizing compilers will generate exactly the same code for each. That conclusion was confirmed by studying the generated assembly code for GCC and Visual C++. Furthermore, time spent doing I/O will determine the speed of this application.
Now consider a slightly different problem:
+| @@ -456,230 +290,63 @@ native_to_big_inplace(x); |
With the Endian arithmetic approach, on little endian platforms an implicit conversion from and then back to big endian is done inside the loop. With the Endian conversion function approach, the user has ensured the conversions are done outside the loop, so the code may run more quickly on little endian platforms.
-These tests were run against release builds on a circa 2012 4-core little endian X64 Intel Core i5-3570K CPU @ 3.40GHz under Windows 7.
Caveat emptor: The Windows CPU timer has very high granularity. Repeated runs of the same tests often yield considerably different results.
-See loop_time_test.cpp and -Jamfile.v2 for the actual code and build -setup. -(For GCC 4.7, there are no 16-bit intrinsics, so they are emulated by using -32-bit intrinsics.)
+See test/loop_time_test.cpp for the actual code and benchmark/Jamfile.v2 for the build +setup.
+ +| GNU C++ version 4.7.0 | |||||
| Iterations: 1000000000, Intrinsics: __builtin_bswap16, etc. | |||||
| Test Case | -Endian arithmetic |
-Endian conversion function |
+|||
| GNU C++ version 4.8.2 on Linux virtual + machine | |||||
| Iterations: 10'000'000'000, Intrinsics: __builtin_bswap16, etc. | |||||
| Test Case | +Endian arithmetic type |
+Endian conversion function |
|||
| 16-bit aligned big endian | -1.37 s | -0.81 s | |||
| 16-bit aligned little endian | -0.83 s | -0.81 s | |||
| 16-bit unaligned big endian | -1.09 s | -0.83 s | |||
| 16-bit unaligned little endian | -1.09 s | -0.81 s | |||
| 32-bit aligned big endian | -0.98 s | -0.27 s | |||
| 32-bit aligned little endian | -0.28 s | -0.27 s | |||
| 32-bit unaligned big endian | -3.82 s | -0.27 s | |||
| 32-bit unaligned little endian | -3.82 s | -0.27 s | |||
| 64-bit aligned big endian | -1.65 s | -0.41 s | |||
| 64-bit aligned little endian | -0.41 s | -0.41 s | |||
| 64-bit unaligned big endian | -17.53 s | -0.41 s | |||
| 64-bit unaligned little endian | -17.52 s | -0.41 s | |||
| Iterations: 1000000000, Intrinsics: no byte swap intrinsics | |||||
| Test Case | -Endian arithmetic |
-Endian conversion function |
-|||
| 16-bit aligned big endian | -1.95 s | -0.81 s | |||
| 16-bit aligned little endian | -0.83 s | -0.81 s | |||
| 16-bit unaligned big endian | -1.19 s | -0.81 s | |||
| 16-bit unaligned little endian | -1.20 s | -0.81 s | |||
| 32-bit aligned big endian | -0.97 s | -0.28 s | |||
| 32-bit aligned little endian | -0.27 s | -0.28 s | |||
| 32-bit unaligned big endian | -4.10 s | -0.27 s | |||
| 32-bit unaligned little endian | -4.10 s | -0.27 s | |||
| 64-bit aligned big endian | -1.64 s | -0.42 s | |||
| 64-bit aligned little endian | -0.41 s | -0.41 s | |||
| 64-bit unaligned big endian | -17.52 s | -0.42 s | |||
| 64-bit unaligned little endian | -17.52 s | -0.41 s | |||
| 16-bit aligned big endian | 8.46 s | 5.28 s | |||
| 16-bit aligned little endian | 5.28 s | 5.22 s | |||
| 32-bit aligned big endian | 8.40 s | 2.11 s | |||
| 32-bit aligned little endian | 2.11 s | 2.10 s | |||
| 64-bit aligned big endian | 14.02 s | 3.10 s | |||
| 64-bit aligned little endian | 3.00 s | 3.03 s | |||
Comment: Note that the 32-bit aligned big endian -timings are the same with or without intrinsics turned on. Presumably the -optimizer is recognizing the byte swapping and applying the intrinsics itself.
- +| Microsoft Visual C++ version 11.0 | |||||
| Iterations: 1000000000, Intrinsics: cstdlib _byteswap_ushort, etc. | |||||
| Test Case | -Endian type |
-Endian conversion function |
+|||
| Microsoft Visual C++ version 14.0 | |||||
| Iterations: 10'000'000'000, Intrinsics: cstdlib _byteswap_ushort, etc. | |||||
| Test Case | +Endian arithmetic type |
+Endian conversion function |
|||
| 16-bit aligned big endian | -0.83 s | -0.51 s | |||
| 16-bit aligned little endian | -0.51 s | -0.50 s | |||
| 16-bit unaligned big endian | -1.37 s | -0.51 s | |||
| 16-bit unaligned little endian | -1.37 s | -0.50 s | |||
| 32-bit aligned big endian | -0.81 s | -0.50 s | |||
| 32-bit aligned little endian | -0.51 s | -0.51 s | |||
| 32-bit unaligned big endian | -2.98 s | -0.53 s | |||
| 32-bit unaligned little endian | -3.00 s | -0.51 s | |||
| 64-bit aligned big endian | -1.33 s | -0.33 s | |||
| 64-bit aligned little endian | -0.34 s | -0.27 s | |||
| 64-bit unaligned big endian | -7.05 s | -0.33 s | |||
| 64-bit unaligned little endian | -7.11 s | -0.31 s | |||
| Iterations: 1000000000, Intrinsics: no byte swap intrinsics | |||||
| Test Case | -Endian type |
-Endian conversion function |
-|||
| 16-bit aligned big endian | -0.83 s | -0.51 s | |||
| 16-bit aligned little endian | -0.51 s | -0.51 s | |||
| 16-bit unaligned big endian | -1.36 s | -0.51 s | |||
| 16-bit unaligned little endian | -1.37 s | -0.51 s | |||
| 32-bit aligned big endian | -3.42 s | -0.50 s | |||
| 32-bit aligned little endian | -0.51 s | -0.51 s | |||
| 32-bit unaligned big endian | -2.93 s | -0.50 s | |||
| 32-bit unaligned little endian | -2.95 s | -0.50 s | |||
| 64-bit aligned big endian | -5.99 s | -0.33 s | |||
| 64-bit aligned little endian | -0.33 s | -0.33 s | |||
| 64-bit unaligned big endian | -7.02 s | -0.27 s | |||
| 64-bit unaligned little endian | -7.02 s | -0.27 s | |||
| 16-bit aligned big endian | 8.27 s | 5.26 s | |||
| 16-bit aligned little endian | 5.29 s | 5.32 s | |||
| 32-bit aligned big endian | 8.36 s | 5.24 s | |||
| 32-bit aligned little endian | 5.24 s | 5.24 s | |||
| 64-bit aligned big endian | 13.65 s | 3.34 s | |||
| 64-bit aligned little endian | 3.35 s | 2.73 s | |||
When program logic dictates many more conversions for the Endian arithmetic -approach than the Endian conversion function approach (example -2):
- -- -+There may be a considerable performance difference. If machine endianness differs from the -desired endianness, the Endian arithmetic approach must do the byte reversal many -times while the Endian conversion approach only does the reversal once. But if -the endianness is the same, there is no conversion with either approach and no -conversion code is generated for typical release builds.
- -Whether or not compiler byte swap intrinsics are explicitly available has little -impact on GCC but a lot of impact on Visual C++, for the tested compiler -versions. Yet another example of why actual timing tests are needed to -determine if some coding technique has significant impact on performance.
- -Unaligned types are much slower that aligned types, regardless of -endianness considerations. Instead of single instruction register loads and -stores, multiple instructions are required on common platforms.
- -
Are C++03 compilers supported?
+ ++ ++Yes.
+ +
Does the implementation use compiler intrinsic built-in byte swapping?
@@ -708,7 +383,7 @@ stores, multiple instructions are required on common platforms. I/O formats?Using the unaligned integer types to save internal or external -memory space is a minor secondary use case.
+memory space is a minor secondary use.Why bother with binary I/O? Why not just use C++ Standard Library stream inserters and extractors?
@@ -764,68 +439,71 @@ and 16, 32, and 64-bit aligned integers.
The library was reworked from top to bottom to accommodate changes requested +during the formal review. See Mini-Review +page for details.
+The endian types have been decomposed into endian buffer types - and endian arithmetic types, as requested. The arithmetic types derive from - the buffer types.
Headers have been renamed to endian/arithmetic.hpp and
- endian/conversion.hpp. endian/buffers.hpp has been
+
boost/endian/endian.hpp has been renamed to
+ boost/endian/arithmetic.hpp. Headers
+ boost/endian/conversion.hpp and boost/endian/buffers.hpp have been
added.
Infrastructure file names were changed accordingly.The endian buffer and arithmetic types and endian conversion functions now support 32-bit (float) and
- 64-bit (double) floating point, as requested.
order::native is now a synonym for order::big
- or order::little according to the endianness of the platform, as
- requested. This reduces the number of template specializations required._t suffix, for
+ consistency with the standard library integer type aliases and because use of
+ aligned types is much more common than unaligned types._ut suffix. This
+ is short, yet stands out enough to alert the reader than unusual types are
+ involved.endian_reverse() overloads for int8_t and
uint8_t have been added for improved generality. (Pierre Talbot)endian_reverse_inplace() have been replaced with a single
endian_reverse_inplace() template. (Pierre Talbot)noexcept are now used, while still
- supporting C++03 compilers.noexcept, are now used.
+ C++03 compilers are still
+ supported.Prior to the official Boost release, class template
+endian_arithmetic has been used for a decade or more with the same
+functionality but under the name endian. Other names also changed
+in the official release. If the macro BOOST_ENDIAN_DEPRECATED_NAMES
+is defined, those old now deprecated names are still supported. However, the
+class template endian name is only provided for compilers
+supporting C++11 template aliases. For C++03 compilers, the name will have to be
+changed to endian_arithmetic.
To support backward header compatibility, deprecated header boost/endian/endian.hpp
+forwards to boost/endian/arithmetic.hpp. It requires
+BOOST_ENDIAN_DEPRECATED_NAMES be defined. It should only be used while
+transitioning to the official Boost release of the library as it will be removed
+in some future release.
Comments and suggestions were received from Adder, Benaka Moorthi, Christopher Kohlhoff, Cliff Green, Daniel James, Gennaro Proto, Giovanni Piero -Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn, John Filo, John +Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John Maddock, Kim Barrett, Marsh Ray, Martin Bonner, Mathias Gaunard, Matias Capeletto, Neil Mayhew, Paul Bristow, Pierre Talbot, Phil Endecott, Pyry Jahkola, Rene Rivera, Robert Stewart, Roland Schwarz, Scott McMurray, Sebastian Redl, Tim Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen and -Vitaly Budovski,.
+Vitaly Budovsk. Apologies if anyone has been missed.Last revised: -17 December, 2014
+19 January, 2015© Copyright Beman Dawes, 2011, 2013
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt
diff --git a/mini_review_topics.html b/mini_review_topics.html index 340baed..d7a7f3c 100644 --- a/mini_review_topics.html +++ b/mini_review_topics.html @@ -9,34 +9,60 @@ -Here is what needs to be done to get the library ready for a mini-review: +
|
+
+ |
+ + + Endian Mini-Review | +
| + Endian Home + Conversion Functions + Arithmetic Types + Buffer Types + Choosing Approach | +
The results of the Boost.Endian formal review included a list of issues to be +resolved before a mini-review.
- +The issues are shown in bold below, with the resolution indicated.
-Common use case scenarios should be developed.
+1. Common use case scenarios should be developed.
--Done. See Use cases.
+Done. The documentation have been refactored. A page is now devoted to + Choosing the Approach to endianness. See + Use cases for use case + scenarios.
Example programs should be developed for the common use case scenarios.
+2. Example programs should be developed for the common use case scenarios.
--+
Done. See Choosing the Approach. + Example code has been added throughout.
Documentation should illuminate the differences between endian +
3. Documentation should illuminate the differences between endian integer/float type and endian conversion approaches to the common use case scenarios, and provide guidelines for choosing the most appropriate approach in user's applications.
--Done. See Choosing between endian conversion - functions, endian buffer types, and endian arithmetic types.
+Done. See Choosing the Approach.
Conversion functions supplying results via return should be provided.
+4 .Conversion functions supplying results via return should be provided.
--Done. See conversion docs.
+Done. See ConversionFunctions.
Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.
+5. Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.
-Done. Compiler (Clang, GCC, VisualC++, etc.) intrinsics and built-in functions are used in the implementation where appropriate, as requested. See @@ -44,7 +70,7 @@ approach in user's applications.
Timings for Example 2 to gauge the impact of intrinsics.
Endian integer (and floating) types should be implemented via the +
6. Endian integer (and floating) types should be implemented via the conversion functions. If that can't be done efficiently, consideration should be given to expanding the conversion function signatures to resolve the inefficiencies.
@@ -52,7 +78,7 @@ resolve the inefficiencies.Done. For the endian types, the implementation uses the endian conversion functions, and thus the intrinsics, as requested.
-Benchmarks that measure performance should be provided. It should be +
7. Benchmarks that measure performance should be provided. It should be possible to compare platform specific performance enhancements against portable base implementations, and to compare endian integer approaches against endian conversion approaches for the common use case scenarios.
@@ -60,7 +86,7 @@ against endian conversion approaches for the common use case scenarios.Done. See Timings for Example 2. The endian/test directory
also contains several additional benchmark and speed test programs.
Float (32-bits) and double (64-bits) should be supported. IEEE 754 is +
8. Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the primary use case.
-Done. The endian buffer types, @@ -68,12 +94,13 @@ the primary use case.
endian conversion functions now support 32-bit (float)and 64-bit(double)floating point, as requested.
Support for user defined types (UDTs) is desirable, and should be +
9. Support for user defined types (UDTs) is desirable, and should be provided where there would be no conflict with the other concerns.
--Done. See conversion requirements.
+Done. See Customization + points for user-defined types (UDTs).
There is some concern that endian integer/float arithmetic operations +
10. There is some concern that endian integer/float arithmetic operations might used inadvertently or inappropriately. The impact of adding an endian_buffer class without arithmetic operations should be investigated.
@@ -83,23 +110,37 @@ might used inadvertently or inappropriately. The impact of adding an endian_buff-endian_bufferis a public base class forendian_arithmetic, and can also be used by users as a stand-alone class.
Stream insertion and extraction of the endian integer/float types should +
11. Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.
--Done. See Stream inserter and - Stream extractor.
+Done. See Stream inserter and + Stream extractor.
Binary I/O support that was investigated during development of the Endian +
12. Binary I/O support that was investigated during development of the Endian library should be put up for mini-review for inclusion in the Boost I/O library.
-++
Not done yet. Will be handled as a separate min-review soon after the + Endian mini-review.
+
13. Other requested changes.
+ +++
- In addition to the named-endianness conversion functions, functions that perform + compile-time (via template) and run-time (via function argument) dispatch + are now provided.
+- +
order::nativeis now a synonym fororder::big+ ororder::littleaccording to the endianness of the platform. This reduces the number of template specializations required.- Headers have been reorganized to make them easier to read, + with a synopsis at the front and implementation following.
+
Last revised: -17 December, 2014
+19 January, 2015© Copyright Beman Dawes, 2014
Distributed under the Boost Software License, Version 1.0. See www.boost.org/ LICENSE_1_0.txt
diff --git a/styles.css b/styles.css index d1b8958..f761bcb 100644 --- a/styles.css +++ b/styles.css @@ -3,6 +3,7 @@ body { font-family: sans-serif; max-width: 6.5in; + margin: 0px auto; font-size: 85%; } ins {background-color: #CCFFCC;} @@ -12,7 +13,7 @@ body table{font-size: 100%;} /* - © Copyright Beman Dawes, 2014 + © Copyright Beman Dawes, 2014 Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt */ diff --git a/todo_list.html b/todo_list.html index b4f3241..fed67d3 100644 --- a/todo_list.html +++ b/todo_list.html @@ -12,23 +12,9 @@Last revised: -17 December, 2014
- -August 12, 2014: The many items that have been completed should be -removed, after verifying that they are in fact taken care of.
John Filo - "Absolutely. I'd like to see support for float and @@ -52,26 +38,6 @@ removed, after verifying that they are in fact taken care of.
Spirit with the reviewed version. All of Spirits regression tests stillRobert Stewart - "There are issues that keep me from saying yes
- at this time. There are too many suggested variations and ideas under
- consideration to accept the library in its present state. However, a
- mini-review should be sufficient to evaluate the final form, once Beman
- determines a course of action, and determine whether to accept it or not."
-
Tim Blechmann - "the library should be accepted, if
-
- (a) the interface of the conversion functions is changed
- (b) the performance can be improved
- (c) the documentation integrates better with the rest of the boost
- documentation."
-
Vicente J. Botet Escriba - "No in its current state.
- Once the library takes in account the requested modification (that Beman has
- already accepted) a mini-review will be necessary to improve the library
- before release."
I'll add FAQ and/or add more entries to the final docs.
-
- Only big/little endianness is taken into account because these are the
- only endian schemes that have any practical value. All the others are
- just historical curiosities.
Also change docs if applicable.
-Compile time dispatch on an endianness enum was also requested in
- another review. That's fine with me, but I haven't had a chance to
- figure out the interface details.
Will do.
* I'm only willing to provide conversion.hpp FP support. Providing
-types that mimic FP types is far beyond my knowledge of how to deal
-with floating point's notorious arithmetic issues.
Support IEEE754 format (32 bit, 64 bit) only.
Last revised: -17 December, 2014
+17 January, 2015© Copyright Beman Dawes, 2012
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt