diff --git a/libs/endian/doc/do_list.html b/libs/endian/doc/do_list.html
index e8ae41c..cc4f6ee 100644
--- a/libs/endian/doc/do_list.html
+++ b/libs/endian/doc/do_list.html
@@ -11,6 +11,22 @@
Endian Library Do List
+To Do
+
+ - Re-read all messages, and extract Acknowledgements and revise TODO list.
+ - Develop the use-cases example programs, using plain integers and UDT's.
+
+ - Apply revised conversion functions to the example programs. Iterate until
+ happy.
+ - Apply the integers to the example programs, and also see if using
+ the revised conversion functions to implement some or all of the
+ integers.
+ - Apply mockups of the buffers to the example programs, to get a
+ firmer idea if the buffer idea actually seems to do be worthwhile in
+ practice.
+ - Post work-in-progress for feedback.
+ - Finalize and hold mini-review.
+
Format Review Comments
Votes
Executive summary
- - Great concern and many suggestions regarding performance.
- - Request for performance benchmarks.
- - Great concern about documentation distinguishing use cases and
- recommendations for which approach (integers vs conversion) is appropriate.
- - Interest in support for float, double (IEEE754) and user defined types
- - Either add tutorial or remove from menu bar.
+ - Common use case scenarios should be developed.
+ - Example programs should be developed for the common use case scenarios.
+ - 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
+ for user's applications.
+ - Conversion functions supplying results via
return should be
+ provided.
+ - Platform specific performance enhancements such as use of compiler
+ intrinsics or relaxed alignment requirements should be supported.
+ - 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.
+ - 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.
+ - Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the
+ primary use case.
+ - Support for user defined types (UDTs) is desirable, and should be
+ supported where there would be no conflict with the other concerns.
+ - 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.
+ - Stream insertion and extraction of the endian integer/float types should
+ be documented and included in the test coverage.
+ - Binary I/O support that was investigated during development of the Endian
+ library should be put up for min-review for inclusion in the Boost I/O
+ library.
Docs
+ - Document use of endian integers with stream inserters and extractors.
+ - Either add tutorial or remove from menu bar.
- Conversion in note mention similarity to htonl() , etc.
- Conversion: add discussion of alignment, packing, etc. Bottom line; use at
your own risk. Use Phil's example:
@@ -107,13 +156,75 @@
historical notes, compiler-specific stuff, includes and ifdefs. imo, this is
the implementation part, which should not be exposed to a user.
- so i'd suggest to completely remove the links to the c++ headers.
+ so i'd suggest to completely remove the links to the c++ headers.
+
+ -
+
+ > explaining the other builting types are not considered. Why only
+ big/little
+ > endianness has been taken in account?
+ 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.
Code
+Also change docs if applicable.
+ - Beman: TODO:
+ Google
+ "unaligned integer", look at various entries. For example, http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.faqs/ka3544.html
- Merge conversion2 into conversion.hpp
- Use builtins where applicable (GCC, possibly others)
- - Endian integer types should use the conversion functions where applicable
+ - Endian integer types should use the conversion functions where applicable.
+ - Beman: Some platforms (compiler/processor taken together) don't require
+ alignment for the conversion functions if code is inlined, although speed may
+ suffer. (test to verify this assertion). On those platforms, conversion
+ functions (perhaps in-place) can be used to implement unaligned integers.
+
+ - Beman: Does the use of the unrolling templates get in the way of processor
+ specific optimization code?
+ - Test use of endian integers with stream inserters and extractors.
+ - Continue work on benchmarks and timings. Consider using use-case example
+ programs as benchmarks.
+ -
+
+ > The reorder fuction should provide both reorder in place and returned.
+ Interesting, but providing two ways of doing something is often
+ considered the not best design practice. And the tests I've run so far
+ don't indicate any efficiency concern. Once all other aspects of the
+ interface and implementation are settled, let's revisit that question.
+
+ - > The endianness scoped enum native should be replaced so it is defined
+ > depending on the endianess of the platform.
+ >
+ > BOOST_SCOPED_ENUM_START(endianness) { big, little, native=(big or
+ little)
+ > }; BOOST_SCOPED_ENUM_END
+ >
+ > This will have the advantage to reduce of 1/3 the number of specializations.
+
+ Does this work?
+
+ -
+
+ > The library should provide in addition endian conversion functions that
+ have
+ > the endiannes as template parameters to make possible generic functions.
+ 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.
Infrastructure
@@ -131,13 +242,14 @@
> might speed up the compilation time of the testsuite by something like
50ms ;)
Will do.
+
- Make the bin() functionality available
Performance
Acknowledge
Gordon Woodhull, Hartmut Kaiser, Phil Endecott, tymofey, Giovanni Piero Deretta, Pyry Jahkola,
John Filo, Vitaly Budovski, Tomas Puverle, Vicente J. Botet Escriba, Tim
-Blechmann, Daniel James, Mathias Gaunard
+Blechmann, Daniel James, Mathias Gaunard, Adder, Tim Moore
Paul Bristow docs help