Crypto++ 8.4 Free C++ class library of cryptographic schemes

Classes | Macros | Typedefs | Functions
misc.h File Reference

Utility functions for the Crypto++ library. More...

Go to the source code of this file.

## Classes
class | Empty
| An Empty class. More...
class | ObjectHolder< T >
| Uses encapsulation to hide an object in derived classes. More...
class | NotCopyable
| Ensures an object is not copyable. More...
struct | NewObject< T >
| An object factory function. More...
class | Singleton< T, F, instance >
| Restricts the instantiation of a class to one static object without locks. More...
class | GetBlock< T, B, A >
| Access a block of memory. More...
class | PutBlock< T, B, A >
| Access a block of memory. More...
struct | BlockGetAndPut< T, B, GA, PA >
| Access a block of memory. More...
struct | SafeShifter< overflow >
| Safely shift values when undefined behavior could occur. More...
struct | SafeShifter< true >
| Shifts a value in the presence of overflow. More...
struct | SafeShifter< false >
| Shifts a value in the absence of overflow. More...

## Macros
#define | SIZE_MAX ...
| The maximum value of a machine word. More...
#define | CRYPTOPP_COMPILE_ASSERT(expr) { ... }
| Compile time assertion. More...
#define | COUNTOF(arr)
| Counts elements in an array. More...
#define | MEMORY_BARRIER ...
| A memory barrier. More...
#define | RETURN_IF_NONZERO(x) size_t returnedValue = x; if (returnedValue) return returnedValue
#define | GETBYTE(x, y) (unsigned int)byte((x)>>(8*(y)))
#define | CRYPTOPP_GET_BYTE_AS_BYTE(x, y) byte((x)>>(8*(y)))
#define | CRYPTOPP_BLOCK_1(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+0);} size_t SS1() {return sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_2(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS1());} size_t SS2() {return SS1()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_3(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS2());} size_t SS3() {return SS2()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_4(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS3());} size_t SS4() {return SS3()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_5(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS4());} size_t SS5() {return SS4()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_6(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS5());} size_t SS6() {return SS5()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_7(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS6());} size_t SS7() {return SS6()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCK_8(n, t, s) t* m_##n() {return (t *)(void *)(m_aggregate+SS7());} size_t SS8() {return SS7()+sizeof(t)*(s);} size_t m_##n##Size() {return (s);}
#define | CRYPTOPP_BLOCKS_END(i) size_t SST() {return SS##i();} void AllocateBlocks() {m_aggregate.New(SST());} AlignedSecByteBlock m_aggregate;

## Typedefs
typedef LittleEndian | NativeByteOrder

