njlr / byte-lite

A single-file header-only C++17-like byte type for C++98, C++11 and later

byte-lite: A single-file header-only C++17-like byte type for C++98, C++11 and later

Contents

• Example usage
• In a nutshell
• License
• Dependencies
• Installation
• Synopsis
• Features
• Reported to work with
• Building the tests
• Other implementations of byte
• Notes and references
• Appendix

Example usage

#include "byte.hpp"

#include <cassert>

using namespace nonstd;

int main()
{
    byte b1 = to_byte( 0x5a );  // to_byte() is non-standard, needed for pre-C++17
    byte b2 = to_byte( 0xa5 );

    byte r1 = b1 ^ b2; assert( 0xff == to_integer( r1 ) );  // not (yet) standard, needs C++11
    byte r2 = b1 ^ b2; assert( 0xff == to_integer<unsigned int>( r2 ) );
}

Compile and run

prompt> g++ -std=c++11 -Wall -I../include/nonstd -o 01-basic 01-basic.cpp && 01-basic

Or to run with Buck:

prompt> buck run example:01-basic

In a nutshell

byte lite is a single-file header-only library to provide a C++17-like distinct byte type for use with C++98 and later.

Features and properties of byte lite are are ease of installation (single header), freedom of dependencies other than the standard library.

A limitation of byte lite is that you need to use function to_byte(v) to construct a byte from an intergal value v, when C++17's relaxation of the enum value construction rule is not available.

License

byte lite uses the MIT license.

Dependencies

byte lite has no other dependencies than the C++ standard library.

Installation

byte lite is a single-file header-only library. Put byte.hpp in the include folder directly into the project source tree or somewhere reachable from your project.

Synopsis

Contents

• Types in namespace nonstd
• Algorithms for byte lite
• Configuration macros

Types in namespace nonstd

Purpose	Type	Std	Notes
Distinct byte type	enum class byte	>=C++17
	struct byte	< C++17

Algorithms for byte lite

Kind	Std	Function	Result
Shift-assign		template< class IntegerType > constexpr byte & operator<<=( byte & b, IntegerType shift ) noexcept	left-shifted b
		template< class IntegerType > constexpr byte & operator>>=( byte & b, IntegerType shift ) noexcept	right-shifted b
Shift		template< class IntegerType > constexpr byte operator<<( byte b, IntegerType shift ) noexcept	left-shifted byte
		template< class IntegerType > constexpr byte operator>>( byte b, IntegerType shift ) noexcept	right-shifted byte
Bitwise-op-assign		template< class IntegerType > constexpr byte & operator¦=( byte & l, byte r ) noexcept	bitwise-or-ed b
		template< class IntegerType > constexpr byte & operator&=( byte & l, byte r ) noexcept	bitwise-xor-ed b
		template< class IntegerType > constexpr byte & operator^=( byte & l, byte r ) noexcept	bitwise-and-ed b
Bitwise-op		template< class IntegerType > constexpr byte & operator¦( byte l, byte r ) noexcept	bitwise-or-ed byte
		template< class IntegerType > constexpr byte & operator&( byte l, byte r ) noexcept	bitwise-xor-ed byte
		template< class IntegerType > constexpr byte & operator^( byte l, byte r ) noexcept	bitwise-and-ed byte
Conversion	non-std	template< class IntegerType > constexpr byte to_byte( IntegerType v )	byte with value v
	>=C++11	template< class IntegerType = underlying-type > constexpr IntegerType to_integer( byte b )	byte's value, note 2, 3
	< C++11	template< class IntegerType > constexpr IntegerType to_integer( byte b )	byte's value, note 3

Note 1: the algrithms use an extra level of casting to prevent undefined behaviour, as mentioned by Thomas Köppe on mailing list isocpp-lib, subject "std::byte operations are hard to use correctly", on 16 March 2017.

Note 2: default template parameter as suggested by Zhihao Yuan on mailing list isocpp-lib, subject "std::byte to_integer<>", on 10 March 2017.

Note 3: use to_integer() to compute a byte's hash value.

Configuration macros

Currently there are no configuration macros.

Reported to work with

The table below mentions the compiler versions byte lite is reported to work with.

OS	Compiler	Versions
Windows	Clang/LLVM	?
	GCC	5.2.0
	Visual C++ (Visual Studio)	6 (6), 8 (2005), 10 (2010), 11 (2012), 12 (2013), 14 (2015), 14 (2017)
GNU/Linux	Clang/LLVM	3.5.0
	GCC	4.8.4
OS X	?	?

Building the tests

To build the tests you need:

• CMake, version 2.8.12 or later to be installed and in your PATH.
• A suitable compiler.

The lest test framework is included in the test folder.

The following steps assume that the byte lite source code has been cloned into a directory named c:\byte-lite.

1. Create a directory for the build outputs for a particular architecture. Here we use c:\byte-lite\build-win-x86-vc10.

    cd c:\byte-lite
    md build-win-x86-vc10
    cd build-win-x86-vc10
   

2. Configure CMake to use the compiler of your choice (run cmake --help for a list).

    cmake -G "Visual Studio 10 2010" ..
   

3. Build the test suite in the Debug configuration (alternatively use Release).

    cmake --build . --config Debug
   

4. Run the test suite.

    ctest -V -C Debug
   

All tests should pass, indicating your platform is supported and you are ready to use byte lite.

Other implementations of byte

• Martin Moene. gsl lite. C++98 and later.
• Microsoft. Guideline Support Library (GSL). C++14 (supports MSVC 2013 and 2015).

Notes and References

[1] CppReference. byte.

[2] ISO/IEC WG21. N4659, section 21.2.1, Header synopsis. March 2017.

[3] Neil MacIntosh. P0298: A byte type definition (Revision 3). March 2017.

Appendix

A.1 byte lite test specification

byte: Allows to construct from integral via static cast (C++17)
byte: Allows to construct from integral via byte() (C++17)
byte: Allows to construct from integral via to_byte()
byte: Allows to convert to integral via to_integer()
byte: Allows to convert to integral via to_integer(), using default type
byte: Allows comparison operations
byte: Allows bitwise or operation
byte: Allows bitwise and operation
byte: Allows bitwise x-or operation
byte: Allows bitwise or assignment
byte: Allows bitwise and assignment
byte: Allows bitwise x-or assignment
byte: Allows shift-left operation
byte: Allows shift-right operation
byte: Allows shift-left assignment
byte: Allows shift-right assignment
byte: Provides constexpr non-assignment operations (C++11)
byte: Provides constexpr assignment operations (C++14)