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

Classes | Friends | List of all members
Integer Class Reference

Multiple precision integer with arithmetic operations. More...

Inheritance diagram for Integer:

## Classes
class | DivideByZero
| Exception thrown when division by 0 is encountered. More...
class | OpenPGPDecodeErr
| Exception thrown when an error is encountered decoding an OpenPGP integer. More...
class | RandomNumberNotFound
| Exception thrown when a random number cannot be found that satisfies the condition. More...

## Friends
CRYPTOPP_DLL friend Integer CRYPTOPP_API | a_times_b_mod_c (const Integer &x, const Integer &y, const Integer &m)
| Modular multiplication. More...
CRYPTOPP_DLL friend Integer CRYPTOPP_API | a_exp_b_mod_c (const Integer &x, const Integer &e, const Integer &m)
| Modular exponentiation. More...

## ENUMS, EXCEPTIONS, and TYPEDEFS
enum | Sign { POSITIVE =0, NEGATIVE =1 }
| Used internally to represent the integer. More...
enum | Signedness { UNSIGNED, SIGNED }
| Used when importing and exporting integers. More...
enum | RandomNumberType { ANY, PRIME }
| Properties of a random integer. More...

## CREATORS
| Integer ()
| Creates the zero integer.
| Integer (const Integer &t)
| copy constructor
| Integer (signed long value)
| Convert from signed long.
| Integer (Sign sign, lword value)
| Convert from lword. More...
| Integer (Sign sign, word highWord, word lowWord)
| Convert from two words. More...
| Integer (const char *str, ByteOrder order=BIG_ENDIAN_ORDER)
| Convert from a C-string. More...
| Integer (const wchar_t *str, ByteOrder order=BIG_ENDIAN_ORDER)
| Convert from a wide C-string. More...
| Integer (const byte *encodedInteger, size_t byteCount, Signedness sign=UNSIGNED, ByteOrder order=BIG_ENDIAN_ORDER)
| Convert from a big-endian byte array. More...
| Integer (BufferedTransformation &bt, size_t byteCount, Signedness sign=UNSIGNED, ByteOrder order=BIG_ENDIAN_ORDER)
| Convert from a big-endian array. More...
| Integer (BufferedTransformation &bt)
| Convert from a BER encoded byte array. More...
| Integer (RandomNumberGenerator &rng, size_t bitCount)
| Create a random integer. More...
| Integer (RandomNumberGenerator &rng, const Integer &min, const Integer &max, RandomNumberType rnType=ANY, const Integer &equiv=Zero(), const Integer &mod=One())
| Create a random integer of special form. More...
static const Integer &CRYPTOPP_API | Zero ()
| Integer representing 0. More...
static const Integer &CRYPTOPP_API | One ()
| Integer representing 1. More...
static const Integer &CRYPTOPP_API | Two ()
| Integer representing 2. More...
static Integer CRYPTOPP_API | Power2 (size_t e)
| Exponentiates to a power of 2. More...

## ENCODE/DECODE
size_t | MinEncodedSize (Signedness sign=UNSIGNED) const
| Minimum number of bytes to encode this integer. More...
void | Encode (byte *output, size_t outputLen, Signedness sign=UNSIGNED) const
| Encode in big-endian format. More...
void | Encode (BufferedTransformation &bt, size_t outputLen, Signedness sign=UNSIGNED) const
| Encode in big-endian format. More...
void | DEREncode (BufferedTransformation &bt) const
| Encode in DER format. More...
void | DEREncodeAsOctetString (BufferedTransformation &bt, size_t length) const
| Encode absolute value as big-endian octet string. More...
size_t | OpenPGPEncode (byte *output, size_t bufferSize) const
| Encode absolute value in OpenPGP format. More...
size_t | OpenPGPEncode (BufferedTransformation &bt) const
| Encode absolute value in OpenPGP format. More...
void | Decode (const byte *input, size_t inputLen, Signedness sign=UNSIGNED)
| Decode from big-endian byte array. More...
void | Decode (BufferedTransformation &bt, size_t inputLen, Signedness sign=UNSIGNED)
| Decode nonnegative value from big-endian byte array. More...
void | BERDecode (const byte *input, size_t inputLen)
| Decode from BER format. More...
void | BERDecode (BufferedTransformation &bt)
| Decode from BER format. More...
void | BERDecodeAsOctetString (BufferedTransformation &bt, size_t length)
| Decode nonnegative value from big-endian octet string. More...
void | OpenPGPDecode (const byte *input, size_t inputLen)
| Decode from OpenPGP format. More...
void | OpenPGPDecode (BufferedTransformation &bt)
| Decode from OpenPGP format. More...

## ACCESSORS
bool | IsConvertableToLong () const
| Determines if the Integer is convertable to Long. More...
signed long | ConvertToLong () const
| Convert the Integer to Long. More...
unsigned int | BitCount () const
| Determines the number of bits required to represent the Integer. More...
unsigned int | ByteCount () const
| Determines the number of bytes required to represent the Integer. More...
unsigned int | WordCount () const
| Determines the number of words required to represent the Integer. More...
bool | GetBit (size_t i) const
| Provides the i-th bit of the Integer. More...
byte | GetByte (size_t i) const
| Provides the i-th byte of the Integer. More...
lword | GetBits (size_t i, size_t n) const
| Provides the low order bits of the Integer. More...
bool | IsZero () const
| Determines if the Integer is 0. More...
bool | NotZero () const
| Determines if the Integer is non-0. More...
bool | IsNegative () const
| Determines if the Integer is negative. More...
bool | NotNegative () const
| Determines if the Integer is non-negative. More...
bool | IsPositive () const
| Determines if the Integer is positive. More...
bool | NotPositive () const
| Determines if the Integer is non-positive. More...
bool | IsEven () const
| Determines if the Integer is even parity. More...
bool | IsOdd () const
| Determines if the Integer is odd parity. More...