## Functions
template<typename PTR , typename OFF >
PTR | PtrAdd (PTR pointer, OFF offset)
| Create a pointer with an offset. More...
template<typename PTR , typename OFF >
PTR | PtrSub (PTR pointer, OFF offset)
| Create a pointer with an offset. More...
template<typename PTR >
ptrdiff_t | PtrDiff (const PTR pointer1, const PTR pointer2)
| Determine pointer difference. More...
template<typename PTR >
size_t | PtrByteDiff (const PTR pointer1, const PTR pointer2)
| Determine pointer difference. More...
byte * | BytePtr (std::string &str)
| Pointer to the first element of a string. More...
byte * | BytePtr (SecByteBlock &str)
| Pointer to the first element of a string. More...
const byte * | ConstBytePtr (const std::string &str)
| Const pointer to the first element of a string. More...
const byte * | ConstBytePtr (const SecByteBlock &str)
| Const pointer to the first element of a string. More...
size_t | BytePtrSize (const std::string &str)
| Size of a string. More...
size_t | BytePtrSize (const SecByteBlock &str)
| Size of a string. More...
void | memcpy_s (void *dest, size_t sizeInBytes, const void *src, size_t count)
| Bounds checking replacement for memcpy() More...
void | memmove_s (void *dest, size_t sizeInBytes, const void *src, size_t count)
| Bounds checking replacement for memmove() More...
template<class T >
void | vec_swap (T &a, T &b)
| Swaps two variables which are arrays. More...
void * | memset_z (void *ptr, int val, size_t num)
| Memory block initializer. More...
template<class T >
const T & | STDMIN (const T &a, const T &b)
| Replacement function for std::min. More...
template<class T >
const T & | STDMAX (const T &a, const T &b)
| Replacement function for std::max. More...
template<class T1 , class T2 >
const T1 | UnsignedMin (const T1 &a, const T2 &b)
| Safe comparison of values that could be neagtive and incorrectly promoted. More...
template<class T1 , class T2 >
bool | SafeConvert (T1 from, T2 &to)
| Tests whether a conversion from -> to is safe to perform. More...
template<class T >
std::string | IntToString (T value, unsigned int base=10)
| Converts a value to a string. More...
template<>
CRYPTOPP_DLL std::string | IntToString< word64 > (word64 value, unsigned int base)
| Converts an unsigned value to a string. More...
template<>
CRYPTOPP_DLL std::string | IntToString< Integer > (Integer value, unsigned int base)
| Converts an Integer to a string. More...
template<class T >
unsigned int | Parity (T value)
| Returns the parity of a value. More...
template<class T >
unsigned int | BytePrecision (const T &value)
| Returns the number of 8-bit bytes or octets required for a value. More...
template<class T >
unsigned int | BitPrecision (const T &value)
| Returns the number of bits required for a value. More...
unsigned int | TrailingZeros (word32 v)
| Determines the number of trailing 0-bits in a value. More...
unsigned int | TrailingZeros (word64 v)
| Determines the number of trailing 0-bits in a value. More...
template<class T >
T | Crop (T value, size_t bits)
| Truncates the value to the specified number of bits. More...
size_t | BitsToBytes (size_t bitCount)
| Returns the number of 8-bit bytes or octets required for the specified number of bits. More...
size_t | BytesToWords (size_t byteCount)
| Returns the number of words required for the specified number of bytes. More...
size_t | BitsToWords (size_t bitCount)
| Returns the number of words required for the specified number of bits. More...
size_t | BitsToDwords (size_t bitCount)
| Returns the number of double words required for the specified number of bits. More...
CRYPTOPP_DLL void | xorbuf (byte *buf, const byte *mask, size_t count)
| Performs an XOR of a buffer with a mask. More...
CRYPTOPP_DLL void | xorbuf (byte *output, const byte *input, const byte *mask, size_t count)
| Performs an XOR of an input buffer with a mask and stores the result in an output buffer. More...
CRYPTOPP_DLL bool | VerifyBufsEqual (const byte *buf1, const byte *buf2, size_t count)
| Performs a near constant-time comparison of two equally sized buffers. More...
template<class T >
bool | IsPowerOf2 (const T &value)
| Tests whether a value is a power of 2. More...
template<class T >
T | NumericLimitsMin ()
| Provide the minimum value for a type. More...
template<class T >
T | NumericLimitsMax ()
| Provide the maximum value for a type. More...
template<>
word128 | NumericLimitsMin ()
template<>
word128 | NumericLimitsMax ()
template<class T1 , class T2 >
T1 | SaturatingSubtract (const T1 &a, const T2 &b)
| Performs a saturating subtract clamped at 0. More...
template<class T1 , class T2 >
T1 | SaturatingSubtract1 (const T1 &a, const T2 &b)
| Performs a saturating subtract clamped at 1. More...
template<class T1 , class T2 >
T2 | ModPowerOf2 (const T1 &a, const T2 &b)
| Reduces a value to a power of 2. More...
template<class T1 , class T2 >
T1 | RoundDownToMultipleOf (const T1 &n, const T2 &m)
| Rounds a value down to a multiple of a second value. More...
template<class T1 , class T2 >
T1 | RoundUpToMultipleOf (const T1 &n, const T2 &m)
| Rounds a value up to a multiple of a second value. More...
template<class T >
unsigned int | GetAlignmentOf ()
| Returns the minimum alignment requirements of a type. More...
bool | IsAlignedOn (const void *ptr, unsigned int alignment)
| Determines whether ptr is aligned to a minimum value. More...
template<class T >
bool | IsAligned (const void *ptr)
| Determines whether ptr is minimally aligned. More...
ByteOrder | GetNativeByteOrder ()
| Returns NativeByteOrder as an enumerated ByteOrder value. More...
bool | NativeByteOrderIs (ByteOrder order)
| Determines whether order follows native byte ordering. More...
template<class T >
CipherDir | GetCipherDir (const T &obj)
| Returns the direction the cipher is being operated. More...
void | IncrementCounterByOne (byte *inout, unsigned int size)
| Performs an addition with carry on a block of bytes. More...
void | IncrementCounterByOne (byte *output, const byte *input, unsigned int size)
| Performs an addition with carry on a block of bytes. More...
template<class T >
void | ConditionalSwap (bool c, T &a, T &b)
| Performs a branchless swap of values a and b if condition c is true. More...
template<class T >
void | ConditionalSwapPointers (bool c, T &a, T &b)
| Performs a branchless swap of pointers a and b if condition c is true. More...
template<class T >
void | SecureWipeBuffer (T *buf, size_t n)
| Sets each element of an array to 0. More...
template<>
void | SecureWipeBuffer (byte *buf, size_t n)
| Sets each byte of an array to 0. More...
template<>
void | SecureWipeBuffer (word16 *buf, size_t n)
| Sets each 16-bit element of an array to 0. More...
template<>
void | SecureWipeBuffer (word32 *buf, size_t n)
| Sets each 32-bit element of an array to 0. More...
template<>
void | SecureWipeBuffer (word64 *buf, size_t n)
| Sets each 64-bit element of an array to 0. More...
template<class T >
void | SecureWipeArray (T *buf, size_t n)
| Sets each element of an array to 0. More...
std::string | StringNarrow (const wchar_t *str, bool throwOnError=true)
| Converts a wide character C-string to a multibyte string. More...
std::wstring | StringWiden (const char *str, bool throwOnError=true)
| Converts a multibyte C-string to a wide character string. More...
template<unsigned int R, class T >
T | rotlConstant (T x)
| Performs a left rotate. More...
template<unsigned int R, class T >
T | rotrConstant (T x)
| Performs a right rotate. More...
template<class T >
T | rotlFixed (T x, unsigned int y)
| Performs a left rotate. More...
template<class T >
T | rotrFixed (T x, unsigned int y)
| Performs a right rotate. More...
template<class T >
T | rotlVariable (T x, unsigned int y)
| Performs a left rotate. More...
template<class T >
T | rotrVariable (T x, unsigned int y)
| Performs a right rotate. More...
template<class T >
T | rotlMod (T x, unsigned int y)
| Performs a left rotate. More...
template<class T >
T | rotrMod (T x, unsigned int y)
| Performs a right rotate. More...
template<class T >
unsigned int | GetByte (ByteOrder order, T value, unsigned int index)
| Gets a byte from a value. More...
byte | ByteReverse (byte value)
| Reverses bytes in a 8-bit value. More...
word16 | ByteReverse (word16 value)
| Reverses bytes in a 16-bit value. More...
word32 | ByteReverse (word32 value)
| Reverses bytes in a 32-bit value. More...
word64 | ByteReverse (word64 value)
| Reverses bytes in a 64-bit value. More...
byte | BitReverse (byte value)
| Reverses bits in a 8-bit value. More...
word16 | BitReverse (word16 value)
| Reverses bits in a 16-bit value. More...
word32 | BitReverse (word32 value)
| Reverses bits in a 32-bit value. More...
word64 | BitReverse (word64 value)
| Reverses bits in a 64-bit value. More...
template<class T >
T | BitReverse (T value)
| Reverses bits in a value. More...
template<class T >
T | ConditionalByteReverse (ByteOrder order, T value)
| Reverses bytes in a value depending upon endianness. More...
template<class T >
void | ByteReverse (T *out, const T *in, size_t byteCount)
| Reverses bytes in an element from an array of elements. More...
template<class T >
void | ConditionalByteReverse (ByteOrder order, T *out, const T *in, size_t byteCount)
| Conditionally reverses bytes in an element from an array of elements. More...
template<class T >
void | GetUserKey (ByteOrder order, T *out, size_t outlen, const byte *in, size_t inlen)
byte | UnalignedGetWordNonTemplate (ByteOrder order, const byte *block, const byte *)
word16 | UnalignedGetWordNonTemplate (ByteOrder order, const byte *block, const word16 *)
word32 | UnalignedGetWordNonTemplate (ByteOrder order, const byte *block, const word32 *)
word64 | UnalignedGetWordNonTemplate (ByteOrder order, const byte *block, const word64 *)
void | UnalignedbyteNonTemplate (ByteOrder order, byte *block, byte value, const byte *xorBlock)
void | UnalignedbyteNonTemplate (ByteOrder order, byte *block, word16 value, const byte *xorBlock)
void | UnalignedbyteNonTemplate (ByteOrder order, byte *block, word32 value, const byte *xorBlock)
void | UnalignedbyteNonTemplate (ByteOrder order, byte *block, word64 value, const byte *xorBlock)
template<class T >
T | GetWord (bool assumeAligned, ByteOrder order, const byte *block)
| Access a block of memory. More...
template<class T >
void | GetWord (bool assumeAligned, ByteOrder order, T &result, const byte *block)
| Access a block of memory. More...
template<class T >
void | PutWord (bool assumeAligned, ByteOrder order, byte *block, T value, const byte *xorBlock=NULL)
| Access a block of memory. More...
template<class T >
std::string | WordToString (T value, ByteOrder order=BIG_ENDIAN_ORDER)
| Convert a word to a string. More...
template<class T >
T | StringToWord (const std::string &str, ByteOrder order=BIG_ENDIAN_ORDER)
| Convert a string to a word. More...
template<unsigned int bits, class T >
T | SafeRightShift (T value)
| Safely right shift values when undefined behavior could occur. More...
template<unsigned int bits, class T >
T | SafeLeftShift (T value)
| Safely left shift values when undefined behavior could occur. More...
template<typename InputIt , typename T >
InputIt | FindIfNot (InputIt first, InputIt last, const T &value)
| Finds first element not in a range. More...

## Detailed Description

Utility functions for the Crypto++ library.

Definition in file misc.h.

## Macro Definition Documentation

## ◆ SIZE_MAX

#define SIZE_MAX ...

The maximum value of a machine word.

`SIZE_MAX` provides the maximum value of a machine word. The value is `0xffffffff` on 32-bit targets, and `0xffffffffffffffff` on 64-bit targets.

If `SIZE_MAX` is not defined, then `__SIZE_MAX__` is used if defined. If not defined, then `SIZE_T_MAX` is used if defined. If not defined, then the library uses `std::numeric_limits<size_t>::max()`.

The library prefers `__SIZE_MAX__` or `__SIZE_T_MAX__` because they are effectively `constexpr` that is optimized well by all compilers. `std::numeric_limits<size_t>::max()` is not always a `constexpr`, and it is not always optimized well.

Definition at line 116 of file misc.h.

## ◆ CRYPTOPP_COMPILE_ASSERT

#define CRYPTOPP_COMPILE_ASSERT | ( |  | expr | ) | { ... }

Compile time assertion.

Parameters

  expr | the expression to evaluate

Asserts the expression `expr` during compile. If C++14 and N3928 are available, then C++14 `static_assert` is used. Otherwise, a `CompileAssert` structure is used. When the structure is used a negative-sized array triggers the assert at compile time.

Definition at line 149 of file misc.h.

## ◆ COUNTOF

