Crypto++  7.0
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...
 
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 value, size_t num)
 Memory block initializer and eraser that attempts to survive optimizations. 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<>
std::string IntToString< word64 > (word64 value, unsigned int base)
 Converts an unsigned value to a string. More...
 
template<>
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 >
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...
 
void xorbuf (byte *buf, const byte *mask, size_t count)
 Performs an XOR of a buffer with a mask. More...
 
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...
 
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 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 CallNewHandler ()
 Attempts to reclaim unused memory. 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<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...
 
void * AlignedAllocate (size_t size)
 Allocates a buffer on 16-byte boundary. More...
 
void AlignedDeallocate (void *ptr)
 Frees a buffer allocated with AlignedAllocate. More...
 
void * UnalignedAllocate (size_t size)
 Allocates a buffer. More...
 
void UnalignedDeallocate (void *ptr)
 Frees a buffer allocated with UnalignedAllocate. More...
 
template<unsigned int R, class T >
rotlConstant (T x)
 Performs a left rotate. More...
 
template<unsigned int R, class T >
rotrConstant (T x)
 Performs a right rotate. More...
 
template<class T >
rotlFixed (T x, unsigned int y)
 Performs a left rotate. More...
 
template<class T >
rotrFixed (T x, unsigned int y)
 Performs a right rotate. More...
 
template<class T >
rotlVariable (T x, unsigned int y)
 Performs a left rotate. More...
 
template<class T >
rotrVariable (T x, unsigned int y)
 Performs a right rotate. More...
 
template<class T >
rotlMod (T x, unsigned int y)
 Performs a left rotate. More...
 
template<class 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 >
BitReverse (T value)
 Reverses bits in a value. More...
 
template<class 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 >
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 >
StringToWord (const std::string &str, ByteOrder order=BIG_ENDIAN_ORDER)
 Convert a string to a word. More...
 
template<unsigned int bits, class T >
SafeRightShift (T value)
 Safely right shift values when undefined behavior could occur. More...
 
template<unsigned int bits, class 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 machines, and 0xffffffffffffffff on 64-bit machines. Internally, SIZE_MAX is defined as __SIZE_MAX__ if __SIZE_MAX__ is defined. If not defined, then SIZE_T_MAX is tried. If neither __SIZE_MAX__ nor SIZE_T_MAX is is defined, the library uses std::numeric_limits<size_t>::max(). The library prefers __SIZE_MAX__ because its a constexpr that is optimized well by all compilers. std::numeric_limits<size_t>::max() is not a constexpr, and it is not always optimized well.

Definition at line 85 of file misc.h.

◆ CRYPTOPP_COMPILE_ASSERT

#define CRYPTOPP_COMPILE_ASSERT (   expr)    { ... }

Compile time assertion.

Parameters
exprthe expression to evaluate

Asserts the expression expr though a dummy struct.

Definition at line 144 of file misc.h.

◆ COUNTOF

#define COUNTOF (   arr)

Counts elements in an array.

Parameters
arran 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 181 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 255 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
PTRa pointer type
OFFa size type
Parameters
pointera pointer
offseta offset into the pointer

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

Definition at line 371 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
PTRa pointer type
OFFa size type
Parameters
pointera pointer
offseta offset into the pointer

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

Definition at line 384 of file misc.h.

◆ PtrDiff()

template<typename PTR >
ptrdiff_t PtrDiff ( const PTR  pointer1,
const PTR  pointer2 
)
inline

Determine pointer difference.

Template Parameters
PTRa pointer type
Parameters
pointer1the first pointer
pointer2the 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 399 of file misc.h.

◆ PtrByteDiff()

template<typename PTR >
size_t PtrByteDiff ( const PTR  pointer1,
const PTR  pointer2 
)
inline

Determine pointer difference.

Template Parameters
PTRa pointer type
Parameters
pointer1the first pointer
pointer2the 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 414 of file misc.h.

◆ memcpy_s()

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

Bounds checking replacement for memcpy()