## MANIPULATORS
Integer & | operator= (const Integer &t)
| Assignment. More...
Integer & | operator+= (const Integer &t)
| Addition Assignment. More...
Integer & | operator-= (const Integer &t)
| Subtraction Assignment. More...
Integer & | operator*= (const Integer &t)
| Multiplication Assignment. More...
Integer & | operator/= (const Integer &t)
| Division Assignment. More...
Integer & | operator%= (const Integer &t)
| Remainder Assignment. More...
Integer & | operator/= (word t)
| Division Assignment. More...
Integer & | operator%= (word t)
| Remainder Assignment. More...
Integer & | operator<<= (size_t n)
| Left-shift Assignment. More...
Integer & | operator>>= (size_t n)
| Right-shift Assignment. More...
Integer & | operator &= (const Integer &t)
| Bitwise AND Assignment. More...
Integer & | operator|= (const Integer &t)
| Bitwise OR Assignment. More...
Integer & | operator^= (const Integer &t)
| Bitwise XOR Assignment. More...
void | Randomize (RandomNumberGenerator &rng, size_t bitCount)
| Set this Integer to random integer. More...
void | Randomize (RandomNumberGenerator &rng, const Integer &min, const Integer &max)
| Set this Integer to random integer. More...
bool | Randomize (RandomNumberGenerator &rng, const Integer &min, const Integer &max, RandomNumberType rnType, const Integer &equiv=Zero(), const Integer &mod=One())
| Set this Integer to random integer of special form. More...
bool | GenerateRandomNoThrow (RandomNumberGenerator &rng, const NameValuePairs &params=g_nullNameValuePairs)
| Generate a random number. More...
void | GenerateRandom (RandomNumberGenerator &rng, const NameValuePairs &params=g_nullNameValuePairs)
| Generate a random number. More...
void | SetBit (size_t n, bool value=1)
| Set the n-th bit to value. More...
void | SetByte (size_t n, byte value)
| Set the n-th byte to value. More...
void | Negate ()
| Reverse the Sign of the Integer.
void | SetPositive ()
| Sets the Integer to positive.
void | SetNegative ()
| Sets the Integer to negative.
void | swap (Integer &a)
| Swaps this Integer with another Integer.

## UNARY OPERATORS
bool | operator! () const
| Negation.
Integer | operator+ () const
| Addition.
Integer | operator- () const
| Subtraction.
Integer & | operator++ ()
| Pre-increment.
Integer & | operator-- ()
| Pre-decrement.
Integer | operator++ (int)
| Post-increment.
Integer | operator-- (int)
| Post-decrement.

## BINARY OPERATORS
int | Compare (const Integer &a) const
| Perform signed comparison. More...
Integer | Plus (const Integer &b) const
| Addition.
Integer | Minus (const Integer &b) const
| Subtraction.
Integer | Times (const Integer &b) const
| Multiplication. More...
Integer | DividedBy (const Integer &b) const
| Division.
Integer | Modulo (const Integer &b) const
| Remainder. More...
Integer | DividedBy (word b) const
| Division.
word | Modulo (word b) const
| Remainder. More...
Integer | And (const Integer &t) const
| Bitwise AND. More...
Integer | Or (const Integer &t) const
| Bitwise OR. More...
Integer | Xor (const Integer &t) const
| Bitwise XOR. More...
Integer | operator>> (size_t n) const
| Right-shift.
Integer | operator<< (size_t n) const
| Left-shift.

## OTHER ARITHMETIC FUNCTIONS
Integer | AbsoluteValue () const
| Retrieve the absolute value of this integer.
Integer | Doubled () const
| Add this integer to itself.
Integer | Squared () const
| Multiply this integer by itself. More...
Integer | SquareRoot () const
| Extract square root. More...
bool | IsSquare () const
| Determine whether this integer is a perfect square.
bool | IsUnit () const
| Determine if 1 or -1. More...
Integer | MultiplicativeInverse () const
| Calculate multiplicative inverse. More...
Integer | InverseMod (const Integer &n) const
| Calculate multiplicative inverse. More...
word | InverseMod (word n) const
| Calculate multiplicative inverse. More...
static void CRYPTOPP_API | Divide (Integer &r, Integer &q, const Integer &a, const Integer &d)
| Extended Division. More...
static void CRYPTOPP_API | Divide (word &r, Integer &q, const Integer &a, word d)
| Extended Division. More...
static void CRYPTOPP_API | DivideByPowerOf2 (Integer &r, Integer &q, const Integer &a, unsigned int n)
| Extended Division. More...
static Integer CRYPTOPP_API | Gcd (const Integer &a, const Integer &n)
| Calculate greatest common divisor. More...

## INPUT/OUTPUT
CRYPTOPP_DLL std::istream &CRYPTOPP_API | operator>> (std::istream &in, Integer &a)
| Extraction operator. More...
CRYPTOPP_DLL std::ostream &CRYPTOPP_API | operator<< (std::ostream &out, const Integer &a)
| Insertion operator. More...

## Additional Inherited Members
Public Member Functions inherited from ASN1Object
virtual void | BEREncode (BufferedTransformation &bt) const
| Encode this object into a BufferedTransformation. More...

## Detailed Description

Multiple precision integer with arithmetic operations.

The Integer class can represent positive and negative integers with absolute value less than (256**sizeof(word))(256**sizeof(int)).