#define COUNTOF | ( |  | arr | ) |

Counts elements in an array.

Parameters

  arr | an array of elements

COUNTOF counts elements in an array. On Windows COUNTOF(x) is defined to `_countof(x)` to ensure correct results for pointers.

Note
  COUNTOF does not produce correct results with pointers, and an array must be used. `sizeof(x)/sizeof(x[0])` suffers the same problem. The risk is eliminated by using `_countof(x)` on Windows. Windows will provide the immunity for other platforms.

Definition at line 189 of file misc.h.

## ◆ MEMORY_BARRIER

#define MEMORY_BARRIER ...

A memory barrier.

MEMORY_BARRIER attempts to ensure reads and writes are completed in the absence of a language synchronization point. It is used by the Singleton class if the compiler supports it. The barrier is provided at the customary places in a double-checked initialization.

Internally, MEMORY_BARRIER uses `std::atomic_thread_fence` if C++11 atomics are available. Otherwise, `intrinsic(_ReadWriteBarrier)`, `_ReadWriteBarrier()` or `__asm__("" ::: "memory")` is used.

Definition at line 268 of file misc.h.

## Function Documentation

## ◆ PtrAdd()

template<typename PTR , typename OFF >

PTR PtrAdd | ( | PTR | pointer,
|  | OFF | offset
| ) |  |
| inline

Create a pointer with an offset.

Template Parameters

  PTR | a pointer type
  OFF | a size type

Parameters

  pointer | a pointer
  offset | a offset into the pointer

PtrAdd can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction.

Definition at line 384 of file misc.h.

## ◆ PtrSub()

template<typename PTR , typename OFF >

PTR PtrSub | ( | PTR | pointer,
|  | OFF | offset
| ) |  |
| inline

Create a pointer with an offset.

Template Parameters

  PTR | a pointer type
  OFF | a size type

Parameters

  pointer | a pointer
  offset | a offset into the pointer

PtrSub can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction.

Definition at line 397 of file misc.h.

## ◆ PtrDiff()

template<typename PTR >

ptrdiff_t PtrDiff | ( | const PTR | pointer1,
|  | const PTR | pointer2
| ) |  |
| inline

Determine pointer difference.

Template Parameters

  PTR | a pointer type

Parameters

  pointer1 | the first pointer
  pointer2 | the second pointer

PtrDiff can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction. pointer1 and pointer2 must point to the same object or array (or one past the end), and yields the number of elements (not bytes) difference.

Definition at line 412 of file misc.h.

## ◆ PtrByteDiff()

template<typename PTR >

size_t PtrByteDiff | ( | const PTR | pointer1,
|  | const PTR | pointer2
| ) |  |
| inline

Determine pointer difference.

Template Parameters

  PTR | a pointer type

Parameters

  pointer1 | the first pointer
  pointer2 | the second pointer

PtrByteDiff can be used to squash Clang and GCC UBsan findings for pointer addition and subtraction. pointer1 and pointer2 must point to the same object or array (or one past the end), and yields the number of bytes (not elements) difference.

Definition at line 427 of file misc.h.

## ◆ BytePtr() [1/2]

byte* BytePtr | ( | std::string & | str | ) |
| inline

Pointer to the first element of a string.

Parameters

  str | std::string

BytePtr returns NULL pointer for an empty string.

Returns
  Pointer to the first element of a string

Since
  Crypto++ 8.0

Definition at line 437 of file misc.h.

## ◆ BytePtr() [2/2]

byte* BytePtr | ( | SecByteBlock & | str | ) |

Pointer to the first element of a string.

Parameters

  str | SecByteBlock

BytePtr returns NULL pointer for an empty string.

Returns
  Pointer to the first element of a string

Since
  Crypto++ 8.3

## ◆ ConstBytePtr() [1/2]

const byte* ConstBytePtr | ( | const std::string & | str | ) |
| inline

Const pointer to the first element of a string.

Parameters

  str | std::string

ConstBytePtr returns non-NULL pointer for an empty string.

Returns
  Pointer to the first element of a string

Since
  Crypto++ 8.0

Definition at line 459 of file misc.h.

## ◆ ConstBytePtr() [2/2]

const byte* ConstBytePtr | ( | const SecByteBlock & | str | ) |

Const pointer to the first element of a string.

Parameters

  str | SecByteBlock

ConstBytePtr returns non-NULL pointer for an empty string.

Returns
  Pointer to the first element of a string

Since
  Crypto++ 8.3

## ◆ BytePtrSize() [1/2]

size_t BytePtrSize | ( | const std::string & | str | ) |
| inline

Size of a string.

Parameters

  str | std::string

Returns
  size of a string

Definition at line 476 of file misc.h.

## ◆ BytePtrSize() [2/2]

size_t BytePtrSize | ( | const SecByteBlock & | str | ) |

Size of a string.

Parameters

  str | SecByteBlock

Returns
  size of a string

## ◆ memcpy_s()

void memcpy_s | ( | void * | dest,
|  | size_t | sizeInBytes,
|  | const void * | src,
|  | size_t | count
| ) |  |
| inline

Bounds checking replacement for memcpy()

Parameters

  dest | pointer to the desination memory block
  sizeInBytes | size of the desination memory block, in bytes
  src | pointer to the source memory block
  count | the number of bytes to copy

Exceptions

  InvalidArgument |

ISO/IEC TR-24772 provides bounds checking interfaces for potentially unsafe functions like memcpy(), strcpy() and memmove(). However, not all standard libraries provides them, like Glibc. The library's memcpy_s() is a near-drop in replacement. Its only a near-replacement because the library's version throws an InvalidArgument on a bounds violation.

memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. If __STDC_WANT_SECURE_LIB__ is not defined or defined to 0, then the library makes memcpy_s() and memmove_s() available. The library will also optionally make the symbols available if `CRYPTOPP_WANT_SECURE_LIB` is defined. `CRYPTOPP_WANT_SECURE_LIB` is in config.h, but it is disabled by default.

memcpy_s() will assert the pointers src and dest are not NULL in debug builds. Passing NULL for either pointer is undefined behavior.

Definition at line 506 of file misc.h.

## ◆ memmove_s()

void memmove_s | ( | void * | dest,
|  | size_t | sizeInBytes,
|  | const void * | src,
|  | size_t | count
| ) |  |
| inline

Bounds checking replacement for memmove()

Parameters

  dest | pointer to the desination memory block
  sizeInBytes | size of the desination memory block, in bytes
  src | pointer to the source memory block
  count | the number of bytes to copy

Exceptions

  InvalidArgument |

ISO/IEC TR-24772 provides bounds checking interfaces for potentially unsafe functions like memcpy(), strcpy() and memmove(). However, not all standard libraries provides them, like Glibc. The library's memmove_s() is a near-drop in replacement. Its only a near-replacement because the library's version throws an InvalidArgument on a bounds violation.

memcpy_s() and memmove_s() are guarded by __STDC_WANT_SECURE_LIB__. If __STDC_WANT_SECURE_LIB__ is not defined or defined to 0, then the library makes memcpy_s() and memmove_s() available. The library will also optionally make the symbols available if `CRYPTOPP_WANT_SECURE_LIB` is defined. `CRYPTOPP_WANT_SECURE_LIB` is in config.h, but it is disabled by default.

memmove_s() will assert the pointers src and dest are not NULL in debug builds. Passing NULL for either pointer is undefined behavior.

Definition at line 552 of file misc.h.

## ◆ vec_swap()

template<class T >

void vec_swap | ( | T & | a,
|  | T & | b
| ) |  |
| inline

Swaps two variables which are arrays.

Template Parameters

  T | class or type

Parameters

  a | the first value
  b | the second value

C++03 does not provide support for `std::swap(__m128i a, __m128i b)` because `__m128i` is an `unsigned long long[2]`. Most compilers support it out of the box, but Sun Studio C++ compilers 12.2 and 12.3 do not.

