third_party/boost/endian/doc/endian/history.adoc - platform/external/sdv/vsomeip - Git at Google

 ////
 Copyright 2011-2016 Beman Dawes

 Distributed under the Boost Software License, Version 1.0.
 (http://www.boost.org/LICENSE_1_0.txt)
 ////

 [#appendix_history]
 [appendix]
 # History and Acknowledgments
 :idprefix: apph_

 ## History

 ### Changes requested by formal review

 The library was reworked from top to bottom to accommodate changes requested
 during the formal review. The issues that were required to be resolved before
 a mini-review are shown in *bold* below, with the resolution indicated.

 Common use case scenarios should be developed.::
 Done. The documentation have been refactored. A page is now devoted to
 <<choosing,Choosing the Approach>> to endianness. See
 <<choosing_use_cases,Use cases>> for use case scenarios.

 Example programs should be developed for the common use case scenarios.::
 Done. See <<choosing,Choosing the Approach>>. Example code has been added
 throughout.

 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,Choosing the Approach>>.

 Conversion functions supplying results via return should be provided.::
 Done. See <<conversion,Conversion Functions>>.

 Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.::
 Done. Compiler (Clang, GCC, Visual{cpp}, etc.) intrinsics and built-in
 functions are used in the implementation where appropriate, as requested. See
 <<overview_intrinsic,Built-in support for Intrinsics>>. See
 <<overview_timings,Timings for Example 2>> to gauge the impact of intrinsics.

 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.::
 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 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.::
 Done. See <<overview_timings,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 the primary use case.::
 Done. The <<buffers,endian buffer types>>,
 <<arithmetic,endian arithmetic types>> and
 <<conversion,endian conversion functions>> now support 32-bit `(float)`
 and 64-bit `(double)` floating point, as requested.

 NOTE: This answer is outdated. The support for `float` and `double` was subsequently found
       problematic and has been removed. Recently, support for `float` and `double` has
       been reinstated for `endian_buffer` and `endian_arithmetic`, but not for the
       conversion functions.

 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_customization,Customization points for user-defined
 types (UDTs)>>.

 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.::
 Done. The endian types have been decomposed into class template
 `<<buffers,endian_buffer>>` and class template
 `<<arithmetic,endian_arithmetic>>`. Class `endian_buffer` is a public base
 class for `endian_arithmetic`, and can also be used by users as a stand-alone
 class.

 Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.::
 Done. See <<buffers_stream_inserter,Stream inserter>> and
 <<buffers_stream_extractor,Stream extractor>>.

 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.

 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::native` is now a synonym for `order::big` or `order::little` according
   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.

 ### Other changes since formal review

 * Header `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 arithmetic type aliases have been renamed, using a naming pattern
 that is consistent for both integer and floating point, and a consistent set of
 aliases supplied for the endian buffer types.
 * The unaligned-type alias names still have the `_t` suffix, but the
 aligned-type alias names now have an `_at` suffix.
 * `endian_reverse()` overloads for `int8_t` and `uint8_t` have been added for
 improved generality. (Pierre Talbot)
 * Overloads of `endian_reverse_inplace()` have been replaced with a single
 `endian_reverse_inplace()` template. (Pierre Talbot)
 * For X86 and X64 architectures, which permit unaligned loads and stores,
 unaligned little endian buffer and arithmetic types use regular loads and
 stores when the size is exact. This makes unaligned little endian buffer and
 arithmetic types significantly more efficient on these architectures. (Jeremy
 Maitin-Shepard)
 * {cpp}11 features affecting interfaces, such as `noexcept`, are now used.
 {cpp}03 compilers are still supported.
 * Acknowledgements have been updated.

 ## Compatibility with interim releases

 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 {cpp}11 template aliases. For {cpp}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.

 ## Future directions

 Standardization.::
 The plan is to submit Boost.Endian to the {cpp} standards committee for possible
 inclusion in a Technical Specification or the {cpp} standard itself.

 Specializations for `numeric_limits`.::
 Roger Leigh requested that all `boost::endian` types provide `numeric_limits`
 specializations.
 See https://github.com/boostorg/endian/issues/4[GitHub issue 4].

 Character buffer support.::
 Peter Dimov pointed out during the mini-review that getting and setting basic
 arithmetic types (or `<cstdint>` equivalents) from/to an offset into an array of
 unsigned char is a common need. See
 http://lists.boost.org/Archives/boost/2015/01/219574.php[Boost.Endian
 mini-review posting].

 Out-of-range detection.::
 Peter Dimov pointed suggested during the mini-review that throwing an exception
 on buffer values being out-of-range might be desirable. See the end of
 http://lists.boost.org/Archives/boost/2015/01/219659.php[this posting] and
 subsequent replies.

 ## Acknowledgements

 Comments and suggestions were received from Adder, Benaka Moorthi, Christopher
 Kohlhoff, Cliff Green, Daniel James, Dave Handley, Gennaro Proto, Giovanni Piero
 Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Howard Hinnant, Jason Newton,
 Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John Maddock, Kim Barrett, Marsh
 Ray, Martin Bonner, Mathias Gaunard, Matias Capeletto, Neil Mayhew, Nevin Liber,
 Olaf van der Spek, Paul Bristow, Peter Dimov, Pierre Talbot, Phil Endecott,
 Philip Bennefall, Pyry Jahkola, Rene Rivera, Robert Stewart, Roger Leigh, Roland
 Schwarz, Scott McMurray, Sebastian Redl, Tim Blechmann, Tim Moore, tymofey,
 Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if
 anyone has been missed.

 The documentation was converted into Asciidoc format by Glen Fernandes.
	////
	Copyright 2011-2016 Beman Dawes

	Distributed under the Boost Software License, Version 1.0.
	(http://www.boost.org/LICENSE_1_0.txt)
	////

	[#appendix_history]
	[appendix]
	# History and Acknowledgments
	:idprefix: apph_

	## History

	### Changes requested by formal review

	The library was reworked from top to bottom to accommodate changes requested
	during the formal review. The issues that were required to be resolved before
	a mini-review are shown in bold below, with the resolution indicated.

	Common use case scenarios should be developed.::
	Done. The documentation have been refactored. A page is now devoted to
	<<choosing,Choosing the Approach>> to endianness. See
	<<choosing_use_cases,Use cases>> for use case scenarios.

	Example programs should be developed for the common use case scenarios.::
	Done. See <<choosing,Choosing the Approach>>. Example code has been added
	throughout.

	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,Choosing the Approach>>.

	Conversion functions supplying results via return should be provided.::
	Done. See <<conversion,Conversion Functions>>.

	Platform specific performance enhancements such as use of compiler intrinsics or relaxed alignment requirements should be supported.::
	Done. Compiler (Clang, GCC, Visual{cpp}, etc.) intrinsics and built-in
	functions are used in the implementation where appropriate, as requested. See
	<<overview_intrinsic,Built-in support for Intrinsics>>. See
	<<overview_timings,Timings for Example 2>> to gauge the impact of intrinsics.

	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.::
	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 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.::
	Done. See <<overview_timings,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 the primary use case.::
	Done. The <<buffers,endian buffer types>>,
	<<arithmetic,endian arithmetic types>> and
	<<conversion,endian conversion functions>> now support 32-bit `(float)`
	and 64-bit `(double)` floating point, as requested.

	NOTE: This answer is outdated. The support for `float` and `double` was subsequently found
	problematic and has been removed. Recently, support for `float` and `double` has
	been reinstated for `endian_buffer` and `endian_arithmetic`, but not for the
	conversion functions.

	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_customization,Customization points for user-defined
	types (UDTs)>>.

	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.::
	Done. The endian types have been decomposed into class template
	`<<buffers,endian_buffer>>` and class template
	`<<arithmetic,endian_arithmetic>>`. Class `endian_buffer` is a public base
	class for `endian_arithmetic`, and can also be used by users as a stand-alone
	class.

	Stream insertion and extraction of the endian integer/float types should be documented and included in the test coverage.::
	Done. See <<buffers_stream_inserter,Stream inserter>> and
	<<buffers_stream_extractor,Stream extractor>>.

	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.

	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::native` is now a synonym for `order::big` or `order::little` according
	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.

	### Other changes since formal review

	* Header `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 arithmetic type aliases have been renamed, using a naming pattern
	that is consistent for both integer and floating point, and a consistent set of
	aliases supplied for the endian buffer types.
	* The unaligned-type alias names still have the `_t` suffix, but the
	aligned-type alias names now have an `_at` suffix.
	* `endian_reverse()` overloads for `int8_t` and `uint8_t` have been added for
	improved generality. (Pierre Talbot)
	* Overloads of `endian_reverse_inplace()` have been replaced with a single
	`endian_reverse_inplace()` template. (Pierre Talbot)
	* For X86 and X64 architectures, which permit unaligned loads and stores,
	unaligned little endian buffer and arithmetic types use regular loads and
	stores when the size is exact. This makes unaligned little endian buffer and
	arithmetic types significantly more efficient on these architectures. (Jeremy
	Maitin-Shepard)
	* {cpp}11 features affecting interfaces, such as `noexcept`, are now used.
	{cpp}03 compilers are still supported.
	* Acknowledgements have been updated.

	## Compatibility with interim releases

	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 {cpp}11 template aliases. For {cpp}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.

	## Future directions

	Standardization.::
	The plan is to submit Boost.Endian to the {cpp} standards committee for possible
	inclusion in a Technical Specification or the {cpp} standard itself.

	Specializations for `numeric_limits`.::
	Roger Leigh requested that all `boost::endian` types provide `numeric_limits`
	specializations.
	See https://github.com/boostorg/endian/issues/4[GitHub issue 4].

	Character buffer support.::
	Peter Dimov pointed out during the mini-review that getting and setting basic
	arithmetic types (or `<cstdint>` equivalents) from/to an offset into an array of
	unsigned char is a common need. See
	http://lists.boost.org/Archives/boost/2015/01/219574.php[Boost.Endian
	mini-review posting].

	Out-of-range detection.::
	Peter Dimov pointed suggested during the mini-review that throwing an exception
	on buffer values being out-of-range might be desirable. See the end of
	http://lists.boost.org/Archives/boost/2015/01/219659.php[this posting] and
	subsequent replies.

	## Acknowledgements

	Comments and suggestions were received from Adder, Benaka Moorthi, Christopher
	Kohlhoff, Cliff Green, Daniel James, Dave Handley, Gennaro Proto, Giovanni Piero
	Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Howard Hinnant, Jason Newton,
	Jeff Flinn, Jeremy Maitin-Shepard, John Filo, John Maddock, Kim Barrett, Marsh
	Ray, Martin Bonner, Mathias Gaunard, Matias Capeletto, Neil Mayhew, Nevin Liber,
	Olaf van der Spek, Paul Bristow, Peter Dimov, Pierre Talbot, Phil Endecott,
	Philip Bennefall, Pyry Jahkola, Rene Rivera, Robert Stewart, Roger Leigh, Roland
	Schwarz, Scott McMurray, Sebastian Redl, Tim Blechmann, Tim Moore, tymofey,
	Tomas Puverle, Vincente Botet, Yuval Ronen and Vitaly Budovsk. Apologies if
	anyone has been missed.

	The documentation was converted into Asciidoc format by Glen Fernandes.