Internally, the library uses a sign magnitude representation, and the class has two data members. The first is a IntegerSecBlock (a SecBlock<word>) and it is used to hold the representation. The second is a Sign (an enumeration), and it is used to track the sign of the Integer.

For details on how the Integer class initializes its function pointers using InitializeInteger and how it creates Integer::Zero(), Integer::One(), and Integer::Two(), then see the comments at the top of `integer.cpp`.

Since
  Crypto++ 1.0

Definition at line 49 of file integer.h.

## Member Enumeration Documentation

## ◆ Sign

enum Integer::Sign

Used internally to represent the integer.

Sign is used internally to represent the integer. It is also used in a few API functions.

See also
  SetPositive(), SetNegative(), Signedness

Enumerator
POSITIVE | the value is positive or 0
NEGATIVE | the value is negative

Definition at line 73 of file integer.h.

## ◆ Signedness

enum Integer::Signedness

Used when importing and exporting integers.

Signedness is usually used in API functions.

See also
  Sign

Enumerator
UNSIGNED | an unsigned value
SIGNED | a signed value

Definition at line 83 of file integer.h.

## ◆ RandomNumberType

enum Integer::RandomNumberType

Properties of a random integer.

Enumerator
ANY | a number with no special properties
PRIME | a number which is probabilistically prime

Definition at line 91 of file integer.h.

## Constructor & Destructor Documentation

## ◆ Integer() [1/9]

Integer::Integer | ( | Sign | sign,
|  | lword | value
| ) |  |

Convert from lword.

Parameters

  sign | enumeration indicating Sign
  value | the long word

Definition at line 2978 of file integer.cpp.

## ◆ Integer() [2/9]

Integer::Integer | ( | Sign | sign,
|  | word | highWord,
|  | word | lowWord
| ) |  |

Convert from two words.

Parameters

  sign | enumeration indicating Sign
  highWord | the high word
  lowWord | the low word

Definition at line 2999 of file integer.cpp.

## ◆ Integer() [3/9]

Integer::Integer | ( | const char * | str,
|  | ByteOrder | order = `BIG_ENDIAN_ORDER`
| ) |  |
| explicit

Convert from a C-string.

Parameters

  str | C-string value
  order | the ByteOrder of the string to be processed

`str` can be in base 2, 8, 10, or 16. Base is determined by a case insensitive suffix of 'h', 'o', or 'b'. No suffix means base 10.

Byte order was added at Crypto++ 5.7 to allow use of little-endian integers with curve25519, Poly1305 and Microsoft CAPI.

Definition at line 3322 of file integer.cpp.

## ◆ Integer() [4/9]

Integer::Integer | ( | const wchar_t * | str,
|  | ByteOrder | order = `BIG_ENDIAN_ORDER`
| ) |  |
| explicit

Convert from a wide C-string.

Parameters

  str | wide C-string value
  order | the ByteOrder of the string to be processed

`str` can be in base 2, 8, 10, or 16. Base is determined by a case insensitive suffix of 'h', 'o', or 'b'. No suffix means base 10.

Byte order was added at Crypto++ 5.7 to allow use of little-endian integers with curve25519, Poly1305 and Microsoft CAPI.

Definition at line 3328 of file integer.cpp.

## ◆ Integer() [5/9]

Integer::Integer | ( | const byte * | encodedInteger,
|  | size_t | byteCount,
|  | Signedness | sign = `UNSIGNED`,
|  | ByteOrder | order = `BIG_ENDIAN_ORDER`
| ) |  |

Convert from a big-endian byte array.

Parameters

  encodedInteger | big-endian byte array
  byteCount | length of the byte array
  sign | enumeration indicating Signedness
  order | the ByteOrder of the array to be processed

Byte order was added at Crypto++ 5.7 to allow use of little-endian integers with curve25519, Poly1305 and Microsoft CAPI.

Definition at line 3047 of file integer.cpp.

## ◆ Integer() [6/9]

Integer::Integer | ( | BufferedTransformation & | bt,
|  | size_t | byteCount,
|  | Signedness | sign = `UNSIGNED`,
|  | ByteOrder | order = `BIG_ENDIAN_ORDER`
| ) |  |

Convert from a big-endian array.

Parameters

  bt | BufferedTransformation object with big-endian byte array
  byteCount | length of the byte array
  sign | enumeration indicating Signedness
  order | the ByteOrder of the data to be processed

Byte order was added at Crypto++ 5.7 to allow use of little-endian integers with curve25519, Poly1305 and Microsoft CAPI.

Definition at line 3029 of file integer.cpp.

## ◆ Integer() [7/9]

Integer::Integer | ( | BufferedTransformation & | bt | ) |
| explicit

Convert from a BER encoded byte array.

Parameters

  bt | BufferedTransformation object with BER encoded byte array

Definition at line 3070 of file integer.cpp.

## ◆ Integer() [8/9]

Integer::Integer | ( | RandomNumberGenerator & | rng,
|  | size_t | bitCount
| ) |  |

Create a random integer.

Parameters

  rng | RandomNumberGenerator used to generate material
  bitCount | the number of bits in the resulting integer

The random integer created is uniformly distributed over `[0, 2bitCount]`.

Definition at line 3076 of file integer.cpp.

## ◆ Integer() [9/9]

Integer::Integer | ( | RandomNumberGenerator & | rng,
|  | const Integer & | min,
|  | const Integer & | max,
|  | RandomNumberType | rnType = `ANY`,
|  | const Integer & | equiv = `Zero()`,
|  | const Integer & | mod = `One()`
| ) |  |

Create a random integer of special form.