See also
  How to swap two __m128i variables in C++03 given its an opaque type and an array? on Stack Overflow.

Definition at line 596 of file misc.h.

## ◆ memset_z()

void* memset_z | ( | void * | ptr,
|  | int | val,
|  | size_t | num
| ) |  |
| inline

Memory block initializer.

Parameters

  ptr | pointer to the memory block being written
  val | the integer value to write for each byte
  num | the size of the source memory block, in bytes

Internally the function calls memset with the value `val`. memset_z can be used to initialize a freshly allocated memory block. To zeroize a memory block on destruction use `SecureWipeBuffer`.

Returns
  the pointer to the memory block

See also
  SecureWipeBuffer

Definition at line 618 of file misc.h.

## ◆ STDMIN()

template<class T >

const T& STDMIN | ( | const T & | a,
|  | const T & | b
| ) |  |
| inline

Replacement function for std::min.

Template Parameters

  T | class or type

Parameters

  a | the first value
  b | the second value

Returns
  the minimum value based on a comparison of `b < a` using `operator<`

STDMIN was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0

Definition at line 635 of file misc.h.

## ◆ STDMAX()

template<class T >

const T& STDMAX | ( | const T & | a,
|  | const T & | b
| ) |  |
| inline

Replacement function for std::max.

Template Parameters

  T | class or type

Parameters

  a | the first value
  b | the second value

Returns
  the minimum value based on a comparison of `a < b` using `operator<`

STDMAX was provided because the library could not easily use std::min or std::max in Windows or Cygwin 1.1.0

Definition at line 646 of file misc.h.

## ◆ UnsignedMin()

template<class T1 , class T2 >

const T1 UnsignedMin | ( | const T1 & | a,
|  | const T2 & | b
| ) |  |
| inline

Safe comparison of values that could be neagtive and incorrectly promoted.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  a | the first value
  b | the second value

Returns
  the minimum value based on a comparison a and b using `operator<`.

The comparison `b < a` is performed and the value returned is a's type T1.

Definition at line 674 of file misc.h.

## ◆ SafeConvert()

template<class T1 , class T2 >

bool SafeConvert | ( | T1 | from,
|  | T2 & | to
| ) |  |
| inline

Tests whether a conversion from -> to is safe to perform.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  from | the first value
  to | the second value

Returns
  true if its safe to convert from into to, false otherwise.

Definition at line 690 of file misc.h.

## ◆ IntToString()

template<class T >

std::string IntToString | ( | T | value,
|  | unsigned int | base = `10`
| ) |  |

Converts a value to a string.

Template Parameters

  T | class or type

Parameters

  value | the value to convert
  base | the base to use during the conversion

Returns
  the string representation of value in base.

Definition at line 704 of file misc.h.

## ◆ IntToString< word64 >()

template<>

CRYPTOPP_DLL std::string IntToString< word64 > | ( | word64 | value,
|  | unsigned int | base
| ) |  |

Converts an unsigned value to a string.

Parameters

  value | the value to convert
  base | the base to use during the conversion

Returns
  the string representation of value in base.

this template function specialization was added to suppress Coverity findings on IntToString() with unsigned types.

## ◆ IntToString< Integer >()

template<>

CRYPTOPP_DLL std::string IntToString< Integer > | ( | Integer | value,
|  | unsigned int | base
| ) |  |

Converts an Integer to a string.

Parameters

  value | the Integer to convert
  base | the base to use during the conversion

Returns
  the string representation of value in base.

This is a template specialization of IntToString(). Use it like IntToString():

     // Print integer in base 10
     Integer n...
     std::string s = IntToString(n, 10);

The string is presented with lowercase letters by default. A hack is available to switch to uppercase letters without modifying the function signature.

     // Print integer in base 16, uppercase letters
     Integer n...
     const unsigned int UPPER = (1 << 31);
     std::string s = IntToString(n, (UPPER | 16));

## ◆ Parity()

template<class T >

unsigned int Parity | ( | T | value | ) |

Returns the parity of a value.

Template Parameters

  T | class or type

Parameters

  value | the value to provide the parity

Returns
  1 if the number 1-bits in the value is odd, 0 otherwise

Definition at line 787 of file misc.h.

## ◆ BytePrecision()

template<class T >

unsigned int BytePrecision | ( | const T & | value | ) |

Returns the number of 8-bit bytes or octets required for a value.

Template Parameters

  T | class or type

Parameters

  value | the value to test

Returns
  the minimum number of 8-bit bytes or octets required to represent a value

Definition at line 799 of file misc.h.

## ◆ BitPrecision()

template<class T >

unsigned int BitPrecision | ( | const T & | value | ) |

Returns the number of bits required for a value.

Template Parameters

  T | class or type

Parameters

  value | the value to test

Returns
  the maximum number of bits required to represent a value.

Definition at line 822 of file misc.h.

## ◆ TrailingZeros() [1/2]

unsigned int TrailingZeros | ( | word32 | v | ) |
| inline

Determines the number of trailing 0-bits in a value.

Parameters

  v | the 32-bit value to test

Returns
  the number of trailing 0-bits in v, starting at the least significant bit position

TrailingZeros returns the number of trailing 0-bits in v, starting at the least significant bit position. The return value is undefined if there are no 1-bits set in the value v.

Note
  The function does not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position.

Definition at line 847 of file misc.h.

## ◆ TrailingZeros() [2/2]

unsigned int TrailingZeros | ( | word64 | v | ) |
| inline

Determines the number of trailing 0-bits in a value.

Parameters

  v | the 64-bit value to test

Returns
  the number of trailing 0-bits in v, starting at the least significant bit position

TrailingZeros returns the number of trailing 0-bits in v, starting at the least significant bit position. The return value is undefined if there are no 1-bits set in the value v.

Note
  The function does not return 0 if no 1-bits are set because 0 collides with a 1-bit at the 0-th position.

Definition at line 878 of file misc.h.

## ◆ Crop()

template<class T >

T Crop | ( | T | value,
|  | size_t | bits
| ) |  |
| inline

Truncates the value to the specified number of bits.

Template Parameters

  T | class or type

Parameters

  value | the value to truncate or mask
  bits | the number of bits to truncate or mask

Returns
  the value truncated to the specified number of bits, starting at the least significant bit position

This function masks the low-order bits of value and returns the result. The mask is created with `(1 << bits) - 1`.

Definition at line 906 of file misc.h.

## ◆ BitsToBytes()

size_t BitsToBytes | ( | size_t | bitCount | ) |
| inline

Returns the number of 8-bit bytes or octets required for the specified number of bits.

Parameters

  bitCount | the number of bits

Returns
  the minimum number of 8-bit bytes or octets required by bitCount

BitsToBytes is effectively a ceiling function based on 8-bit bytes.

Definition at line 918 of file misc.h.

## ◆ BytesToWords()

size_t BytesToWords | ( | size_t | byteCount | ) |
| inline

Returns the number of words required for the specified number of bytes.

Parameters

  byteCount | the number of bytes

Returns
  the minimum number of words required by byteCount

BytesToWords is effectively a ceiling function based on `WORD_SIZE`. `WORD_SIZE` is defined in config.h

Definition at line 928 of file misc.h.

## ◆ BitsToWords()

size_t BitsToWords | ( | size_t | bitCount | ) |
| inline

Returns the number of words required for the specified number of bits.

Parameters

  bitCount | the number of bits

Returns
  the minimum number of words required by bitCount

BitsToWords is effectively a ceiling function based on `WORD_BITS`. `WORD_BITS` is defined in config.h

Definition at line 938 of file misc.h.

## ◆ BitsToDwords()

size_t BitsToDwords | ( | size_t | bitCount | ) |
| inline

Returns the number of double words required for the specified number of bits.

