Description

Bit operations on unsigned integers.

This namespace provides functions that operate at the bit level on unsigned integer types and avoid C/C++ undefined behavior.

Functions
template<typename Unsigned >
size_t	nBits (Unsigned=Unsigned(0))
	Number of bits in a type or value. More...

template<typename Unsigned >
Unsigned	all (bool b=true)
	Generate a value with all bits set or cleared. More...

template<typename Unsigned >
Unsigned	lowMask (size_t n)
	Generate a value with low order bits set. More...

template<typename Unsigned >
Unsigned	allLsb (Unsigned src, size_t w, bool b=true)
	Set or clear the low-order bits. More...

template<typename Unsigned >
Unsigned	highMask (size_t n)
	Generate a value with high order bits set. More...

template<typename Unsigned >
Unsigned	select (Unsigned cond, Unsigned a, Unsigned b)
	Combine two values based on a bit mask. More...

template<typename Unsigned >
Unsigned	shiftLeft (Unsigned src, size_t n, bool b=false)
	Left shift a value. More...

template<typename Unsigned >
Unsigned	shiftLeftLsb (Unsigned src, size_t w, size_t n, bool b=false)
	Left shift part of a value without affecting the rest. More...

template<typename Unsigned >
Unsigned	shiftRight (Unsigned src, size_t n, bool b=false)
	Right shift a value. More...

template<typename Unsigned >
Unsigned	shiftRightLsb (Unsigned src, size_t w, size_t n, bool b=false)
	Right shift part of a value without affecting the rest. More...

template<typename Unsigned >
Unsigned	position (size_t i)
	Generate a single-bit mask. More...

template<typename Unsigned >
Unsigned	positionLsb (Unsigned src, size_t w, size_t i)
	Generate a single-bit mask without affecting the high-order bits. More...

template<typename Unsigned >
Unsigned	mask (size_t least, size_t greatest)
	Generate a mask. More...

template<typename Unsigned >
Unsigned	maskLsb (Unsigned src, size_t w, size_t least, size_t greatest)
	Generate a mask without affecting other bits. More...

template<typename Unsigned >
bool	bit (Unsigned src, size_t i)
	Extract a single bit. More...

template<typename Unsigned >
bool	bitLsb (Unsigned src, size_t w, size_t i)
	Extract a single bit. More...

template<typename Unsigned >
bool	msb (Unsigned src)
	Most significant bit. More...

template<typename Unsigned >
bool	msbLsb (Unsigned src, size_t w)
	Most significant bit within lsb region. More...

template<typename Unsigned >
Unsigned	shiftRightSigned (Unsigned src, size_t n)
	Right shift replicating MSB. More...

template<typename Unsigned >
Unsigned	shiftRightSigned (Unsigned src, size_t w, size_t n)
	Right shift low bits without affecting other bits. More...

template<typename Unsigned >
Unsigned	bits (Unsigned src, size_t least, size_t greatest)
	Extract part of a value. More...

template<typename Unsigned >
Unsigned	bitsLsb (Unsigned src, size_t w, size_t least, size_t greatest)
	Extract part of a value limited by width. More...

template<typename UnsignedTarget , typename UnsignedSource >
UnsignedTarget	convert (UnsignedSource x, bool b=false)
	Extend or truncate a value. More...

template<typename UnsignedTarget , typename UnsignedSource >
UnsignedTarget	convertSigned (UnsignedSource x)
	Sign extend or truncate a value. More...

template<typename Unsigned >
Unsigned	signExtend (Unsigned src, size_t n)
	Sign extend part of a value to the full width of the src type. More...

template<typename Unsigned >
Unsigned	signExtendLsb (Unsigned src, size_t n, size_t m)
	Sign extend part of value without affecting other bits. More...

template<typename Unsigned >
Unsigned	rotateLeft (Unsigned src, size_t n)
	Rotate bits left. More...

template<typename Unsigned >
Unsigned	rotateLeftLsb (Unsigned src, size_t w, size_t n)
	Rotate low-order bits left without affecting others. More...