Parameters

  rng | RandomNumberGenerator used to generate material
  min | the minimum value
  max | the maximum value
  rnType | RandomNumberType to specify the type
  equiv | the equivalence class based on the parameter `mod`
  mod | the modulus used to reduce the equivalence class

Exceptions

  RandomNumberNotFound | if the set is empty.

Ideally, the random integer created should be uniformly distributed over `{x | min <= x <= max` and `x` is of rnType and `x % mod == equiv}`. However the actual distribution may not be uniform because sequential search is used to find an appropriate number from a random starting point.

May return (with very small probability) a pseudoprime when a prime is requested and `max > lastSmallPrime*lastSmallPrime`. `lastSmallPrime` is declared in nbtheory.h.

Definition at line 3081 of file integer.cpp.

## Member Function Documentation

## ◆ Zero()

const Integer & Integer::Zero | ( |  | ) |
| static

Integer representing 0.

Returns
  an Integer representing 0

Zero() avoids calling constructors for frequently used integers

Definition at line 4856 of file integer.cpp.

## ◆ One()

const Integer & Integer::One | ( |  | ) |
| static

Integer representing 1.

Returns
  an Integer representing 1

One() avoids calling constructors for frequently used integers

Definition at line 4868 of file integer.cpp.

## ◆ Two()

const Integer & Integer::Two | ( |  | ) |
| static

Integer representing 2.

Returns
  an Integer representing 2

Two() avoids calling constructors for frequently used integers

Definition at line 4880 of file integer.cpp.

## ◆ Power2()

Integer Integer::Power2 | ( | size_t | e | ) |
| static

Exponentiates to a power of 2.

Returns
  the Integer 2e

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 3087 of file integer.cpp.

## ◆ MinEncodedSize()

size_t Integer::MinEncodedSize | ( | Signedness | sign = `UNSIGNED` | ) | const

Minimum number of bytes to encode this integer.

Parameters

  sign | enumeration indicating Signedness

Note
  The MinEncodedSize() of 0 is 1.

Definition at line 3396 of file integer.cpp.

## ◆ Encode() [1/2]

void Integer::Encode | ( | byte * | output,
|  | size_t | outputLen,
|  | Signedness | sign = `UNSIGNED`
| ) |  | const

Encode in big-endian format.

Parameters

  output | big-endian byte array
  outputLen | length of the byte array
  sign | enumeration indicating Signedness

Unsigned means encode absolute value, signed means encode two's complement if negative.

outputLen can be used to ensure an Integer is encoded to an exact size (rather than a minimum size). An exact size is useful, for example, when encoding to a field element size.

Definition at line 3411 of file integer.cpp.

## ◆ Encode() [2/2]

void Integer::Encode | ( | BufferedTransformation & | bt,
|  | size_t | outputLen,
|  | Signedness | sign = `UNSIGNED`
| ) |  | const

Encode in big-endian format.

Parameters

  bt | BufferedTransformation object
  outputLen | length of the encoding
  sign | enumeration indicating Signedness

Unsigned means encode absolute value, signed means encode two's complement if negative.

outputLen can be used to ensure an Integer is encoded to an exact size (rather than a minimum size). An exact size is useful, for example, when encoding to a field element size.

Definition at line 3418 of file integer.cpp.

## ◆ DEREncode()

void Integer::DEREncode | ( | BufferedTransformation & | bt | ) | const
| virtual

Encode in DER format.

Parameters

  bt | BufferedTransformation object

Encodes the Integer using Distinguished Encoding Rules The result is placed into a BufferedTransformation object

Implements ASN1Object.

Definition at line 3433 of file integer.cpp.

## ◆ DEREncodeAsOctetString()

void Integer::DEREncodeAsOctetString | ( | BufferedTransformation & | bt,
|  | size_t | length
| ) |  | const

Encode absolute value as big-endian octet string.

Parameters

  bt | BufferedTransformation object
  length | the number of mytes to decode

Definition at line 3456 of file integer.cpp.

## ◆ OpenPGPEncode() [1/2]

size_t Integer::OpenPGPEncode | ( | byte * | output,
|  | size_t | bufferSize
| ) |  | const

Encode absolute value in OpenPGP format.

Parameters

  output | big-endian byte array
  bufferSize | length of the byte array

Returns
  length of the output

OpenPGPEncode places result into the buffer and returns the number of bytes used for the encoding

Definition at line 3472 of file integer.cpp.

## ◆ OpenPGPEncode() [2/2]

size_t Integer::OpenPGPEncode | ( | BufferedTransformation & | bt | ) | const

Encode absolute value in OpenPGP format.

Parameters

  bt | BufferedTransformation object

Returns
  length of the output

OpenPGPEncode places result into a BufferedTransformation object and returns the number of bytes used for the encoding

Definition at line 3480 of file integer.cpp.

## ◆ Decode() [1/2]

void Integer::Decode | ( | const byte * | input,
|  | size_t | inputLen,
|  | Signedness | sign = `UNSIGNED`
| ) |  |

Decode from big-endian byte array.

Parameters

  input | big-endian byte array
  inputLen | length of the byte array
  sign | enumeration indicating Signedness

Definition at line 3357 of file integer.cpp.

## ◆ Decode() [2/2]

void Integer::Decode | ( | BufferedTransformation & | bt,
|  | size_t | inputLen,
|  | Signedness | sign = `UNSIGNED`
| ) |  |

Decode nonnegative value from big-endian byte array.

Parameters

  bt | BufferedTransformation object
  inputLen | length of the byte array
  sign | enumeration indicating Signedness

Note
  `bt.MaxRetrievable() >= inputLen`.

