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 x=Unsigned(0)) |
| Number of bits in a type or value. | |
| template<typename Unsigned > | |
| Unsigned | all (bool b=true) |
| Generate a value with all bits set or cleared. | |
| 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) |
Function Documentation
◆ lowMask()
|
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.
◆ allLsb()
|
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().
◆ highMask()
|
inline |
◆ select()
|
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().
◆ shiftLeft()
|
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().
◆ shiftLeftLsb()
|
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().
◆ shiftRight()
|
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().
◆ shiftRightLsb()
|
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().
◆ position()
|
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().
◆ positionLsb()
|
inline |
◆ mask()
|
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().
◆ maskLsb()
|
inline |
◆ bit()
|
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().
◆ bitLsb()
|
inline |
◆ msb()
|
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().
◆ msbLsb()
|
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().
◆ shiftRightSigned() [1/2]
|
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().
◆ shiftRightSigned() [2/2]
|
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().
◆ bits()
|
inline |
Extract part of a value.
Extracts the bits in the range least through @greatest (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().
◆ bitsLsb()
|
inline |
Extract part of a value limited by width.
Extracts the bits in the range least through @greatest (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().
◆ convert()
|
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().
◆ convertSigned()
|
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().
◆ signExtend()
|
inline |
◆ signExtendLsb()
|
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().
◆ rotateLeft()
|
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().
◆ rotateLeftLsb()
|
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().
◆ rotateRight()
|
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().
◆ rotateRightLsb()
|
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().
◆ replicate()
|
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().
◆ replicateLsb()
|
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().
◆ highestSetBit()
|
inline |
