arbitrary precision arithmetic More...
Typedefs | |
| typedef typedefCGUL_BEGIN_C struct cgul_big_integer * | cgul_big_integer_t |
Detailed Description
Basic arbitrary precision arithmetic.
Typedef Documentation
§ cgul_big_integer_t
| typedef typedefCGUL_BEGIN_C struct cgul_big_integer* cgul_big_integer_t |
Opaque pointer to a cgul_big_integer instance.
Function Documentation
§ cgul_big_integer__new()
| CGUL_END_C CGUL_BEGIN_C CGUL_EXPORT cgul_big_integer_t cgul_big_integer__new | ( | cgul_exception_t * | cex | ) |
Create a new cgul_big_integer instance initialized to positive 0. The caller is responsible for calling cgul_big_integer__delete() on the value returned. If memory allocation fails, NULL is returned, and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception
- Returns
- new
cgul_big_integerinstance
§ cgul_big_integer__new_from_big_integer()
| CGUL_EXPORT cgul_big_integer_t cgul_big_integer__new_from_big_integer | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | value | ||
| ) |
Create a new cgul_big_integer instance initialized to value. The caller is responsible for calling cgul_big_integer__delete() on the value returned. If memory allocation fails, NULL is returned and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [in] value initial value
- Returns
- new
cgul_big_integerinstance
§ cgul_big_integer__new_from_long()
| CGUL_EXPORT cgul_big_integer_t cgul_big_integer__new_from_long | ( | cgul_exception_t * | cex, |
| long | value | ||
| ) |
Create a new cgul_big_integer instance initialized to value. The caller is responsible for calling cgul_big_integer__delete() on the value returned. If memory allocation fails, NULL is returned and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [in] value initial value
- Returns
- new
cgul_big_integerinstance
§ cgul_big_integer__new_from_unsigned_long()
| CGUL_EXPORT cgul_big_integer_t cgul_big_integer__new_from_unsigned_long | ( | cgul_exception_t * | cex, |
| unsigned long | value | ||
| ) |
Create a new cgul_big_integer instance initialized to value. The caller is responsible for calling cgul_big_integer__delete() on the value returned. If memory allocation fails, NULL is returned and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [in] value initial value
- Returns
- new
cgul_big_integerinstance
§ cgul_big_integer__new_from_size_type()
| CGUL_EXPORT cgul_big_integer_t cgul_big_integer__new_from_size_type | ( | cgul_exception_t * | cex, |
| size_t | value | ||
| ) |
Create a new cgul_big_integer instance initialized to value. The caller is responsible for calling cgul_big_integer__delete() on the value returned. If memory allocation fails, NULL is returned and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [in] value initial value
- Returns
- new
cgul_big_integerinstance
§ cgul_big_integer__new_from_string()
| CGUL_EXPORT cgul_big_integer_t cgul_big_integer__new_from_string | ( | cgul_exception_t * | cex, |
| const char * | s | ||
| ) |
Create a new cgul_big_integer instance initialized from the string s. If s starts with "0x" or "0X", it will be treated as hex. If it starts with "0b" or "0B", it will be treated as binary. If it starts with "0" followed by any valid octal digit, it will be treated as octal. All other strings will be treated as decimal. The caller is responsible for calling cgul_big_integer__delete() on the value returned. If an error occurs interpreting the string "s", then NULL is returned. If memory allocation fails, NULL is returned and an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [in] s initial value
- Returns
- new
cgul_big_integerinstance
§ cgul_big_integer__delete()
| CGUL_EXPORT void cgul_big_integer__delete | ( | cgul_big_integer_t | big_integer | ) |
Delete the cgul_big_integer object in big_integer. The client must not use big_integer after calling this method.
- Parameters
-
[in] big_integer cgul_big_integerinstance
§ cgul_big_integer__is_positive()
| CGUL_EXPORT int cgul_big_integer__is_positive | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return 1 if big_integer is positive. Return 0 if it is not.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- whether
big_integeris positive
§ cgul_big_integer__is_negative()
| CGUL_EXPORT int cgul_big_integer__is_negative | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return 1 if big_integer is negative. Return 0 if it is not.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- whether
big_integeris negative
§ cgul_big_integer__is_zero()
| CGUL_EXPORT int cgul_big_integer__is_zero | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return 1 if big_integer is zero. Return 0 if it is not.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- whether
big_integeris zero
§ cgul_big_integer__set_to_zero()
| CGUL_EXPORT void cgul_big_integer__set_to_zero | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Set the value of big_integer to zero.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
§ cgul_big_integer__is_one()
| CGUL_EXPORT int cgul_big_integer__is_one | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return 1 if big_integer is one. Return 0 if it is not.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- whether
big_integeris one
§ cgul_big_integer__set_to_one()
| CGUL_EXPORT void cgul_big_integer__set_to_one | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Set the value of big_integer to one.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
§ cgul_big_integer__is_even()
| CGUL_EXPORT int cgul_big_integer__is_even | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return whether big_integer is even.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- whether
big_integeris even
§ cgul_big_integer__is_odd()
| CGUL_EXPORT int cgul_big_integer__is_odd | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return whether big_integer is odd.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- whether
big_integeris odd
§ cgul_big_integer__assign()
| CGUL_EXPORT void cgul_big_integer__assign | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs | ||
| ) |
Assign rhs to lhs. It is safe for rhs and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
§ cgul_big_integer__assign_from_long()
| CGUL_EXPORT void cgul_big_integer__assign_from_long | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| long | rhs | ||
| ) |
Assign long in rhs to lhs.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
§ cgul_big_integer__assign_from_unsigned_long()
| CGUL_EXPORT void cgul_big_integer__assign_from_unsigned_long | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| unsigned long | rhs | ||
| ) |
Assign unsigned long in rhs to lhs.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
§ cgul_big_integer__assign_from_size_type()
| CGUL_EXPORT void cgul_big_integer__assign_from_size_type | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| size_t | rhs | ||
| ) |
Assign size type in rhs to lhs.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
§ cgul_big_integer__assign_from_string()
| CGUL_EXPORT void cgul_big_integer__assign_from_string | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| const char * | rhs | ||
| ) |
Assign the string in rhs to lhs. If an error occurs, an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
- Returns
- whether
rhsparsed
§ cgul_big_integer__negate()
| CGUL_EXPORT void cgul_big_integer__negate | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs | ||
| ) |
Assign the negative of rhs to lhs. It is safe and efficient for rhs and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
§ cgul_big_integer__abs()
| CGUL_EXPORT void cgul_big_integer__abs | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs | ||
| ) |
Assign the absolute value of rhs to lhs. It is safe and efficient for rhs and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side
§ cgul_big_integer__invert()
| CGUL_EXPORT void cgul_big_integer__invert | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs, | ||
| size_t | scale | ||
| ) |
This method uses Newton's Method to calculate the scaled multiplicative inverse of rhs and saves it in lhs. It is permissible for lhs and rhs to point to the same object.
The big_integer class does not handle fractional parts of numbers; instead, scale is used to shift scale bits from the fractional side of the radix point to the whole-number side. The remaining bits in the fractional part are truncated:
1 scale
lhs = --- * 2
rhs
Typically, this method works in conjunction with cgul_big_integer__divide_newton() where big_integer corresponds to the divisor. In this case scale should be at least as large as the following:
scale = cgul_big_integer__get_inversion_scale(cex, dividend, divisor);
If the same divisor will be used repeatedly, it is usually better to calculate the inverse once, and then perform division by repeatedly multiplying by the inverse using cgul_big_integer__divide_newton(). <p.
For example, many pseudo-random number generators (PRNGs) repeatedly divide by the same modulus. These PRNGs will usually see a significant increase in performance if they multiply by the inverse rather than calculating the division from scratch each time.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side [in] scale scale
§ cgul_big_integer__get_inversion_scale()
| CGUL_EXPORT size_t cgul_big_integer__get_inversion_scale | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | dividend, | ||
| cgul_big_integer_t | divisor | ||
| ) |
This method calculates the scale (as a power of 2) needed for inverting divisor using cgul_big_integer__invert() such that it can accurately divide dividend when both are passed into cgul_big_integer__divide_newton().
- Parameters
-
[in] cex c-style exception [in] dividend dividend [in] divisor divisor
- Returns
- scale
§ cgul_big_integer__add()
| CGUL_EXPORT void cgul_big_integer__add | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
Add rhs1 to rhs2 and store the result in lhs. It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__subtract()
| CGUL_EXPORT void cgul_big_integer__subtract | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
Subtract rhs2 from rhs1 and store the result in lhs. It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__multiply()
| CGUL_EXPORT void cgul_big_integer__multiply | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
Multiply rhs1 with rhs2 and store the result in lhs. This method picks a suitable multiplication algorithm given the size of the factors rhs1 and rhs2. If in doubt, this is the method to use for multiplication.
It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object. This method throws an exception if memory cannot be allocated.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__multiply_long()
| CGUL_EXPORT void cgul_big_integer__multiply_long | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method implements multiplication using the "long
multiplication" algorithm. It multiplies rhs1 with rhs2 and stores the result in lhs. If in doubt, use cgul_big_integer__multiply() instead.
It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object. This method throws an exception if memory cannot be allocated.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__multiply_karatsuba()
| CGUL_EXPORT void cgul_big_integer__multiply_karatsuba | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method implements multiplication using the Karatsuba algorithm. It multiplies rhs1 with rhs2 and stores the result in lhs. If in doubt, use cgul_big_integer__multiply() instead.
It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object. This method throws an exception if memory cannot be allocated.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__divide()
| CGUL_EXPORT void cgul_big_integer__divide | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | quotient, | ||
| cgul_big_integer_t | remainder, | ||
| cgul_big_integer_t | dividend, | ||
| cgul_big_integer_t | divisor | ||
| ) |
Divide dividend by divisor and store the result in quotient and remainder. This method picks a suitable division algorithm given the size of dividend and divisor. If in doubt, this is the method to use for division.
It is safe for dividend or divisor and quotient or remainder to point to the same underlying cgul_big_integer object. This method throws an exception if division by zero is attempted or if memory cannot be allocated.
- Parameters
-
[in,out] cex c-style exception [out] quotient quotient [out] remainder remainder [in] dividend dividend [in] divisor divisor
§ cgul_big_integer__divide_long()
| CGUL_EXPORT void cgul_big_integer__divide_long | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | quotient, | ||
| cgul_big_integer_t | remainder, | ||
| cgul_big_integer_t | dividend, | ||
| cgul_big_integer_t | divisor | ||
| ) |
This method implements division using the "long division" algorithm. It divides dividend by divisor and stores the result in quotient and remainder. If in doubt, use cgul_big_integer__divide() instead.
It is safe for dividend or divisor and quotient or remainder to point to the same underlying cgul_big_integer object. This method throws an exception if division by zero is attempted or if memory cannot be allocated.
- Parameters
-
[in,out] cex c-style exception [out] quotient quotient [out] remainder remainder [in] dividend dividend [in] divisor divisor
§ cgul_big_integer__divide_newton()
| CGUL_EXPORT void cgul_big_integer__divide_newton | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | quotient, | ||
| cgul_big_integer_t | remainder, | ||
| cgul_big_integer_t | dividend, | ||
| cgul_big_integer_t | divisor, | ||
| cgul_big_integer_t | reciprocal, | ||
| size_t | scale | ||
| ) |
This method implements division by multiplying dividend by the pre-calculated, scaled reciprocal of the divisor. If in doubt, use cgul_big_integer__divide() instead.
The divisor must be passed in in addition to reciprocal because the reciprocal is an approximation with some round-off error. The divisor is used to make minor adjustments to the result of the multiplication so that quotient and remainder are exact.
This method is especially useful when repeated divisions need to be performed using the same divisor because the reciprocal of the divisor needs to be calculated just once. Each division can then be performed using multiplication which is faster.
It is safe for dividend or divisor and quotient or remainder to point to the same underlying cgul_big_integer object. This method throws an exception if division by zero is attempted or if memory cannot be allocated.
The basic set up follows:
scale = cgul_big_integer__get_inversion_scale(cex, dividend, divisor);
cgul_big_integer__invert(cex, reciprocal, divisor, scale);
cgul_big_integer__divide_newton(cex,
quotient,
remainder,
dividend,
divisor,
reciprocal,
scale);
Often, the size of the dividend will be reduced after each iteration. In this case it is usually possible to almost halve the total run time by keeping the size of the reciprocal in sync with the size of the divisor as shown in the following code:
reciprocal_size = cgul_big_integer__get_size(cex, reciprocal);
dividend_size = cgul_big_integer__get_size(cex, dividend);
if (reciprocal_size > dividend_size + 17) {
cgul_big_integer__shift_right(cex,
reciprocal,
reciprocal,
64);
scale -= 64;
}
This method derives its name from the fact that Newton's Method is used to calculate the inverse of the divisor.
- Parameters
-
[in,out] cex c-style exception [out] quotient quotient [out] remainder remainder [in] dividend dividend [in] divisor divisor [in] reciprocal reciprocal [in] scale scale applied to reciprocal
§ cgul_big_integer__power()
| CGUL_EXPORT void cgul_big_integer__power | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | base, | ||
| cgul_big_integer_t | exponent | ||
| ) |
This method calculates base raised to the power of exponent and saves the result in lhs. If exponent is negative, an exception is thrown. If the program runs out of memory, an exception is thrown.
This method is not as effecient as cgul_big_integer__power_modulo() when the client is only interested in the modulo and not the power.
- Note
- For this implementation, pow(0,0) = 1. This is in agreement with some, but others leave it undefined.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] base base [in] exponent exponent
- See also
- cgul_big_integer__power_modulo()
§ cgul_big_integer__power_modulo()
| CGUL_EXPORT void cgul_big_integer__power_modulo | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | base, | ||
| cgul_big_integer_t | exponent, | ||
| cgul_big_integer_t | modulus | ||
| ) |
This method calculates the modulo of base to the power of exponent using modulus as the modulus. If exponent is negative, an exception is thrown. If the program runs out of memory, an exception is thrown.
This method is much more effecient than cgul_big_integer__power() when the client is only interested in the modulo and not the power because the modulo operation is used at each stage of the calculation to keep the size of the numbers within reason.
- Note
- For this implementation, pow(0,0) = 1. This is in agreement with some, but others leave it undefined.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] base base [in] exponent exponent [in] modulus modulus
- See also
- cgul_big_integer__power()
§ cgul_big_integer__is_probably_prime()
| CGUL_EXPORT int cgul_big_integer__is_probably_prime | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| unsigned int | count | ||
| ) |
This method uses the Miller-Rabin Primality Test to determine whether big_integer is probably prime. The error per iteration for Miller-Rabin is bound by 1/4. This method performs count iterations. The following table shows the theoretical upper bound for the error associated with different values of count:
count | error
------------------------
10 | 9.54e-7
25 | 8.88e-16
50 | 7.89e-31
100 | 6.22e-61
500 | 9.33e-302
1000 | 8.71e-603
If an exception is not thrown, this method returns 1 if big_integer is probably prime and 0 if it is definitely composite.
This method throws an exception if big_integer is negative. It also throws an exception if the program runs out of memory. If an exception is thrown, 0 is returned.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] count number of times test is independently executed
- Returns
- whether
big_integeris probably prime
§ cgul_big_integer__shift_left()
| CGUL_EXPORT void cgul_big_integer__shift_left | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs, | ||
| size_t | bit_count | ||
| ) |
Shift rhs left by bit_count and put the result in lhs. It is safe for rhs and lhs to point to the same underlying cgul_big_integer object.
Note that this method is a base-2 shift that shifts individual bits. Contrast this method with cgul_bcd__shift_left() which shifts individual base-10 digits instead.
This method can be used as a fast way to multiply by a power of 2.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side [in] bit_count how far to shift rhs
§ cgul_big_integer__shift_right()
| CGUL_EXPORT void cgul_big_integer__shift_right | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs, | ||
| size_t | bit_count | ||
| ) |
Shift rhs right by bit_count and put the result in lhs. It is safe for rhs and lhs to point to the same underlying cgul_big_integer object.
Note that this method is a base-2 shift that shifts individual bits. Contrast this method with cgul_bcd__shift_right() which shifts individual base-10 digits instead.
This method can be used as a fast way to divide by a power of 2.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs right-hand side [in] bit_count how far to shift rhs
§ cgul_big_integer__and()
| CGUL_EXPORT void cgul_big_integer__and | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method effectively assigns the value of rhs1 to lhs and then performs a bit-wise AND of lhs and rhs2. It is important to understand that this means that lhs will have the same sign as rhs1 when this method returns.
It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__or()
| CGUL_EXPORT void cgul_big_integer__or | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method effectively assigns the value of rhs1 to lhs and then performs a bit-wise OR of lhs and rhs2. It is important to understand that this means that lhs will have the same sign as rhs1 when this method returns.
It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__xor()
| CGUL_EXPORT void cgul_big_integer__xor | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method effectively assigns the value of rhs1 to lhs and then performs a bit-wise XOR of lhs and rhs2. It is important to understand that this means that lhs will have the same sign as rhs1 when this method returns.
It is safe for rhs1 or rhs2 and lhs to point to the same underlying cgul_big_integer object.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__compare()
| CGUL_EXPORT int cgul_big_integer__compare | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs | ||
| ) |
Return less than zero if lhs is less than rhs, return zero if lhs equals rhs, and return greater than zero if lhs is greater than rhs.
- Parameters
-
[in] cex c-style exception [in] lhs left-hand side [in] rhs right-hand side
- Returns
- comparison of
lhsandrhs
§ cgul_big_integer__compare_magnitudes()
| CGUL_EXPORT int cgul_big_integer__compare_magnitudes | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs | ||
| ) |
Compare just the magnitudes of lhs and rhs. This function returns less than zero if lhs is less than rhs, zero if lhs equals rhs, and greater than zero if the magnitude of lhs is greater than the magnitude of rhs.
- Parameters
-
[in] cex c-style exception [in] lhs left-hand side [in] rhs right-hand side
- Returns
- comparison of the magnitudes of
lhsandrhs
§ cgul_big_integer__gcd()
| CGUL_EXPORT void cgul_big_integer__gcd | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method finds the greatest common divisor (GCD) of rhs1 and rhs2 and saves the result in lhs. If an error occurs, an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__lcm()
| CGUL_EXPORT void cgul_big_integer__lcm | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | lhs, | ||
| cgul_big_integer_t | rhs1, | ||
| cgul_big_integer_t | rhs2 | ||
| ) |
This method finds the least common multiple (LCM) of rhs1 and rhs2 and saves the result in lhs. The value returned is often used as the lowest common denominator (LCD). If an error occurs, an exception is thrown.
- Parameters
-
[in,out] cex c-style exception [out] lhs left-hand side [in] rhs1 first right-hand side [in] rhs2 second right-hand side
§ cgul_big_integer__swap()
| CGUL_EXPORT void cgul_big_integer__swap | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer_1, | ||
| cgul_big_integer_t | big_integer_2 | ||
| ) |
Swap the internal data quickly without copying.
- Parameters
-
[in] cex c-style exception [in] big_integer_1 first cgul_big_integerinstance[in] big_integer_2 second cgul_big_integerinstance
§ cgul_big_integer__get_array()
| CGUL_EXPORT const unsigned char* cgul_big_integer__get_array | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Get the internal array of bytes that comprise the value. The main purpose of this method is to allow the client to access individual bytes after a PRNG with a good bit distribution (like Blum-Blum-Shub) returns a pseudo-random number. The client can use cgul_big_integer__get_size() to determine the number of bytes in the array.
The client must not free the pointer that is returned because it is still owned by v. The client also must not alter the values in the array. The pointer returned is only valid until the next math operation.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- internal array
§ cgul_big_integer__get_size()
| CGUL_EXPORT size_t cgul_big_integer__get_size | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return the number of bytes in the internal array.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- size of the internal array
§ cgul_big_integer__as_long()
| CGUL_EXPORT int cgul_big_integer__as_long | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| long int * | value | ||
| ) |
Convert the value of big_integer to a long. This function returns 1 if the conversion can be accomplished without losing any significant bits; otherwise, it returns 0.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance[out] value converted value
- Returns
- whether a conversion occurred
§ cgul_big_integer__as_unsigned_long()
| CGUL_EXPORT int cgul_big_integer__as_unsigned_long | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| unsigned long int * | value | ||
| ) |
Convert the value of big_integer to an unsigned long. This function returns 1 if the conversion can be accomplished without losing any significant bits; otherwise, it returns 0.
- Parameters
-
[in] cex c-style exception [in] big_integer cgul_big_integerinstance[out] value converted value
- Returns
- whether a conversion occurred
§ cgul_big_integer__as_bcd()
| CGUL_EXPORT void cgul_big_integer__as_bcd | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| cgul_bcd_t | bcd | ||
| ) |
This method converts big_integer to a cgul_bcd object and saves the conversion to bcd which the caller has already instantiated. If an error occurs, an exception is thrown, and bcd is not altered.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[out] bcd cgul_bcdinstance
§ cgul_big_integer__as_binary()
| CGUL_EXPORT char* cgul_big_integer__as_binary | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return a char* object that holds the string representation of big_integer as a radix-2 number. The caller is responsible for calling free() on the pointer returned.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- string representation of
big_integeras binary
§ cgul_big_integer__append_as_binary()
| CGUL_EXPORT void cgul_big_integer__append_as_binary | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| cgul_string_t | s | ||
| ) |
Append the binary representation of big_integer to s.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] s where to append the string representation
§ cgul_big_integer__as_octal()
| CGUL_EXPORT char* cgul_big_integer__as_octal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return a char* that holds the string representation of big_integer as a radix-8 number. The caller is responsible for calling free() on the pointer returned.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- string representation of
big_integeras octal
§ cgul_big_integer__append_as_octal()
| CGUL_EXPORT void cgul_big_integer__append_as_octal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| cgul_string_t | s | ||
| ) |
Append the octal representation of big_integer to s.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] s where to append the string representation
§ cgul_big_integer__as_decimal()
| CGUL_EXPORT char* cgul_big_integer__as_decimal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return a char* object that holds the string representation of big_integer as a radix-10 number. The caller is responsible for calling free() on the pointer returned.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- string representation of
big_integeras decimal
§ cgul_big_integer__append_as_decimal()
| CGUL_EXPORT void cgul_big_integer__append_as_decimal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| cgul_string_t | s | ||
| ) |
Append the decimal representation of big_integer to s.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] s where to append the string representation
§ cgul_big_integer__as_hexadecimal()
| CGUL_EXPORT char* cgul_big_integer__as_hexadecimal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer | ||
| ) |
Return a char* object that holds the string representation of big_integer as a radix-16 number. The caller is responsible for calling free() on the pointer returned.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance
- Returns
- string representation of
big_integeras hexadecimal
§ cgul_big_integer__append_as_hexadecimal()
| CGUL_EXPORT void cgul_big_integer__append_as_hexadecimal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| cgul_string_t | s | ||
| ) |
Append the hexadecimal representation of big_integer to s.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] s where to append the string representation
§ cgul_big_integer__print_as_binary()
| CGUL_EXPORT void cgul_big_integer__print_as_binary | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| FILE * | f | ||
| ) |
Print the string representation of big_integer as a radix-2 number on f.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] f output file
§ cgul_big_integer__print_as_octal()
| CGUL_EXPORT void cgul_big_integer__print_as_octal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| FILE * | f | ||
| ) |
Print the string representation of big_integer as a radix-8 number on f.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] f output file
§ cgul_big_integer__print_as_decimal()
| CGUL_EXPORT void cgul_big_integer__print_as_decimal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| FILE * | f | ||
| ) |
Print the string representation of big_integer as a radix-10 number on f.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] f output file
§ cgul_big_integer__print_as_hexadecimal()
| CGUL_EXPORT void cgul_big_integer__print_as_hexadecimal | ( | cgul_exception_t * | cex, |
| cgul_big_integer_t | big_integer, | ||
| FILE * | f | ||
| ) |
Print the string representation of big_integer as a radix-16 number on f.
- Parameters
-
[in,out] cex c-style exception [in] big_integer cgul_big_integerinstance[in] f output file