Parameters
destpointer to the desination memory block
sizeInBytessize of the desination memory block, in bytes
srcpointer to the source memory block
countthe 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 439 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
destpointer to the desination memory block
sizeInBytessize of the desination memory block, in bytes
srcpointer to the source memory block
countthe 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 484 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
Tclass or type
Parameters
athe first value
bthe 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 527 of file misc.h.

◆ memset_z()

void* memset_z ( void *  ptr,
int  value,
size_t  num 
)
inline

Memory block initializer and eraser that attempts to survive optimizations.

Parameters
ptrpointer to the memory block being written
valuethe integer value to write for each byte
numthe size of the source memory block, in bytes

Internally the function calls memset with the value value, and receives the return value from memset as a volatile pointer.

Definition at line 546 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
Tclass or type
Parameters
athe first value
bthe 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 563 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
Tclass or type
Parameters
athe first value
bthe 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 574 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
T1class or type
T2class or type
Parameters
athe first value
bthe 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 602 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
T1class or type
T2class or type
Parameters
fromthe first value
tothe second value
Returns
true if its safe to convert from into to, false otherwise.

Definition at line 618 of file misc.h.

◆ IntToString()

template<class T >
std::string IntToString ( value,
unsigned int  base = 10 
)

Converts a value to a string.

Template Parameters
Tclass or type
Parameters
valuethe value to convert
basethe base to use during the conversion
Returns
the string representation of value in base.

Definition at line 632 of file misc.h.

◆ IntToString< word64 >()

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

Converts an unsigned value to a string.

Parameters
valuethe value to convert
basethe 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.

Definition at line 4746 of file integer.cpp.

◆ IntToString< Integer >()

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

Converts an Integer to a string.

Parameters
valuethe Integer to convert
basethe 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));

Definition at line 4680 of file integer.cpp.

◆ Parity()

template<class T >
unsigned int Parity ( value)

Returns the parity of a value.

Template Parameters
Tclass or type
Parameters
valuethe value to provide the parity
Returns
1 if the number 1-bits in the value is odd, 0 otherwise

Definition at line 715 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
Tclass or type
Parameters
valuethe value to test
Returns
the minimum number of 8-bit bytes or octets required to represent a value

Definition at line 727 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
Tclass or type
Parameters
valuethe value to test
Returns
the maximum number of bits required to represent a value.

Definition at line 750 of file misc.h.

◆ TrailingZeros() [1/2]

unsigned int TrailingZeros ( word32  v)
inline

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

Parameters
vthe 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 775 of file misc.h.

◆ TrailingZeros() [2/2]

unsigned int TrailingZeros ( word64  v)
inline

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

Parameters
vthe 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 806 of file misc.h.

◆ Crop()

template<class T >
T Crop ( value,
size_t  bits 
)
inline

Truncates the value to the specified number of bits.

Template Parameters
Tclass or type
Parameters
valuethe value to truncate or mask
bitsthe 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 834 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
bitCountthe 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 846 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
byteCountthe 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 856 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
bitCountthe 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 866 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
bitCountthe 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 876 of file misc.h.

◆ xorbuf() [1/2]

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

Performs an XOR of a buffer with a mask.

Parameters
bufthe buffer to XOR with the mask
maskthe mask to XOR with the buffer
countthe 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.

Definition at line 32 of file misc.cpp.

◆ xorbuf() [2/2]

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
outputthe destination buffer
inputthe source buffer to XOR with the mask
maskthe mask buffer to XOR with the input buffer
countthe 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.

Definition at line 65 of file misc.cpp.

◆ VerifyBufsEqual()

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

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

Parameters
buf1the first buffer
buf2the second buffer
countthe size of the buffers, in bytes

The function effectively performs an XOR of the elements in two equally sized buffers and retruns a result based on the XOR operation. 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

Definition at line 100 of file misc.cpp.

◆ IsPowerOf2()

template<class T >
bool IsPowerOf2 ( const T &  value)
inline

Tests whether a value is a power of 2.

