Integer arithmetic v0.1.0
AbsChecked<T>
pub func AbsChecked<T>(value: T, result: *var T) -> bool
The magnitude of value, reporting whether it is representable.
result receives the magnitude the machine produced, which is the true one when this returns false and the
wrapped one when it returns true. Only one input can overflow: the most negative value of a signed type, whose
magnitude is one larger than the maximum. An unsigned type never overflows here, since it is already its own
magnitude. Runs in constant time and allocates nothing. result must be non-null and writable.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
value | T | value whose magnitude is computed |
result | *var T | receives the magnitude or its wrapped representation |
Returns: true when the mathematical magnitude is not representable as T
AbsWrapping<T>
pub func AbsWrapping<T>(value: T) -> T
The magnitude of value, wrapping where it is not representable.
The most negative value of a signed type comes back unchanged, which is what the machine's own negation does. Use
AbsChecked where that matters. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
value | T | value whose magnitude is computed |
Returns: the magnitude of value, wrapping when necessary
Minimum<T>
pub func Minimum<T>(left: T, right: T) -> T
The smaller of two integers.
Total and exact: integers have no NaN, so unlike the floating-point Min there is no case to decide.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | first value to compare |
right | T | second value to compare |
Returns: the smaller value
Maximum<T>
pub func Maximum<T>(left: T, right: T) -> T
The larger of two integers.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | first value to compare |
right | T | second value to compare |
Returns: the larger value
Clamp<T>
pub func Clamp<T>(value: T, low: T, high: T) -> T
value brought into [low, high].
A contradictory pair - low above high - has no correct answer, and this returns low rather than pretending
otherwise. The behavior is stated so it is at least deterministic; callers who cannot rule the case out should check
the bounds themselves.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
value | T | value to constrain |
low | T | inclusive lower bound |
high | T | inclusive upper bound |
Returns: value constrained to [low, high], or low when the bounds contradict each other
GcdChecked<T>
pub func GcdChecked<T>(
left: T,
right: T,
result: *var T
) -> bool
The greatest common divisor of left and right, reporting whether it is representable.
Defined on magnitudes, so signs do not matter and the answer is never negative. Gcd(0, 0) is zero, which is the
conventional answer and the only one that keeps Gcd(x, 0) == |x| true everywhere. The single overflow is a divisor
equal to the magnitude of the most negative value - reachable only as Gcd(min, 0) and Gcd(min, min) - which no
signed type can express. Runs in time proportional to the number of bits and allocates nothing. result must be
non-null and writable.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | first integer |
right | T | second integer |
result | *var T | receives the greatest common divisor or its unrepresentable bit pattern |
Returns: true when the non-negative divisor is not representable as T
LcmChecked<T>
pub func LcmChecked<T>(
left: T,
right: T,
result: *var T
) -> bool
The least common multiple of left and right, reporting whether it is representable.
Zero with anything is zero, which keeps the identity Gcd(a, b) * Lcm(a, b) == |a * b| true. Everything else
overflows readily - two coprime values multiply - so the flag is the usual case rather than the exception, and the
division is done before the multiplication so a representable answer is not lost to an intermediate that is not.
result must be non-null and writable.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | first integer |
right | T | second integer |
result | *var T | receives the least common multiple or a wrapped intermediate |
Returns: true when the least common multiple is not representable as T
PowChecked<T>
pub func PowChecked<T>(
base: T,
exponent: uint,
result: *var T
) -> bool
base raised to exponent, reporting whether the true power is representable.
The exponent is a plain uint because a negative exponent has no integer answer. Anything to the zeroth power is
one, including zero: the empty product is one, and every identity that matters depends on it. result receives the
wrapped power when this returns true, so a caller who wants modular arithmetic can use it directly. Runs in time
proportional to the number of bits in exponent. result must be non-null and writable.
Type parameters
| Name | Description |
|---|---|
T | integer type |
Parameters
| Name | Type | Description |
|---|---|---|
base | T | integer base |
exponent | uint | non-negative exponent |
result | *var T | receives the power, wrapping on overflow |
Returns: true when the mathematical power is not representable as T