template<typename Unsigned >
Unsigned	rotateRight (Unsigned src, size_t n)
	Rotate bits right. More...

template<typename Unsigned >
Unsigned	rotateRightLsb (Unsigned src, size_t w, size_t n)
	Rotate low-order bits right without affecting others. More...

template<typename Unsigned >
Unsigned	replicate (Unsigned src, size_t n)
	Replicate low-order bits to fill return value. More...

template<typename Unsigned >
Unsigned	replicateLsb (Unsigned src, size_t w, size_t n)
	Replicate low-order bits to fill region without affecting other bits. More...

template<typename Unsigned >
Sawyer::Optional< size_t >	highestSetBit (Unsigned src)
	Index of the highest set bit. More...

template<typename Unsigned >
size_t	nSet (Unsigned src)

template<class T >
std::enable_if< std::is_integral< T >::value, T >::type	reverseBytes (const T &x)
	Reverse the bytes. More...

bool	isBigEndian ()
	True if host is big endian. More...

bool	isLittleEndian ()
	True if host is little endian. More...

template<class T >
std::enable_if< std::is_integral< T >::value, T >::type	toBigEndian (const T x)
	Convert integral value from host order to big endian. More...

template<class T >
std::enable_if< std::is_integral< T >::value, T >::type	toLittleEndian (const T x)
	Convert integral value from host order to little endian. More...

template<class T >
std::enable_if< std::is_integral< T >::value, T >::type	fromBigEndian (const T x)
	Convert integral value from big endian to host order. More...

template<class T >
std::enable_if< std::is_integral< T >::value, T >::type	fromLittleEndian (const T x)
	Convert integral value from little endian to host order. More...

Function Documentation

template<typename Unsigned >

size_t Rose::BitOps::nBits ( Unsigned = Unsigned(0) )

inline

Number of bits in a type or value.

Definition at line 17 of file BitOps.h.

Referenced by allLsb(), convert(), highestSetBit(), maskLsb(), msb(), msbLsb(), positionLsb(), replicate(), replicateLsb(), rotateLeft(), rotateLeftLsb(), rotateRight(), rotateRightLsb(), shiftLeft(), shiftLeftLsb(), shiftRight(), shiftRightLsb(), signExtend(), signExtendLsb(), and Rose::StringUtility::toBinary().

template<typename Unsigned >

Unsigned Rose::BitOps::all ( bool b = true )

inline

Generate a value with all bits set or cleared.

Definition at line 23 of file BitOps.h.

template<typename Unsigned >

Unsigned Rose::BitOps::lowMask ( size_t n )

inline

Generate a value with low order bits set.

Returns a value whose n low-order bits are set and all the other higher order bits are cleared. If n is greater than or equal to the size of the unsigned type then the returned value has all bits set. If n is zero then no bits are set in the return value.

Definition at line 48 of file BitOps.h.

template<typename Unsigned >

Unsigned Rose::BitOps::allLsb	(	Unsigned	src,
		size_t	w,
		bool	b = `true`
	)

inline

Set or clear the low-order
bits.

Sets or clears the low order bits of the input value without affecting any of the other bits.

Definition at line 33 of file BitOps.h.

References nBits().

Referenced by shiftLeftLsb(), and shiftRightLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::highMask ( size_t n )

inline

Generate a value with high order bits set.

Returns a value whose n high-order bits are set and the other low order bits are cleared. If n is greater than or equal to the size of the unsigned type then the returned value has all bits set.

Definition at line 57 of file BitOps.h.

template<typename Unsigned >

Unsigned Rose::BitOps::select	(	Unsigned	cond,
		Unsigned	a,
		Unsigned	b
	)

inline

Combine two values based on a bit mask.

The return value has bits from a and b depending on the mask cond. If the mask bit i is set, then the return value bit i comes from a, otherwise it comes from b.

Definition at line 66 of file BitOps.h.