Parameters
valuethe 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 915 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
T1class or type
T2class or type
Parameters
athe minuend
bthe 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 946 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
T1class or type
T2class or type
Parameters
athe minuend
bthe 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 963 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
T1class or type
T2class or type
Parameters
athe first value
bthe 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 978 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
T1class or type
T2class or type
Parameters
nthe value to reduce
mthe value to reduce
to 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 997 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
T1class or type
T2class or type
Parameters
nthe value to reduce
mthe value to reduce
to 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 1027 of file misc.h.

◆ GetAlignmentOf()

template<class T >
unsigned int GetAlignmentOf ( )
inline

Returns the minimum alignment requirements of a type.

Template Parameters
Tclass 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 __BIGGEST_ALIGNMENT__ if __BIGGEST_ALIGNMENT__ is smaller than sizeof(T). sizeof(T) is used if all others are not available.

Definition at line 1053 of file misc.h.

◆ IsAlignedOn()

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

Determines whether ptr is aligned to a minimum value.

Parameters
ptrthe pointer being checked for alignment
alignmentthe 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 1081 of file misc.h.

◆ IsAligned()

template<class T >
bool IsAligned ( const void *  ptr)
inline

Determines whether ptr is minimally aligned.

Template Parameters
Tclass or type
Parameters
ptrthe 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 1092 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 1114 of file misc.h.

◆ NativeByteOrderIs()

bool NativeByteOrderIs ( ByteOrder  order)
inline

Determines whether order follows native byte ordering.

Parameters
orderthe ordering being tested against native byte ordering
Returns
true if order follows native byte ordering, false otherwise

Definition at line 1122 of file misc.h.

◆ GetCipherDir()

template<class T >
CipherDir GetCipherDir ( const T &  obj)
inline

Returns the direction the cipher is being operated.

Template Parameters
Tclass or type
Parameters
objthe 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 1138 of file misc.h.

◆ CallNewHandler()

void CallNewHandler ( )

Attempts to reclaim unused memory.

Exceptions
bad_alloc

In the normal course of running a program, a request for memory normally succeeds. If a call to AlignedAllocate or UnalignedAllocate fails, then CallNewHandler is called in an effort to recover. Internally, CallNewHandler calls set_new_handler(NULLPTR) in an effort to free memory. There is no guarantee CallNewHandler will be able to procure more memory so an allocation succeeds. If the call to set_new_handler fails, then CallNewHandler throws a bad_alloc exception.

Definition at line 268 of file misc.cpp.

◆ IncrementCounterByOne() [1/2]

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

Performs an addition with carry on a block of bytes.

Parameters
inoutthe byte block
sizethe 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 1159 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
outputthe destination block of bytes
inputthe source block of bytes
sizethe 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 1173 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
Tclass or type
Parameters
cthe condition to perform the swap
athe first value
bthe second value

Definition at line 1189 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
Tclass or type
Parameters
cthe condition to perform the swap
athe first pointer
bthe second pointer

Definition at line 1202 of file misc.h.

◆ SecureWipeBuffer()

template<class T >
void SecureWipeBuffer ( T *  buf,
size_t  n 
)

Sets each element of an array to 0.

Template Parameters
Tclass or type
Parameters
bufan array of elements
nthe 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 1218 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
Tclass or type
Parameters
bufan array of elements
nthe 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 1326 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
strC-string consisting of wide characters
throwOnErrorflag 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.

Definition at line 140 of file misc.cpp.

◆ StringWiden()

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

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

Parameters
strC-string consisting of wide characters
throwOnErrorflag 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.

Definition at line 204 of file misc.cpp.

◆ AlignedAllocate()

void* AlignedAllocate ( size_t  size)

Allocates a buffer on 16-byte boundary.

Parameters
sizethe size of the buffer

AlignedAllocate is primarily used when the data will be proccessed by MMX, SSE2 and NEON instructions. The assembly language routines rely on the alignment. If the alignment is not respected, then a SIGBUS could be generated on Unix and Linux, and an EXCEPTION_DATATYPE_MISALIGNMENT could be generated on Windows.

Note
AlignedAllocate and AlignedDeallocate are available when CRYPTOPP_BOOL_ALIGN16 is defined. CRYPTOPP_BOOL_ALIGN16 is defined in config.h