Definition at line 3364 of file integer.cpp.

## ◆ BERDecode() [1/2]

void Integer::BERDecode | ( | const byte * | input,
|  | size_t | inputLen
| ) |  |

Decode from BER format.

Parameters

  input | big-endian byte array
  inputLen | length of the byte array

Definition at line 3440 of file integer.cpp.

## ◆ BERDecode() [2/2]

void Integer::BERDecode | ( | BufferedTransformation & | bt | ) |
| virtual

Decode from BER format.

Parameters

  bt | BufferedTransformation object

Implements ASN1Object.

Definition at line 3447 of file integer.cpp.

## ◆ BERDecodeAsOctetString()

void Integer::BERDecodeAsOctetString | ( | BufferedTransformation & | bt,
|  | size_t | length
| ) |  |

Decode nonnegative value from big-endian octet string.

Parameters

  bt | BufferedTransformation object
  length | length of the byte array

Definition at line 3463 of file integer.cpp.

## ◆ OpenPGPDecode() [1/2]

void Integer::OpenPGPDecode | ( | const byte * | input,
|  | size_t | inputLen
| ) |  |

Decode from OpenPGP format.

Parameters

  input | big-endian byte array
  inputLen | length of the byte array

Definition at line 3489 of file integer.cpp.

## ◆ OpenPGPDecode() [2/2]

void Integer::OpenPGPDecode | ( | BufferedTransformation & | bt | ) |

Decode from OpenPGP format.

Parameters

  bt | BufferedTransformation object

Definition at line 3496 of file integer.cpp.

## ◆ IsConvertableToLong()

bool Integer::IsConvertableToLong | ( |  | ) | const

Determines if the Integer is convertable to Long.

Returns
  true if *this can be represented as a signed long

See also
  ConvertToLong()

Definition at line 3006 of file integer.cpp.

## ◆ ConvertToLong()

signed long Integer::ConvertToLong | ( |  | ) | const

Convert the Integer to Long.

Returns
  equivalent signed long if possible, otherwise undefined

See also
  IsConvertableToLong()

Definition at line 3020 of file integer.cpp.

## ◆ BitCount()

unsigned int Integer::BitCount | ( |  | ) | const

Determines the number of bits required to represent the Integer.

Returns
  number of significant bits

BitCount is calculated as `floor(log2(abs(*this))) + 1`.

Definition at line 3348 of file integer.cpp.

## ◆ ByteCount()

unsigned int Integer::ByteCount | ( |  | ) | const

Determines the number of bytes required to represent the Integer.

Returns
  number of significant bytes

ByteCount is calculated as `ceiling(BitCount()/8)`.

Definition at line 3339 of file integer.cpp.

## ◆ WordCount()

unsigned int Integer::WordCount | ( |  | ) | const

Determines the number of words required to represent the Integer.

Returns
  number of significant words

WordCount is calculated as `ceiling(ByteCount()/sizeof(word))`.

Definition at line 3334 of file integer.cpp.

## ◆ GetBit()

bool Integer::GetBit | ( | size_t | i | ) | const

Provides the i-th bit of the Integer.

Returns
  the i-th bit, i=0 being the least significant bit

Definition at line 3111 of file integer.cpp.

## ◆ GetByte()

byte Integer::GetByte | ( | size_t | i | ) | const

Provides the i-th byte of the Integer.

Returns
  the i-th byte

Definition at line 3134 of file integer.cpp.

## ◆ GetBits()

lword Integer::GetBits | ( | size_t | i,
|  | size_t | n
| ) |  | const

Provides the low order bits of the Integer.

Returns
  n lowest bits of *this >> i

Definition at line 3150 of file integer.cpp.

## ◆ IsZero()

bool Integer::IsZero | ( |  | ) | const
| inline

Determines if the Integer is 0.

Returns
  true if the Integer is 0, false otherwise

Definition at line 333 of file integer.h.

## ◆ NotZero()

bool Integer::NotZero | ( |  | ) | const
| inline

Determines if the Integer is non-0.

Returns
  true if the Integer is non-0, false otherwise

Definition at line 336 of file integer.h.

## ◆ IsNegative()

bool Integer::IsNegative | ( |  | ) | const
| inline

Determines if the Integer is negative.

Returns
  true if the Integer is negative, false otherwise

Definition at line 339 of file integer.h.

## ◆ NotNegative()

bool Integer::NotNegative | ( |  | ) | const
| inline

Determines if the Integer is non-negative.

Returns
  true if the Integer is non-negative, false otherwise

Definition at line 342 of file integer.h.

## ◆ IsPositive()

bool Integer::IsPositive | ( |  | ) | const
| inline

Determines if the Integer is positive.

Returns
  true if the Integer is positive, false otherwise

Definition at line 345 of file integer.h.

## ◆ NotPositive()

bool Integer::NotPositive | ( |  | ) | const
| inline

Determines if the Integer is non-positive.

Returns
  true if the Integer is non-positive, false otherwise

Definition at line 348 of file integer.h.

## ◆ IsEven()

bool Integer::IsEven | ( |  | ) | const
| inline

Determines if the Integer is even parity.

Returns
  true if the Integer is even, false otherwise

Definition at line 351 of file integer.h.

## ◆ IsOdd()

bool Integer::IsOdd | ( |  | ) | const
| inline

Determines if the Integer is odd parity.

Returns
  true if the Integer is odd, false otherwise

Definition at line 354 of file integer.h.

## ◆ operator=()

Integer & Integer::operator= | ( | const Integer & | t | ) |

Assignment.

Parameters

  t | the other Integer

Returns
  the result of assignment