Referenced by maskLsb(), positionLsb(), replicateLsb(), rotateLeftLsb(), rotateRightLsb(), shiftLeftLsb(), and shiftRightLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::shiftLeft	(	Unsigned	src,
		size_t	n,
		bool	b = `false`
	)

inline

Left shift a value.

The value src has its bits shifted n places toward higher order. The
highest order bits are discarded and the n new low-order bits are either set or cleared depending on the value of b. If n is greater than or equal to the number of bits in src then the return value has either all bits set or all bits cleared depending on b.

Definition at line 76 of file BitOps.h.

References nBits().

Referenced by mask(), position(), replicate(), rotateLeft(), rotateRight(), and shiftLeftLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::shiftLeftLsb	(	Unsigned	src,
		size_t	w,
		size_t	n,
		bool	b = `false`
	)

inline

Left shift part of a value without affecting the rest.

The value src has its low-order w bits shifted n places toward higher order. The
highest bits are discarded and the n new lower order bits are either set or cleared depending on the value of b. If n is greater than or equal to w then all affected bits are set or cleared, depending on b. The bits not in the affected range are not affected and are returned.

Definition at line 91 of file BitOps.h.

References allLsb(), nBits(), select(), and shiftLeft().

Referenced by rotateLeftLsb(), and rotateRightLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::shiftRight	(	Unsigned	src,
		size_t	n,
		bool	b = `false`
	)

inline

Right shift a value.

Shift all bits of the value right (to lower indices) by n. The n low-order bits are discarded and the new n high-order bits are set or cleared depending on b. If n is greater than or equal to the size of src then the return value has either all bits set or all bits cleared depending on b.

Definition at line 106 of file BitOps.h.

References nBits().

Referenced by bits(), bitsLsb(), rotateLeft(), rotateRight(), shiftRightLsb(), and shiftRightSigned().

template<typename Unsigned >

Unsigned Rose::BitOps::shiftRightLsb	(	Unsigned	src,
		size_t	w,
		size_t	n,
		bool	b = `false`
	)

inline

Right shift part of a value without affecting the rest.

The value src has its low-order w bits shifted right toward lower order. The n lowest bits are discarded and the n new higher order bits are either set or cleared depending on b. If n is greater than or equal to w then all affected bits are set or cleared, depending on b. The bits not in the affected range are not affected and are returned.

Definition at line 120 of file BitOps.h.

References allLsb(), nBits(), select(), and shiftRight().

Referenced by rotateLeftLsb(), rotateRightLsb(), and shiftRightSigned().

template<typename Unsigned >

Unsigned Rose::BitOps::position ( size_t i )

inline

Generate a single-bit mask.

Returns a value that has all bit cleared except the bit at position i. If i is outside the valid range of bit positions for the unsigned type, then zero is returned.

Definition at line 134 of file BitOps.h.

References shiftLeft().

template<typename Unsigned >

Unsigned Rose::BitOps::positionLsb	(	Unsigned	src,
		size_t	w,
		size_t	i
	)

inline

Generate a single-bit mask without affecting the high-order bits.

The low order w bits of src are cleared except bit i is set, and other bits are not affected.

Definition at line 142 of file BitOps.h.

References nBits(), and select().

template<typename Unsigned >

Unsigned Rose::BitOps::mask	(	size_t	least,
		size_t	greatest
	)

inline

Generate a mask.

Returns a value where bits least through greatest (inclusive) are set and all other bits are cleared. The specified indexes must be valid for the type of x. In other words, greatest must be less than the number of bits in x and greatest must be greater than or equal to least.

Definition at line 153 of file BitOps.h.

References shiftLeft().

template<typename Unsigned >

Unsigned Rose::BitOps::maskLsb	(	Unsigned	src,
		size_t	w,
		size_t	least,
		size_t	greatest
	)

inline

Generate a mask without affecting other bits.

Generates a mask limited to the low order w bits without affecting the other bits of src.

Definition at line 163 of file BitOps.h.

References nBits(), and select().

template<typename Unsigned >

bool Rose::BitOps::bit	(	Unsigned	src,
		size_t	i
	)

inline