Parameters

  bitCount | the number of bits

Returns
  the minimum number of double words required by bitCount

BitsToDwords is effectively a ceiling function based on `2*WORD_BITS`. `WORD_BITS` is defined in config.h

Definition at line 948 of file misc.h.

## ◆ xorbuf() [1/2]

CRYPTOPP_DLL void xorbuf | ( | byte * | buf,
|  | const byte * | mask,
|  | size_t | count
| ) |  |

Performs an XOR of a buffer with a mask.

Parameters

  buf | the buffer to XOR with the mask
  mask | the mask to XOR with the buffer
  count | the size of the buffers, in bytes

The function effectively visits each element in the buffers and performs `buf[i] ^= mask[i]`. buf and mask must be of equal size.

## ◆ xorbuf() [2/2]

CRYPTOPP_DLL void xorbuf | ( | byte * | output,
|  | const byte * | input,
|  | const byte * | mask,
|  | size_t | count
| ) |  |

Performs an XOR of an input buffer with a mask and stores the result in an output buffer.

Parameters

  output | the destination buffer
  input | the source buffer to XOR with the mask
  mask | the mask buffer to XOR with the input buffer
  count | the size of the buffers, in bytes

The function effectively visits each element in the buffers and performs `output[i] = input[i] ^ mask[i]`. output, input and mask must be of equal size.

## ◆ VerifyBufsEqual()

CRYPTOPP_DLL bool VerifyBufsEqual | ( | const byte * | buf1,
|  | const byte * | buf2,
|  | size_t | count
| ) |  |

Performs a near constant-time comparison of two equally sized buffers.

Parameters

  buf1 | the first buffer
  buf2 | the second buffer
  count | the size of the buffers, in bytes

VerifyBufsEqual performs an XOR of the elements in two equally sized buffers and retruns a result based on the XOR operation. A count of 0 returns true because two empty buffers are considered equal.

The function is near constant-time because CPU micro-code timings could affect the "constant-ness". Calling code is responsible for mitigating timing attacks if the buffers are not equally sized.

See also
  ModPowerOf2

## ◆ IsPowerOf2()

template<class T >

bool IsPowerOf2 | ( | const T & | value | ) |
| inline

Tests whether a value is a power of 2.

Parameters

  value | the value to test

Returns
  true if value is a power of 2, false otherwise

The function creates a mask of `value - 1` and returns the result of an AND operation compared to 0. If value is 0 or less than 0, then the function returns false.

Definition at line 990 of file misc.h.

## ◆ NumericLimitsMin()

template<class T >

T NumericLimitsMin | ( |  | ) |
| inline

Provide the minimum value for a type.

Template Parameters

  T | type of class

Returns
  the minimum value of the type or class

NumericLimitsMin() was introduced for Clang at Issue 364, Apple Clang 6.0 and numeric_limits<word128>::max() returns 0.

NumericLimitsMin() requires a specialization for `T`, meaning `std::numeric_limits<T>::is_specialized` must return `true`. In the case of `word128` Clang did not specialize `numeric_limits` for the type.

Since
  Crypto++ 8.1

Definition at line 1023 of file misc.h.

## ◆ NumericLimitsMax()

template<class T >

T NumericLimitsMax | ( |  | ) |
| inline

Provide the maximum value for a type.

Template Parameters

  T | type of class

Returns
  the maximum value of the type or class

NumericLimitsMax() was introduced for Clang at Issue 364, Apple Clang 6.0 and numeric_limits<word128>::max() returns 0.

NumericLimitsMax() requires a specialization for `T`, meaning `std::numeric_limits<T>::is_specialized` must return `true`. In the case of `word128` Clang did not specialize `numeric_limits` for the type.

Since
  Crypto++ 8.1

Definition at line 1041 of file misc.h.

## ◆ SaturatingSubtract()

template<class T1 , class T2 >

T1 SaturatingSubtract | ( | const T1 & | a,
|  | const T2 & | b
| ) |  |
| inline

Performs a saturating subtract clamped at 0.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  a | the minuend
  b | the subtrahend

Returns
  the difference produced by the saturating subtract

Saturating arithmetic restricts results to a fixed range. Results that are less than 0 are clamped at 0.

Use of saturating arithmetic in places can be advantageous because it can avoid a branch by using an instruction like a conditional move (`CMOVE`).

Definition at line 1073 of file misc.h.

## ◆ SaturatingSubtract1()

template<class T1 , class T2 >

T1 SaturatingSubtract1 | ( | const T1 & | a,
|  | const T2 & | b
| ) |  |
| inline

Performs a saturating subtract clamped at 1.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  a | the minuend
  b | the subtrahend

Returns
  the difference produced by the saturating subtract

Saturating arithmetic restricts results to a fixed range. Results that are less than 1 are clamped at 1.

Use of saturating arithmetic in places can be advantageous because it can avoid a branch by using an instruction like a conditional move (`CMOVE`).

Definition at line 1090 of file misc.h.

## ◆ ModPowerOf2()

template<class T1 , class T2 >

T2 ModPowerOf2 | ( | const T1 & | a,
|  | const T2 & | b
| ) |  |
| inline

Reduces a value to a power of 2.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  a | the first value
  b | the second value

Returns
  ModPowerOf2() returns `a & (b-1)`. `b` must be a power of 2. Use IsPowerOf2() to determine if `b` is a suitable candidate.

See also
  IsPowerOf2

Definition at line 1105 of file misc.h.

## ◆ RoundDownToMultipleOf()

template<class T1 , class T2 >

T1 RoundDownToMultipleOf | ( | const T1 & | n,
|  | const T2 & | m
| ) |  |
| inline

Rounds a value down to a multiple of a second value.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  n | the value to reduce
  m | the value to reduce `n` to a multiple

Returns
  the possibly unmodified value

RoundDownToMultipleOf is effectively a floor function based on m. The function returns the value `n - n%m`. If n is a multiple of m, then the original value is returned.

Note
  `T1` and `T2` should be usigned arithmetic types. If `T1` or `T2` is signed, then the value should be non-negative. The library asserts in debug builds when practical, but allows you to perform the operation in release builds.

Definition at line 1124 of file misc.h.

## ◆ RoundUpToMultipleOf()

template<class T1 , class T2 >

T1 RoundUpToMultipleOf | ( | const T1 & | n,
|  | const T2 & | m
| ) |  |
| inline

Rounds a value up to a multiple of a second value.

Template Parameters

  T1 | class or type
  T2 | class or type

Parameters

  n | the value to reduce
  m | the value to reduce `n` to a multiple

Returns
  the possibly unmodified value

RoundUpToMultipleOf is effectively a ceiling function based on m. The function returns the value `n + n%m`. If n is a multiple of m, then the original value is returned. If the value n would overflow, then an InvalidArgument exception is thrown.

Note
  `T1` and `T2` should be usigned arithmetic types. If `T1` or `T2` is signed, then the value should be non-negative. The library asserts in debug builds when practical, but allows you to perform the operation in release builds.

Definition at line 1154 of file misc.h.

## ◆ GetAlignmentOf()

template<class T >

unsigned int GetAlignmentOf | ( |  | ) |
| inline

Returns the minimum alignment requirements of a type.

Template Parameters

  T | class or type

Returns
  the minimum alignment requirements of `T`, in bytes

Internally the function calls C++11's `alignof` if available. If not available, then the function uses compiler specific extensions such as `__alignof` and `_alignof_`. If an extension is not available, then the function uses `sizeof(T)`.

Definition at line 1179 of file misc.h.

## ◆ IsAlignedOn()

bool IsAlignedOn | ( | const void * | ptr,
|  | unsigned int | alignment
| ) |  |
| inline

Determines whether ptr is aligned to a minimum value.

Parameters

  ptr | the pointer being checked for alignment
  alignment | the alignment value to test the pointer against