Definition at line 3099 of file integer.cpp.

## ◆ operator+=()

Integer & Integer::operator+= | ( | const Integer & | t | ) |

Addition Assignment.

Parameters

  t | the other Integer

Returns
  the result of `*this + t`

Definition at line 3957 of file integer.cpp.

## ◆ operator-=()

Integer & Integer::operator-= | ( | const Integer & | t | ) |

Subtraction Assignment.

Parameters

  t | the other Integer

Returns
  the result of `*this - t`

Definition at line 4003 of file integer.cpp.

## ◆ operator*=()

Integer& Integer::operator*= | ( | const Integer & | t | ) |
| inline

Multiplication Assignment.

Parameters

  t | the other Integer

Returns
  the result of `*this * t`

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 375 of file integer.h.

## ◆ operator/=() [1/2]

Integer& Integer::operator/= | ( | const Integer & | t | ) |
| inline

Division Assignment.

Parameters

  t | the other Integer

Returns
  the result of `*this / t`

Definition at line 379 of file integer.h.

## ◆ operator%=() [1/2]

Integer& Integer::operator%= | ( | const Integer & | t | ) |
| inline

Remainder Assignment.

Parameters

  t | the other Integer

Returns
  the result of `*this % t`

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 384 of file integer.h.

## ◆ operator/=() [2/2]

Integer& Integer::operator/= | ( | word | t | ) |
| inline

Division Assignment.

Parameters

  t | the other word

Returns
  the result of `*this / t`

Definition at line 388 of file integer.h.

## ◆ operator%=() [2/2]

Integer& Integer::operator%= | ( | word | t | ) |
| inline

Remainder Assignment.

Parameters

  t | the other word

Returns
  the result of `*this % t`

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 393 of file integer.h.

## ◆ operator<<=()

Integer & Integer::operator<<= | ( | size_t | n | ) |

Left-shift Assignment.

Parameters

  n | number of bits to shift

Returns
  reference to this Integer

Definition at line 4026 of file integer.cpp.

## ◆ operator>>=()

Integer & Integer::operator>>= | ( | size_t | n | ) |

Right-shift Assignment.

Parameters

  n | number of bits to shift

Returns
  reference to this Integer

Definition at line 4038 of file integer.cpp.

## ◆ operator &=()

Integer& Integer::operator&= | ( | const Integer & | t | ) |

Bitwise AND Assignment.

Parameters

  t | the other Integer

Returns
  the result of *this & t

operator&=() performs a bitwise AND on *this. Missing bits are truncated at the most significant bit positions, so the result is as small as the smaller of the operands.

Internally, Crypto++ uses a sign-magnitude representation. The library does not attempt to interpret bits, and the result is always POSITIVE. If needed, the integer should be converted to a 2's compliment representation before performing the operation.

Since
  Crypto++ 6.0

## ◆ operator|=()

Integer & Integer::operator|= | ( | const Integer & | t | ) |

Bitwise OR Assignment.

Parameters

  t | the second Integer

Returns
  the result of *this | t

operator|=() performs a bitwise OR on *this. Missing bits are shifted in at the most significant bit positions, so the result is as large as the larger of the operands.

Internally, Crypto++ uses a sign-magnitude representation. The library does not attempt to interpret bits, and the result is always POSITIVE. If needed, the integer should be converted to a 2's compliment representation before performing the operation.

Since
  Crypto++ 6.0

Definition at line 4064 of file integer.cpp.

## ◆ operator^=()

Integer & Integer::operator^= | ( | const Integer & | t | ) |

Bitwise XOR Assignment.

Parameters

  t | the other Integer

Returns
  the result of *this ^ t

operator^=() performs a bitwise XOR on *this. Missing bits are shifted in at the most significant bit positions, so the result is as large as the larger of the operands.

Internally, Crypto++ uses a sign-magnitude representation. The library does not attempt to interpret bits, and the result is always POSITIVE. If needed, the integer should be converted to a 2's compliment representation before performing the operation.

Since
  Crypto++ 6.0

Definition at line 4085 of file integer.cpp.

## ◆ Randomize() [1/3]

void Integer::Randomize | ( | RandomNumberGenerator & | rng,
|  | size_t | bitCount
| ) |  |

Set this Integer to random integer.

Parameters

  rng | RandomNumberGenerator used to generate material
  bitCount | the number of bits in the resulting integer

The random integer created is uniformly distributed over `[0, 2bitCount]`.

Definition at line 3504 of file integer.cpp.

## ◆ Randomize() [2/3]

void Integer::Randomize | ( | RandomNumberGenerator & | rng,
|  | const Integer & | min,
|  | const Integer & | max
| ) |  |

Set this Integer to random integer.

Parameters

  rng | RandomNumberGenerator used to generate material
  min | the minimum value
  max | the maximum value

The random integer created is uniformly distributed over `[min, max]`.

Definition at line 3514 of file integer.cpp.

## ◆ Randomize() [3/3]

bool Integer::Randomize | ( | RandomNumberGenerator & | rng,
|  | const Integer & | min,
|  | const Integer & | max,
|  | RandomNumberType | rnType,
|  | const Integer & | equiv = `Zero()`,
|  | const Integer & | mod = `One()`
| ) |  |

Set this Integer to random integer of special form.

Parameters

  rng | RandomNumberGenerator used to generate material
  min | the minimum value
  max | the maximum value
  rnType | RandomNumberType to specify the type
  equiv | the equivalence class based on the parameter `mod`
  mod | the modulus used to reduce the equivalence class

Exceptions

  RandomNumberNotFound | if the set is empty.

