README.md

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 "nonstd/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 -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 integral value v, when C++17's relaxation of the enum value construction rule is not available.

License

byte lite is distributed under the Boost Software 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 algorithms 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

Standard selection macro

-Dbyte_CPLUSPLUS=199711L
Define this macro to override the auto-detection of the supported C++ standard, if your compiler does not set the __cpluplus macro correctly.

Select std::byte or nonstd::byte

At default, byte lite uses std::byte if it is available and lets you use it via namespace nonstd. You can however override this default and explicitly request to use std::byte or byte lite's nonstd::byte as nonstd::byte via the following macros.

-Dbyte_CONFIG_SELECT_BYTE=byte_BYTE_DEFAULT
Define this to byte_BYTE_STD to select std::byte as nonstd::byte. Define this to byte_BYTE_NONSTD to select nonstd::byte as nonstd::byte. Default is undefined, which has the same effect as defining to byte_BYTE_DEFAULT.

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), 9 (2008), 10 (2010), 11 (2012), 12 (2013), 14 (2015), 15 (2017)
GNU/Linux	Clang/LLVM	3.5 - 6.0
	GCC	4.8 - 8
OS X	Clang/LLVM	Xcode 6, Xcode 7, Xcode 8, Xcode 9

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" -DBYTE_LITE_OPT_BUILD_TESTS=ON ..
   

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 Compile-time information

The version of byte lite is available via tag [.version]. The following tags are available for information on the compiler and on the C++ standard library used: [.compiler], [.stdc++], [.stdlanguage] and [.stdlibrary].

A.2 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: Allows strict aliasing
byte: Provides constexpr non-assignment operations (C++11)
byte: Provides constexpr assignment operations (C++14)