Extract a single bit.

The bit at position i of the value src is returned. If i is out of range for src then zero is returned.

Definition at line 172 of file BitOps.h.

Referenced by highestSetBit(), msb(), msbLsb(), signExtendLsb(), and Rose::StringUtility::toBinary().

template<typename Unsigned >

bool Rose::BitOps::bitLsb	(	Unsigned	src,
		size_t	w,
		size_t	i
	)

inline

Extract a single bit.

The bit at position i of value src is returned. If i is out of range for the specified value width then zero is returned.

Definition at line 181 of file BitOps.h.

template<typename Unsigned >

bool Rose::BitOps::msb ( Unsigned src )

inline

Most significant bit.

Returns the most significant bit. This is the sign bit for two's complement values.

Definition at line 189 of file BitOps.h.

References bit(), and nBits().

Referenced by convertSigned(), and shiftRightSigned().

template<typename Unsigned >

bool Rose::BitOps::msbLsb	(	Unsigned	src,
		size_t	w
	)

inline

Most significant bit within lsb region.

Returns the value of the most significant bit within the region of w low-order bits. If w is zero then returns false.

Definition at line 197 of file BitOps.h.

References bit(), and nBits().

Referenced by shiftRightSigned(), and signExtend().

template<typename Unsigned >

Unsigned Rose::BitOps::shiftRightSigned	(	Unsigned	src,
		size_t	n
	)

inline

Right shift replicating MSB.

Shift all bits of the value right (to lower indices) by n. The n low-order bits are discarded and the new n high-order bits are set or cleared depending on the original most significant bit. If n is greater than or equal to the size of src then the return value has either all bits set or all bits cleared depending on its original most significant bit.

Definition at line 209 of file BitOps.h.

References msb(), and shiftRight().

template<typename Unsigned >

Unsigned Rose::BitOps::shiftRightSigned	(	Unsigned	src,
		size_t	w,
		size_t	n
	)

inline

Right shift low bits without affecting other bits.

Right shift the low-order w bits by n without affecting higher order bits. The width, w, must not be larger than the src width. If
is greater than or equal to w then the w low order bits are set or cleared depending on bit w-1. Otherwise, the n low order bits are discarded and the n new bits introduced at index w-1 are either zero or one depending on bit w-1.

Definition at line 221 of file BitOps.h.

References msbLsb(), and shiftRightLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::bits	(	Unsigned	src,
		size_t	least,
		size_t	greatest
	)

inline

Extract part of a value.

Extracts the bits in the range least through (inclusive) and shifts them right by least bits. The least and greatest indices must be valid for src as defined by mask.

Definition at line 230 of file BitOps.h.

References shiftRight().

template<typename Unsigned >

Unsigned Rose::BitOps::bitsLsb	(	Unsigned	src,
		size_t	w,
		size_t	least,
		size_t	greatest
	)

inline

Extract part of a value limited by width.

Extracts the bits in the range least through (inclusive) and shifts them right by least bits. Any bits of src at index w or greater are treated as zeros.

Definition at line 239 of file BitOps.h.

References shiftRight().

template<typename UnsignedTarget , typename UnsignedSource >

UnsignedTarget Rose::BitOps::convert	(	UnsignedSource	x,
		bool	b = `false`
	)

inline

Extend or truncate a value.

When the destination type is smaller than the source type, the most significant bits of the source value are discarded, otherwise the most significant bits of the destination type are set to b.

Definition at line 249 of file BitOps.h.

References nBits().

template<typename UnsignedTarget , typename UnsignedSource >

UnsignedTarget Rose::BitOps::convertSigned ( UnsignedSource x )

inline

Sign extend or truncate a value.

This is identical to convert except when the target value is wider than the source value the new bits of the return value are all set to the most significant bit of the source value.

Definition at line 264 of file BitOps.h.

References msb().

template<typename Unsigned >

Unsigned Rose::BitOps::signExtend	(	Unsigned	src,
		size_t	n
	)

inline

Sign extend part of a value to the full width of the src type.