Ideally, the random integer created should be uniformly distributed over `{x | min <= x <= max` and `x` is of rnType and `x % mod == equiv}`. However the actual distribution may not be uniform because sequential search is used to find an appropriate number from a random starting point.

May return (with very small probability) a pseudoprime when a prime is requested and `max > lastSmallPrime*lastSmallPrime`. `lastSmallPrime` is declared in nbtheory.h.

Definition at line 3531 of file integer.cpp.

## ◆ GenerateRandomNoThrow()

bool Integer::GenerateRandomNoThrow | ( | RandomNumberGenerator & | rng,
|  | const NameValuePairs & | params = `g_nullNameValuePairs`
| ) |  |

Generate a random number.

Parameters

  rng | RandomNumberGenerator used to generate material
  params | additional parameters that cannot be passed directly to the function

Returns
  true if a random number was generated, false otherwise

GenerateRandomNoThrow attempts to generate a random number according to the parameters specified in params. The function does not throw RandomNumberNotFound.

The example below generates a prime number using NameValuePairs that Integer class recognizes. The names are not provided in argnames.h.

        AutoSeededRandomPool prng;
        AlgorithmParameters params = MakeParameters("BitLength", 2048)
                                                   ("RandomNumberType", Integer::PRIME);
        Integer x;
        if (x.GenerateRandomNoThrow(prng, params) == false)
            throw std::runtime_error("Failed to generate prime number");

Definition at line 3568 of file integer.cpp.

## ◆ GenerateRandom()

void Integer::GenerateRandom | ( | RandomNumberGenerator & | rng,
|  | const NameValuePairs & | params = `g_nullNameValuePairs`
| ) |  |
| inline

Generate a random number.

Parameters

  rng | RandomNumberGenerator used to generate material
  params | additional parameters that cannot be passed directly to the function

Exceptions

  RandomNumberNotFound | if a random number is not found

GenerateRandom attempts to generate a random number according to the parameters specified in params.

The example below generates a prime number using NameValuePairs that Integer class recognizes. The names are not provided in argnames.h.

        AutoSeededRandomPool prng;
        AlgorithmParameters params = MakeParameters("BitLength", 2048)
                                                   ("RandomNumberType", Integer::PRIME);
        Integer x;
        try { x.GenerateRandom(prng, params); }
        catch (RandomNumberNotFound&) { x = -1; }

Definition at line 506 of file integer.h.

## ◆ SetBit()

void Integer::SetBit | ( | size_t | n,
|  | bool | value = `1`
| ) |  |

Set the n-th bit to value.

0-based numbering.

Definition at line 3120 of file integer.cpp.

## ◆ SetByte()

void Integer::SetByte | ( | size_t | n,
|  | byte | value
| ) |  |

Set the n-th byte to value.

0-based numbering.

Definition at line 3143 of file integer.cpp.

## ◆ Compare()

int Integer::Compare | ( | const Integer & | a | ) | const

Perform signed comparison.

Parameters

  a | the Integer to comapre

Return values

  -1 | if `*this < a`
  0 | if `*this = a`
  1 | if `*this > a`

Definition at line 4345 of file integer.cpp.

## ◆ Times()

Integer Integer::Times | ( | const Integer & | b | ) | const

Multiplication.

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 4130 of file integer.cpp.

## ◆ Modulo() [1/2]

Integer Integer::Modulo | ( | const Integer & | b | ) | const

Remainder.

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 4241 of file integer.cpp.

## ◆ Modulo() [2/2]

word Integer::Modulo | ( | word | b | ) | const

Remainder.

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 4292 of file integer.cpp.

## ◆ And()

Integer Integer::And | ( | const Integer & | t | ) | const

Bitwise AND.

Parameters

  t | the other Integer

Returns
  the result of `*this & t`

And() performs a bitwise AND on the operands. Missing bits are truncated at the most significant bit positions, so the result is as small as the smaller of the operands.

Internally, Crypto++ uses a sign-magnitude representation. The library does not attempt to interpret bits, and the result is always POSITIVE. If needed, the integer should be converted to a 2's compliment representation before performing the operation.

Since
  Crypto++ 6.0

Definition at line 3784 of file integer.cpp.

## ◆ Or()

Integer Integer::Or | ( | const Integer & | t | ) | const

Bitwise OR.

Parameters

  t | the other Integer

Returns
  the result of `*this | t`

Or() performs a bitwise OR on the operands. Missing bits are shifted in at the most significant bit positions, so the result is as large as the larger of the operands.

Internally, Crypto++ uses a sign-magnitude representation. The library does not attempt to interpret bits, and the result is always POSITIVE. If needed, the integer should be converted to a 2's compliment representation before performing the operation.

Since
  Crypto++ 6.0

Definition at line 3810 of file integer.cpp.

## ◆ Xor()

Integer Integer::Xor | ( | const Integer & | t | ) | const

Bitwise XOR.

Parameters

  t | the other Integer

Returns
  the result of `*this ^ t`

Xor() performs a bitwise XOR on the operands. Missing bits are shifted in at the most significant bit positions, so the result is as large as the larger of the operands.

Internally, Crypto++ uses a sign-magnitude representation. The library does not attempt to interpret bits, and the result is always POSITIVE. If needed, the integer should be converted to a 2's compliment representation before performing the operation.

Since
  Crypto++ 6.0

Definition at line 3836 of file integer.cpp.

## ◆ Squared()

Integer Integer::Squared | ( |  | ) | const
| inline

Multiply this integer by itself.

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 631 of file integer.h.

## ◆ SquareRoot()

Integer Integer::SquareRoot | ( |  | ) | const

Extract square root.