Returns
  true if `ptr` is aligned on at least `alignment` boundary, false otherwise

Internally the function tests whether alignment is 1. If so, the function returns true. If not, then the function effectively performs a modular reduction and returns true if the residue is 0.

Definition at line 1206 of file misc.h.

## ◆ IsAligned()

template<class T >

bool IsAligned | ( | const void * | ptr | ) |
| inline

Determines whether ptr is minimally aligned.

Template Parameters

  T | class or type

Parameters

  ptr | the pointer to check for alignment

Returns
  true if `ptr` is aligned to at least `T` boundary, false otherwise

Internally the function calls IsAlignedOn with a second parameter of GetAlignmentOf<T>.

Definition at line 1220 of file misc.h.

## ◆ GetNativeByteOrder()

ByteOrder GetNativeByteOrder | ( |  | ) |
| inline

Returns NativeByteOrder as an enumerated ByteOrder value.

Returns
  LittleEndian if the native byte order is little-endian, and BigEndian if the native byte order is big-endian

NativeByteOrder is a typedef depending on the platform. If CRYPTOPP_LITTLE_ENDIAN is set in config.h, then GetNativeByteOrder returns LittleEndian. If CRYPTOPP_BIG_ENDIAN is set, then GetNativeByteOrder returns BigEndian.

Note
  There are other byte orders besides little- and big-endian, and they include bi-endian and PDP-endian. If a system is neither little-endian nor big-endian, then a compile time error occurs.

Definition at line 1243 of file misc.h.

## ◆ NativeByteOrderIs()

bool NativeByteOrderIs | ( | ByteOrder | order | ) |
| inline

Determines whether order follows native byte ordering.

Parameters

  order | the ordering being tested against native byte ordering

Returns
  true if order follows native byte ordering, false otherwise

Definition at line 1251 of file misc.h.

## ◆ GetCipherDir()

template<class T >

CipherDir GetCipherDir | ( | const T & | obj | ) |
| inline

Returns the direction the cipher is being operated.

Template Parameters

  T | class or type

Parameters

  obj | the cipher object being queried

Returns
  ENCRYPTION if the cipher obj is being operated in its forward direction, DECRYPTION otherwise

A cipher can be operated in a "forward" direction (encryption) or a "reverse" direction (decryption). The operations do not have to be symmetric, meaning a second application of the transformation does not necessariy return the original message. That is, `E(D(m))` may not equal `E(E(m))`; and `D(E(m))` may not equal `D(D(m))`.

Definition at line 1267 of file misc.h.

## ◆ IncrementCounterByOne() [1/2]

void IncrementCounterByOne | ( | byte * | inout,
|  | unsigned int | size
| ) |  |
| inline

Performs an addition with carry on a block of bytes.

Parameters

  inout | the byte block
  size | the size of the block, in bytes

Performs an addition with carry by adding 1 on a block of bytes starting at the least significant byte. Once carry is 0, the function terminates and returns to the caller.

Note
  The function is not constant time because it stops processing when the carry is 0.

Definition at line 1278 of file misc.h.

## ◆ IncrementCounterByOne() [2/2]

void IncrementCounterByOne | ( | byte * | output,
|  | const byte * | input,
|  | unsigned int | size
| ) |  |
| inline

Performs an addition with carry on a block of bytes.

Parameters

  output | the destination block of bytes
  input | the source block of bytes
  size | the size of the block

Performs an addition with carry on a block of bytes starting at the least significant byte. Once carry is 0, the remaining bytes from input are copied to output using memcpy.

The function is close to near-constant time because it operates on all the bytes in the blocks.

Definition at line 1298 of file misc.h.

## ◆ ConditionalSwap()

template<class T >

void ConditionalSwap | ( | bool | c,
|  | T & | a,
|  | T & | b
| ) |  |
| inline

Performs a branchless swap of values a and b if condition c is true.

Template Parameters

  T | class or type

Parameters

  c | the condition to perform the swap
  a | the first value
  b | the second value

Definition at line 1324 of file misc.h.

## ◆ ConditionalSwapPointers()

template<class T >

void ConditionalSwapPointers | ( | bool | c,
|  | T & | a,
|  | T & | b
| ) |  |
| inline

Performs a branchless swap of pointers a and b if condition c is true.

Template Parameters

  T | class or type

Parameters

  c | the condition to perform the swap
  a | the first pointer
  b | the second pointer

Definition at line 1337 of file misc.h.

## ◆ SecureWipeBuffer() [1/5]

template<class T >

void SecureWipeBuffer | ( | T * | buf,
|  | size_t | n
| ) |  |

Sets each element of an array to 0.

Template Parameters

  T | class or type

Parameters

  buf | an array of elements
  n | the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1354 of file misc.h.

## ◆ SecureWipeBuffer() [2/5]

template<>

void SecureWipeBuffer | ( | byte * | buf,
|  | size_t | n
| ) |  |
| inline

Sets each byte of an array to 0.

Parameters

  buf | an array of bytes
  n | the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1372 of file misc.h.

## ◆ SecureWipeBuffer() [3/5]

template<>

void SecureWipeBuffer | ( | word16 * | buf,
|  | size_t | n
| ) |  |
| inline

Sets each 16-bit element of an array to 0.

Parameters

  buf | an array of 16-bit words
  n | the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1387 of file misc.h.

## ◆ SecureWipeBuffer() [4/5]

template<>

void SecureWipeBuffer | ( | word32 * | buf,
|  | size_t | n
| ) |  |
| inline

Sets each 32-bit element of an array to 0.

Parameters

  buf | an array of 32-bit words
  n | the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1402 of file misc.h.

## ◆ SecureWipeBuffer() [5/5]

template<>

void SecureWipeBuffer | ( | word64 * | buf,
|  | size_t | n
| ) |  |
| inline

Sets each 64-bit element of an array to 0.

Parameters

  buf | an array of 64-bit words
  n | the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1417 of file misc.h.

## ◆ SecureWipeArray()

template<class T >

void SecureWipeArray | ( | T * | buf,
|  | size_t | n
| ) |  |
| inline

Sets each element of an array to 0.

Template Parameters

  T | class or type

Parameters

  buf | an array of elements
  n | the number of elements in the array

The operation performs a wipe or zeroization. The function attempts to survive optimizations and dead code removal.

Definition at line 1470 of file misc.h.

## ◆ StringNarrow()

std::string StringNarrow | ( | const wchar_t * | str,
|  | bool | throwOnError = `true`
| ) |  |

Converts a wide character C-string to a multibyte string.

Parameters

  str | C-string consisting of wide characters
  throwOnError | flag indicating the function should throw on error

Returns
  str converted to a multibyte string or an empty string.

StringNarrow() converts a wide string to a narrow string using C++ std::wcstombs() under the executing thread's locale. A locale must be set before using this function, and it can be set with std::setlocale() if needed. Upon success, the converted string is returned.

Upon failure with throwOnError as false, the function returns an empty string. If throwOnError as true, the function throws an InvalidArgument() exception.

Note
  If you try to convert, say, the Chinese character for "bone" from UTF-16 (0x9AA8) to UTF-8 (0xE9 0xAA 0xA8), then you must ensure the locale is available. If the locale is not available, then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception.

## ◆ StringWiden()

std::wstring StringWiden | ( | const char * | str,
|  | bool | throwOnError = `true`
| ) |  |

Converts a multibyte C-string to a wide character string.

Parameters

  str | C-string consisting of wide characters
  throwOnError | flag indicating the function should throw on error

Returns
  str converted to a multibyte string or an empty string.

StringWiden() converts a narrow string to a wide string using C++ std::mbstowcs() under the executing thread's locale. A locale must be set before using this function, and it can be set with std::setlocale() if needed. Upon success, the converted string is returned.