The low order n bits are treated as a signed integer and sign extended to fill the entire width of the return value.

Definition at line 272 of file BitOps.h.

References msbLsb(), and nBits().

template<typename Unsigned >

Unsigned Rose::BitOps::signExtendLsb	(	Unsigned	src,
		size_t	n,
		size_t	m
	)

inline

Sign extend part of value without affecting other bits.

Sign extends the low-order n bits of the input value to occupy the lower order m bits of the output, where m is greater than or equal to n and less than or equal to the number of bits in the src value.

Definition at line 288 of file BitOps.h.

References bit(), and nBits().

template<typename Unsigned >

Unsigned Rose::BitOps::rotateLeft	(	Unsigned	src,
		size_t	n
	)

inline

Rotate bits left.

Rotates the bits of src left (toward higher indices) by n bits. This is similar to shiftLeft except the high order bits that would normally be discarded are reintroduced in the low order positions. If n is zero then this is a no-op. The rotation amount is calculated modulo the width of src

Definition at line 310 of file BitOps.h.

References nBits(), shiftLeft(), and shiftRight().

template<typename Unsigned >

Unsigned Rose::BitOps::rotateLeftLsb	(	Unsigned	src,
		size_t	w,
		size_t	n
	)

inline

Rotate low-order bits left without affecting others.

Rotates the low-order w bits of src left by n bits without affecting the other bits, and returns the result. The rotation amount is modulo w. If w is zero then the original value is returned.

Definition at line 320 of file BitOps.h.

References nBits(), select(), shiftLeftLsb(), and shiftRightLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::rotateRight	(	Unsigned	src,
		size_t	n
	)

inline

Rotate bits right.

Rotates the bits of src right (toward lower indices) by n bits. This is similar to shiftRight except the low order bits that would normally be discarded are reintroduced in the high order positions. If n is zero then this is a no-op. The rotation amount is calculated modulo the width of src.

Definition at line 334 of file BitOps.h.

References nBits(), shiftLeft(), and shiftRight().

template<typename Unsigned >

Unsigned Rose::BitOps::rotateRightLsb	(	Unsigned	src,
		size_t	w,
		size_t	n
	)

inline

Rotate low-order bits right without affecting others.

Rotates the low-order w bits of src right by n bits without affecting the higher-order bits, and returns the result. The rotation amount is modulo w. If w is zero then the original value is returned.

Definition at line 344 of file BitOps.h.

References nBits(), select(), shiftLeftLsb(), and shiftRightLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::replicate	(	Unsigned	src,
		size_t	n
	)

inline

Replicate low-order bits to fill return value.

The n low-order bits of src are repeated as a group as many times as necessary to fill the entire return value. For instance, if src contains 0xabcdef and n is 8 and the return type is a 32-bit unsigned integer, then the return value will be 0xefefefef. If the width of the return value is not an integer multiple of n, then the high order bits of the return value will contain only some of the lowest order bits of the src. The value of n cannot be zero.

Definition at line 359 of file BitOps.h.

References nBits(), and shiftLeft().

Referenced by replicateLsb().

template<typename Unsigned >

Unsigned Rose::BitOps::replicateLsb	(	Unsigned	src,
		size_t	w,
		size_t	n
	)

inline

Replicate low-order bits to fill region without affecting other bits.

This is identical to replicate except that instead of filling the entire return value with the replicated bits, at most w low-order bits of the return value are filled with replicated bits and the remaining high order bits are copied from src.

Definition at line 378 of file BitOps.h.

References nBits(), replicate(), and select().

template<typename Unsigned >

Sawyer::Optional<size_t> Rose::BitOps::highestSetBit ( Unsigned src )

inline

Index of the highest set bit.

If no bits are set then this returns nothing. Otherwise it returns the zero-origin index of the highest order set bit.

Definition at line 387 of file BitOps.h.

References bit(), and nBits().

template<class T >

std::enable_if<std::is_integral<T>::value, T>::type Rose::BitOps::reverseBytes ( const T & x )

inline