◆ AlignedDeallocate()

void AlignedDeallocate ( void *  ptr)

Frees a buffer allocated with AlignedAllocate.

Parameters
ptrthe buffer to free
Note
AlignedAllocate and AlignedDeallocate are available when CRYPTOPP_BOOL_ALIGN16 is defined. CRYPTOPP_BOOL_ALIGN16 is defined in config.h

◆ UnalignedAllocate()

void* UnalignedAllocate ( size_t  size)

Allocates a buffer.

Parameters
sizethe size of the buffer

Definition at line 325 of file misc.cpp.

◆ UnalignedDeallocate()

void UnalignedDeallocate ( void *  ptr)

Frees a buffer allocated with UnalignedAllocate.

Parameters
ptrthe buffer to free

Definition at line 333 of file misc.cpp.

◆ rotlConstant()

template<unsigned int R, class T >
T rotlConstant ( x)
inline

Performs a left rotate.

Template Parameters
Rthe number of bit positions to rotate the value
Tthe word type
Parameters
xthe 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 occassion.

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 1416 of file misc.h.

◆ rotrConstant()

template<unsigned int R, class T >
T rotrConstant ( x)
inline

Performs a right rotate.

Template Parameters
Rthe number of bit positions to rotate the value
Tthe word type
Parameters
xthe 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 occassion.

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 1442 of file misc.h.

◆ rotlFixed()

template<class T >
T rotlFixed ( x,
unsigned int  y 
)
inline

Performs a left rotate.

Template Parameters
Tthe word type
Parameters
xthe value to rotate
ythe 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 1467 of file misc.h.

◆ rotrFixed()

template<class T >
T rotrFixed ( x,
unsigned int  y 
)
inline

Performs a right rotate.

Template Parameters
Tthe word type
Parameters
xthe value to rotate
ythe 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 1492 of file misc.h.

◆ rotlVariable()

template<class T >
T rotlVariable ( x,
unsigned int  y 
)
inline

Performs a left rotate.

Template Parameters
Tthe word type
Parameters
xthe value to rotate
ythe 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 1516 of file misc.h.

◆ rotrVariable()

template<class T >
T rotrVariable ( x,
unsigned int  y 
)
inline

Performs a right rotate.

Template Parameters
Tthe word type
Parameters
xthe value to rotate
ythe 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 1536 of file misc.h.

◆ rotlMod()

template<class T >
T rotlMod ( x,
unsigned int  y 
)
inline

Performs a left rotate.

Template Parameters
Tthe word type
Parameters
xthe value to rotate
ythe 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 1553 of file misc.h.

◆ rotrMod()

template<class T >
T rotrMod ( x,
unsigned int  y 
)
inline

Performs a right rotate.

Template Parameters
Tthe word type
Parameters
xthe value to rotate
ythe 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 1569 of file misc.h.

◆ GetByte()

template<class T >
unsigned int GetByte ( ByteOrder  order,
value,
unsigned int  index 
)
inline

Gets a byte from a value.

Parameters
orderthe ByteOrder of the value
valuethe value to retrieve the byte
indexthe location of the byte to retrieve

Definition at line 1878 of file misc.h.

◆ ByteReverse() [1/5]

byte ByteReverse ( byte  value)
inline

Reverses bytes in a 8-bit value.

Parameters
valuethe 8-bit value to reverse
Note
ByteReverse returns the value passed to it since there is nothing to reverse

Definition at line 1889 of file misc.h.

◆ ByteReverse() [2/5]

word16 ByteReverse ( word16  value)
inline

Reverses bytes in a 16-bit value.

Parameters
valuethe 16-bit value to reverse

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

Definition at line 1897 of file misc.h.

◆ ByteReverse() [3/5]

word32 ByteReverse ( word32  value)
inline

Reverses bytes in a 32-bit value.

Parameters
valuethe 32-bit value to reverse

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

Definition at line 1911 of file misc.h.

◆ ByteReverse() [4/5]

word64 ByteReverse ( word64  value)
inline

Reverses bytes in a 64-bit value.

Parameters
valuethe 64-bit value to reverse

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