Upon failure with throwOnError as false, the function returns an empty string. If throwOnError as true, the function throws an InvalidArgument() exception.

Note
  If you try to convert, say, the Chinese character for "bone" from UTF-8 (0xE9 0xAA 0xA8) to UTF-16 (0x9AA8), then you must ensure the locale is available. If the locale is not available, then a 0x21 error is returned on Windows which eventually results in an InvalidArgument() exception.

## ◆ rotlConstant()

template<unsigned int R, class T >

T rotlConstant | ( | T | x | ) |
| inline

Performs a left rotate.

Template Parameters

  R | the number of bit positions to rotate the value
  T | the word type

Parameters

  x | the value to rotate

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

R must be in the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior. Use rotlMod if the rotate amount R is outside the range.

Use rotlConstant when the rotate amount is constant. The template function was added because Clang did not propagate the constant when passed as a function parameter. Clang's need for a constexpr meant rotlFixed failed to compile on occasion.

Note
  rotlConstant attempts to enlist a `rotate IMM` instruction because its often faster than a `rotate REG`. Immediate rotates can be up to three times faster than their register counterparts.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 6.0

Definition at line 1527 of file misc.h.

## ◆ rotrConstant()

template<unsigned int R, class T >

T rotrConstant | ( | T | x | ) |
| inline

Performs a right rotate.

Template Parameters

  R | the number of bit positions to rotate the value
  T | the word type

Parameters

  x | the value to rotate

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

R must be in the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior. Use rotrMod if the rotate amount R is outside the range.

Use rotrConstant when the rotate amount is constant. The template function was added because Clang did not propagate the constant when passed as a function parameter. Clang's need for a constexpr meant rotrFixed failed to compile on occasion.

Note
  rotrConstant attempts to enlist a `rotate IMM` instruction because its often faster than a `rotate REG`. Immediate rotates can be up to three times faster than their register counterparts.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Definition at line 1553 of file misc.h.

## ◆ rotlFixed()

template<class T >

T rotlFixed | ( | T | x,
|  | unsigned int | y
| ) |  |
| inline

Performs a left rotate.

Template Parameters

  T | the word type

Parameters

  x | the value to rotate
  y | the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior. Use rotlMod if the rotate amount y is outside the range.

Note
  rotlFixed attempts to enlist a `rotate IMM` instruction because its often faster than a `rotate REG`. Immediate rotates can be up to three times faster than their register counterparts. New code should use `rotlConstant`, which accepts the rotate amount as a template parameter.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 6.0

Definition at line 1578 of file misc.h.

## ◆ rotrFixed()

template<class T >

T rotrFixed | ( | T | x,
|  | unsigned int | y
| ) |  |
| inline

Performs a right rotate.

Template Parameters

  T | the word type

Parameters

  x | the value to rotate
  y | the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior. Use rotrMod if the rotate amount y is outside the range.

Note
  rotrFixed attempts to enlist a `rotate IMM` instruction because its often faster than a `rotate REG`. Immediate rotates can be up to three times faster than their register counterparts. New code should use `rotrConstant`, which accepts the rotate amount as a template parameter.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 3.0

Definition at line 1603 of file misc.h.

## ◆ rotlVariable()

template<class T >

T rotlVariable | ( | T | x,
|  | unsigned int | y
| ) |  |
| inline

Performs a left rotate.

Template Parameters

  T | the word type

Parameters

  x | the value to rotate
  y | the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior. Use rotlMod if the rotate amount y is outside the range.

Note
  rotlVariable attempts to enlist a `rotate IMM` instruction because its often faster than a `rotate REG`. Immediate rotates can be up to three times faster than their register counterparts.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 3.0

Definition at line 1627 of file misc.h.

## ◆ rotrVariable()

template<class T >

T rotrVariable | ( | T | x,
|  | unsigned int | y
| ) |  |
| inline

Performs a right rotate.

Template Parameters

  T | the word type

Parameters

  x | the value to rotate
  y | the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y must be in the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior. Use rotrMod if the rotate amount y is outside the range.

Note
  rotrVariable attempts to enlist a `rotate IMM` instruction because its often faster than a `rotate REG`. Immediate rotates can be up to three times faster than their register counterparts.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 3.0

Definition at line 1647 of file misc.h.

## ◆ rotlMod()

template<class T >

T rotlMod | ( | T | x,
|  | unsigned int | y
| ) |  |
| inline

Performs a left rotate.

Template Parameters

  T | the word type

Parameters

  x | the value to rotate
  y | the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y is reduced to the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior.

Note
  rotrVariable will use either `rotate IMM` or `rotate REG`.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 3.0

Definition at line 1664 of file misc.h.

## ◆ rotrMod()

template<class T >

T rotrMod | ( | T | x,
|  | unsigned int | y
| ) |  |
| inline

Performs a right rotate.

Template Parameters

  T | the word type

Parameters

  x | the value to rotate
  y | the number of bit positions to rotate the value

This is a portable C/C++ implementation. The value x to be rotated can be 8 to 64-bits wide.

y is reduced to the range `[0, sizeof(T)*8 - 1]` to avoid undefined behavior.

Note
  rotrVariable will use either `rotate IMM` or `rotate REG`.

See also
  rotlConstant, rotrConstant, rotlFixed, rotrFixed, rotlVariable, rotrVariable

Since
  Crypto++ 3.0

Definition at line 1680 of file misc.h.

## ◆ GetByte()

template<class T >

unsigned int GetByte | ( | ByteOrder | order,
|  | T | value,
|  | unsigned int | index
| ) |  |
| inline

Gets a byte from a value.

Parameters

  order | the ByteOrder of the value
  value | the value to retrieve the byte
  index | the location of the byte to retrieve

Definition at line 1989 of file misc.h.

## ◆ ByteReverse() [1/5]

byte ByteReverse | ( | byte | value | ) |
| inline

Reverses bytes in a 8-bit value.

Parameters

  value | the 8-bit value to reverse

Note
  ByteReverse returns the value passed to it since there is nothing to reverse.

Definition at line 2001 of file misc.h.

## ◆ ByteReverse() [2/5]

word16 ByteReverse | ( | word16 | value | ) |
| inline

Reverses bytes in a 16-bit value.

Parameters

  value | the 16-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function performs a 8-bit rotate on the word16.

Definition at line 2010 of file misc.h.

## ◆ ByteReverse() [3/5]

word32 ByteReverse | ( | word32 | value | ) |
| inline

Reverses bytes in a 32-bit value.

Parameters

  value | the 32-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word32.

Definition at line 2025 of file misc.h.

## ◆ ByteReverse() [4/5]

word64 ByteReverse | ( | word64 | value | ) |
| inline

Reverses bytes in a 64-bit value.

Parameters

  value | the 64-bit value to reverse

ByteReverse calls bswap if available. Otherwise the function uses a combination of rotates on the word64.

Definition at line 2054 of file misc.h.

## ◆ BitReverse() [1/5]

byte BitReverse | ( | byte | value | ) |
| inline

Reverses bits in a 8-bit value.

Parameters

  value | the 8-bit value to reverse

BitReverse performs a combination of shifts on the byte.

Definition at line 2075 of file misc.h.

## ◆ BitReverse() [2/5]

word16 BitReverse | ( | word16 | value | ) |
| inline

Reverses bits in a 16-bit value.

Parameters

  value | the 16-bit value to reverse

BitReverse performs a combination of shifts on the word16.

Definition at line 2085 of file misc.h.

## ◆ BitReverse() [3/5]

word32 BitReverse | ( | word32 | value | ) |
| inline

Reverses bits in a 32-bit value.

Parameters

  value | the 32-bit value to reverse

BitReverse performs a combination of shifts on the word32.

Definition at line 2104 of file misc.h.

## ◆ BitReverse() [4/5]

word64 BitReverse | ( | word64 | value | ) |
| inline