if negative return 0, else return floor of square root

Definition at line 4363 of file integer.cpp.

## ◆ IsUnit()

bool Integer::IsUnit | ( |  | ) | const

Determine if 1 or -1.

Returns
  true if this integer is 1 or -1, false otherwise

Definition at line 4387 of file integer.cpp.

## ◆ MultiplicativeInverse()

Integer Integer::MultiplicativeInverse | ( |  | ) | const

Calculate multiplicative inverse.

Returns
  MultiplicativeInverse inverse if 1 or -1, otherwise return 0.

Definition at line 4392 of file integer.cpp.

## ◆ Divide() [1/2]

void Integer::Divide | ( | Integer & | r,
|  | Integer & | q,
|  | const Integer & | a,
|  | const Integer & | d
| ) |  |
| static

Extended Division.

Parameters

  r | a reference for the remainder
  q | a reference for the quotient
  a | a reference to the dividend
  d | a reference to the divisor

Divide calculates r and q such that (a == d*q + r) && (0 <= r < abs(d)).

Definition at line 4188 of file integer.cpp.

## ◆ Divide() [2/2]

void Integer::Divide | ( | word & | r,
|  | Integer & | q,
|  | const Integer & | a,
|  | word | d
| ) |  |
| static

Extended Division.

Parameters

  r | a reference for the remainder
  q | a reference for the quotient
  a | a reference to the dividend
  d | a reference to the divisor

Divide calculates r and q such that (a == d*q + r) && (0 <= r < abs(d)). This overload uses a faster division algorithm because the divisor is short.

Definition at line 4248 of file integer.cpp.

## ◆ DivideByPowerOf2()

void Integer::DivideByPowerOf2 | ( | Integer & | r,
|  | Integer & | q,
|  | const Integer & | a,
|  | unsigned int | n
| ) |  |
| static

Extended Division.

Parameters

  r | a reference for the remainder
  q | a reference for the quotient
  a | a reference to the dividend
  n | a reference to the divisor

DivideByPowerOf2 calculates r and q such that (a == d*q + r) && (0 <= r < abs(d)). It returns same result as Divide(r, q, a, Power2(n)), but faster. This overload uses a faster division algorithm because the divisor is a power of 2.

Definition at line 4206 of file integer.cpp.

## ◆ Gcd()

Integer Integer::Gcd | ( | const Integer & | a,
|  | const Integer & | n
| ) |  |
| static

Calculate greatest common divisor.

Parameters

  a | a reference to the first number
  n | a reference to the secind number

Returns
  the greatest common divisor `a` and `n`.

Definition at line 4416 of file integer.cpp.

## ◆ InverseMod() [1/2]

Integer Integer::InverseMod | ( | const Integer & | n | ) | const

Calculate multiplicative inverse.

Parameters

  n | a reference to the modulus

Returns
  an Integer `*this % n`.

InverseMod returns the multiplicative inverse of the Integer `*this` modulo the Integer `n`. If no Integer exists then Integer 0 is returned.

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 4421 of file integer.cpp.

## ◆ InverseMod() [2/2]

word Integer::InverseMod | ( | word | n | ) | const

Calculate multiplicative inverse.

Parameters

  n | the modulus

Returns
  a word `*this % n`.

InverseMod returns the multiplicative inverse of the Integer `*this` modulo the word `n`. If no Integer exists then word 0 is returned.

See also
  a_times_b_mod_c() and a_exp_b_mod_c()

Definition at line 4460 of file integer.cpp.

## Friends And Related Function Documentation

## ◆ operator>>

CRYPTOPP_DLL std::istream& CRYPTOPP_API operator>> | ( | std::istream & | in,
|  | Integer & | a
| ) |  |
| friend

Extraction operator.

Parameters

  in | a reference to a std::istream
  a | a reference to an Integer

Returns
  a reference to a std::istream reference

Definition at line 3661 of file integer.cpp.

## ◆ operator<<

CRYPTOPP_DLL std::ostream& CRYPTOPP_API operator<< | ( | std::ostream & | out,
|  | const Integer & | a
| ) |  |
| friend

Insertion operator.

Parameters

  out | a reference to a std::ostream
  a | a constant reference to an Integer

Returns
  a reference to a std::ostream reference

The output integer responds to std::hex, std::oct, std::hex, std::upper and std::lower. The output includes the suffix h (for hex), . (dot, for dec) and o (for octal). There is currently no way to suppress the suffix.

If you want to print an Integer without the suffix or using an arbitrary base, then use IntToString<Integer>().

See also
  IntToString<Integer>

Definition at line 3696 of file integer.cpp.

## ◆ a_times_b_mod_c

CRYPTOPP_DLL friend Integer CRYPTOPP_API a_times_b_mod_c | ( | const Integer & | x,
|  | const Integer & | y,
|  | const Integer & | m
| ) |  |
| friend

Modular multiplication.

Parameters

  x | a reference to the first term
  y | a reference to the second term
  m | a reference to the modulus

Returns
  an Integer `(a * b) % m`.

Definition at line 4397 of file integer.cpp.

## ◆ a_exp_b_mod_c

CRYPTOPP_DLL friend Integer CRYPTOPP_API a_exp_b_mod_c | ( | const Integer & | x,
|  | const Integer & | e,
|  | const Integer & | m
| ) |  |
| friend

Modular exponentiation.

Parameters

  x | a reference to the base
  e | a reference to the exponent
  m | a reference to the modulus

Returns
  an Integer `(a ^ b) % m`.

Definition at line 4406 of file integer.cpp.

The documentation for this class was generated from the following files:

- integer.h
- integer.cpp