Definition at line 1935 of file misc.h.

◆ BitReverse() [1/5]

byte BitReverse ( byte  value)
inline

Reverses bits in a 8-bit value.

Parameters
valuethe 8-bit value to reverse

BitReverse performs a combination of shifts on the byte

Definition at line 1956 of file misc.h.

◆ BitReverse() [2/5]

word16 BitReverse ( word16  value)
inline

Reverses bits in a 16-bit value.

Parameters
valuethe 16-bit value to reverse

BitReverse performs a combination of shifts on the word16

Definition at line 1966 of file misc.h.

◆ BitReverse() [3/5]

word32 BitReverse ( word32  value)
inline

Reverses bits in a 32-bit value.

Parameters
valuethe 32-bit value to reverse

BitReverse performs a combination of shifts on the word32

Definition at line 1977 of file misc.h.

◆ BitReverse() [4/5]

word64 BitReverse ( word64  value)
inline

Reverses bits in a 64-bit value.

Parameters
valuethe 64-bit value to reverse

BitReverse performs a combination of shifts on the word64

Definition at line 1988 of file misc.h.

◆ BitReverse() [5/5]

template<class T >
T BitReverse ( value)
inline

Reverses bits in a value.

Parameters
valuethe 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 2007 of file misc.h.

◆ ConditionalByteReverse() [1/2]

template<class T >
T ConditionalByteReverse ( ByteOrder  order,
value 
)
inline

Reverses bytes in a value depending upon endianness.

Template Parameters
Tthe class or type
Parameters
orderthe ByteOrder of the data
valuethe 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 2030 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
Tthe class or type
Parameters
outthe output array of elements
inthe input array of elements
byteCountthe 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 follwoing 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 follwoing output.

V1: 00000001 00000002 00000003 00000004
V2: 01000000 02000000 03000000 04000000
See also
ConditionalByteReverse

Definition at line 2071 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
Tthe class or type
Parameters
orderthe ByteOrder of the data
outthe output array of elements
inthe input array of elements
byteCountthe 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 2097 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
Tclass or type
Parameters
assumeAlignedflag indicating alignment
orderthe ByteOrder of the data
blockthe 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 2303 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
Tclass or type
Parameters
assumeAlignedflag indicating alignment
orderthe ByteOrder of the data
resultthe word in the specified byte order
blockthe 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 2329 of file misc.h.

◆ PutWord()

template<class T >
void PutWord ( bool  assumeAligned,
ByteOrder  order,
byte *  block,
value,
const byte *  xorBlock = NULL 
)
inline

Access a block of memory.

Template Parameters
Tclass or type
Parameters
assumeAlignedflag indicating alignment
orderthe ByteOrder of the data
blockthe destination byte buffer
valuethe word in the specified byte order
xorBlockan 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 2345 of file misc.h.

◆ WordToString()

template<class T >
std::string WordToString ( value,
ByteOrder  order = BIG_ENDIAN_ORDER 
)

Convert a word to a string.

Template Parameters
Tclass or type
Parameters
valuethe word to convert
orderbyte order
Returns
a string representing the value of the word

Definition at line 2462 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
Tclass or type
Parameters
strthe string to convert
orderbyte order
Returns
a word representing the value of the string

Definition at line 2476 of file misc.h.

◆ SafeRightShift()

template<unsigned int bits, class T >
T SafeRightShift ( value)
inline

Safely right shift values when undefined behavior could occur.

Template Parameters
bitsthe number of bit positions to shift the value
Tclass or type
Parameters
valuethe 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 2560 of file misc.h.

◆ SafeLeftShift()

template<unsigned int bits, class T >
T SafeLeftShift ( value)
inline

Safely left shift values when undefined behavior could occur.

Template Parameters
bitsthe number of bit positions to shift the value
Tclass or type
Parameters
valuethe 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 2574 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
InputItInput iterator type
Tclass or type
Parameters
firstiterator to first element
lastiterator to last element
valuethe value used as a predicate
Returns
iterator to the first element in the range that is not value

Definition at line 2587 of file misc.h.