Reverses bits in a 64-bit value.

Parameters

  value | the 64-bit value to reverse

BitReverse performs a combination of shifts on the word64.

Definition at line 2123 of file misc.h.

## ◆ BitReverse() [5/5]

template<class T >

T BitReverse | ( | T | value | ) |
| inline

Reverses bits in a value.

Parameters

  value | the value to reverse

The template overload of BitReverse operates on signed and unsigned values. Internally the size of T is checked, and then value is cast to a byte, word16, word32 or word64. After the cast, the appropriate BitReverse overload is called.

Definition at line 2142 of file misc.h.

## ◆ ConditionalByteReverse() [1/2]

template<class T >

T ConditionalByteReverse | ( | ByteOrder | order,
|  | T | value
| ) |  |
| inline

Reverses bytes in a value depending upon endianness.

Template Parameters

  T | the class or type

Parameters

  order | the ByteOrder of the data
  value | the value to conditionally reverse

Internally, the ConditionalByteReverse calls NativeByteOrderIs. If order matches native byte order, then the original value is returned. If not, then ByteReverse is called on the value before returning to the caller.

Definition at line 2167 of file misc.h.

## ◆ ByteReverse() [5/5]

template<class T >

void ByteReverse | ( | T * | out,
|  | const T * | in,
|  | size_t | byteCount
| ) |  |

Reverses bytes in an element from an array of elements.

Template Parameters

  T | the class or type

Parameters

  out | the output array of elements
  in | the input array of elements
  byteCount | the total number of bytes in the array

Internally, ByteReverse visits each element in the in array calls ByteReverse on it, and writes the result to out.

ByteReverse does not process tail byes, or bytes that are not part of a full element. If T is int (and int is 4 bytes), then `byteCount = 10` means only the first 2 elements or 8 bytes are reversed.

The following program should help illustrate the behavior.

    vector<word32> v1, v2;

    v1.push_back(1);
    v1.push_back(2);
    v1.push_back(3);
    v1.push_back(4);

    v2.resize(v1.size());
    ByteReverse<word32>(&v2[0], &v1[0], 16);

    cout << "V1: ";
    for(unsigned int i = 0; i < v1.size(); i++)
     cout << std::hex << v1[i] << " ";
    cout << endl;

    cout << "V2: ";
    for(unsigned int i = 0; i < v2.size(); i++)
     cout << std::hex << v2[i] << " ";
    cout << endl;

The program above results in the following output.

    V1: 00000001 00000002 00000003 00000004
    V2: 01000000 02000000 03000000 04000000

See also
  ConditionalByteReverse

Definition at line 2208 of file misc.h.

## ◆ ConditionalByteReverse() [2/2]

template<class T >

void ConditionalByteReverse | ( | ByteOrder | order,
|  | T * | out,
|  | const T * | in,
|  | size_t | byteCount
| ) |  |
| inline

Conditionally reverses bytes in an element from an array of elements.

Template Parameters

  T | the class or type

Parameters

  order | the ByteOrder of the data
  out | the output array of elements
  in | the input array of elements
  byteCount | the byte count of the arrays

Internally, ByteReverse visits each element in the in array calls ByteReverse on it depending on the desired endianness, and writes the result to out.

ByteReverse does not process tail byes, or bytes that are not part of a full element. If T is int (and int is 4 bytes), then `byteCount = 10` means only the first 2 elements or 8 bytes are reversed.

See also
  ByteReverse

Definition at line 2234 of file misc.h.

## ◆ GetWord() [1/2]

template<class T >

T GetWord | ( | bool | assumeAligned,
|  | ByteOrder | order,
|  | const byte * | block
| ) |  |
| inline

Access a block of memory.

Template Parameters

  T | class or type

Parameters

  assumeAligned | flag indicating alignment
  order | the ByteOrder of the data
  block | the byte buffer to be processed

Returns
  the word in the specified byte order

GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER.

An example of reading two word32 values from a block of memory is shown below. `w` will be `0x03020100`.

      word32 w;
      byte buffer[4] = {0,1,2,3};
      w = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, buffer);

Definition at line 2440 of file misc.h.

## ◆ GetWord() [2/2]

template<class T >

void GetWord | ( | bool | assumeAligned,
|  | ByteOrder | order,
|  | T & | result,
|  | const byte * | block
| ) |  |
| inline

Access a block of memory.

Template Parameters

  T | class or type

Parameters

  assumeAligned | flag indicating alignment
  order | the ByteOrder of the data
  result | the word in the specified byte order
  block | the byte buffer to be processed

GetWord() provides alternate read access to a block of memory. The flag assumeAligned indicates if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER.

An example of reading two word32 values from a block of memory is shown below. `w` will be `0x03020100`.

      word32 w;
      byte buffer[4] = {0,1,2,3};
      w = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, buffer);

Definition at line 2466 of file misc.h.

## ◆ PutWord()

template<class T >

void PutWord | ( | bool | assumeAligned,
|  | ByteOrder | order,
|  | byte * | block,
|  | T | value,
|  | const byte * | xorBlock = `NULL`
| ) |  |
| inline

Access a block of memory.

Template Parameters

  T | class or type

Parameters

  assumeAligned | flag indicating alignment
  order | the ByteOrder of the data
  block | the destination byte buffer
  value | the word in the specified byte order
  xorBlock | an optional byte buffer to xor

PutWord() provides alternate write access to a block of memory. The flag assumeAligned indicates if the memory block is aligned for class or type T. The enumeration ByteOrder is BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER.

Definition at line 2482 of file misc.h.

## ◆ WordToString()

template<class T >

std::string WordToString | ( | T | value,
|  | ByteOrder | order = `BIG_ENDIAN_ORDER`
| ) |  |

Convert a word to a string.

Template Parameters

  T | class or type

Parameters

  value | the word to convert
  order | byte order

Returns
  a string representing the value of the word

Definition at line 2599 of file misc.h.

## ◆ StringToWord()

template<class T >

T StringToWord | ( | const std::string & | str,
|  | ByteOrder | order = `BIG_ENDIAN_ORDER`
| ) |  |

Convert a string to a word.

Template Parameters

  T | class or type

Parameters

  str | the string to convert
  order | byte order

Returns
  a word representing the value of the string

Definition at line 2613 of file misc.h.

## ◆ SafeRightShift()

template<unsigned int bits, class T >

T SafeRightShift | ( | T | value | ) |
| inline

Safely right shift values when undefined behavior could occur.

Template Parameters

  bits | the number of bit positions to shift the value
  T | class or type

Parameters

  value | the value to right shift

Returns
  the shifted value or 0

SafeRightShift safely shifts the value to the right when undefined behavior could occur under C/C++ rules. SafeRightShift will return the shifted value or 0 if undefined behavior would occur.

Definition at line 2697 of file misc.h.

## ◆ SafeLeftShift()

template<unsigned int bits, class T >

T SafeLeftShift | ( | T | value | ) |
| inline

Safely left shift values when undefined behavior could occur.

Template Parameters

  bits | the number of bit positions to shift the value
  T | class or type

Parameters

  value | the value to left shift

Returns
  the shifted value or 0

SafeLeftShift safely shifts the value to the left when undefined behavior could occur under C/C++ rules. SafeLeftShift will return the shifted value or 0 if undefined behavior would occur.

Definition at line 2711 of file misc.h.

## ◆ FindIfNot()

template<typename InputIt , typename T >

InputIt FindIfNot | ( | InputIt | first,
|  | InputIt | last,
|  | const T & | value
| ) |  |
| inline

Finds first element not in a range.

Template Parameters

  InputIt | Input iterator type
  T | class or type

Parameters

  first | iterator to first element
  last | iterator to last element
  value | the value used as a predicate

Returns
  iterator to the first element in the range that is not value

Definition at line 2724 of file misc.h.