Endian Library TODO List

To Do

Format Review Comments

Interesting

• John Filo - "Absolutely. I'd like to see support for float and double, but
  even without those additions, I still vote yes." "For those who deal with non-native endian data, this library is
  extremely useful. It automatically eliminates a whole class of common
  programming errors when dealing with such data."
   

• Hartmut Kaiser - "Even if this is not a full review, I would like to vote YES to include this
  library into Boost.

  Boost.Spirit is using (and shipping) with an older version of this library
  for several years now and we never had any problems with its usage in
  Spirit. It is used as the underlying framework for the binary parsers and
  generators and it is functioning as advertised.

  As a quick test I replaced the internal (older) version of Boost.Endian in
  Spirit with the reviewed version. All of Spirits regression tests still
  pass. "
   

Executive summary

• 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

• one other point ... the help file seems to directly link to the c++ headers.
  this should be changed:
  
  * some browsers (at least chromium) will not display the header when clicking
   the link, but will save them on disk.
  
  * providing a direct link to the source code from the docs implies that the
   user will get some information that are necessary to use the library by
   reading the sources. imo, this is not the case for using boost.endian.
  
  * if a user opens integer.hpp, the first 60 lines just contain copyright, some
   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.
   

Last revised: 17 January, 2015

© Copyright Beman Dawes, 2012

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