Integer arithmetic v0.1.0
MaximumOf<T>
pub func MaximumOf<T>(sample: T) -> T
The largest value the integer type of sample can hold.
sample is read by value and only its type matters; its value is never used. Returns the maximum by copy.
Cannot fail. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
sample | T | any value of the type, read only to deduce it |
Returns: the largest value the type can hold
MinimumOf<T>
pub func MinimumOf<T>(sample: T) -> T
The smallest value the integer type of sample can hold.
sample is read by value and only its type matters. Returns the minimum by copy: zero for an unsigned type, and
the most negative value for a signed one.
Cannot fail. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
sample | T | any value of the type, read only to deduce it |
Returns: the smallest value the type can hold
AddChecked<T>
pub func AddChecked<T>(
left: T,
right: T,
result: *var T
) -> bool
Adds two integers and reports whether the true sum is representable.
left and right are read by value. result receives the sum the machine produced, which is the true sum when
this returns false and the wrapped one when it returns true; it is written in both cases, so a caller that
wants the wrapped answer does not have to compute it again. result must not be null.
Returns true when the sum overflowed. Never traps, so the caller decides what a sum too large to express means.
Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
result | *var T | receives the answer the machine produced, true or wrapped; never null |
Returns: true when the sum does not fit; result then holds the wrapped sum
SubChecked<T>
pub func SubChecked<T>(
left: T,
right: T,
result: *var T
) -> bool
Subtracts one integer from another and reports whether the true difference is representable.
left and right are read by value. result receives the difference the machine produced, true or wrapped, and
is written in both cases. result must not be null.
Returns true when the difference overflowed, which for an unsigned type means it was negative. Never traps.
Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
result | *var T | receives the answer the machine produced, true or wrapped; never null |
Returns: true when the difference does not fit; result then holds the wrapped difference
MulChecked<T>
pub func MulChecked<T>(
left: T,
right: T,
result: *var T
) -> bool
Multiplies two integers and reports whether the true product is representable.
left and right are read by value. result receives the product the machine produced, true or wrapped, and is
written in both cases. result must not be null.
Returns true when the product overflowed. This is the operation an allocation size is computed with: a wrapped
product is an allocation far smaller than the caller asked for, so the report has to be read before the size is
used. Never traps, including for the one signed pair whose quotient cannot be taken.
Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
result | *var T | receives the answer the machine produced, true or wrapped; never null |
Returns: true when the product does not fit; result then holds the wrapped product
AddWrapping<T>
pub func AddWrapping<T>(left: T, right: T) -> T
Adds two integers, wrapping around the type's range.
left and right are read by value; the sum is returned by copy. This is what + already does, named so that
wrapping on purpose reads differently from wrapping by accident.
Cannot fail: every pair of operands has a wrapped sum. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
Returns: the sum, wrapped into the type's range
SubWrapping<T>
pub func SubWrapping<T>(left: T, right: T) -> T
Subtracts one integer from another, wrapping around the type's range.
left and right are read by value; the difference is returned by copy.
Cannot fail. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
Returns: the difference, wrapped into the type's range
MulWrapping<T>
pub func MulWrapping<T>(left: T, right: T) -> T
Multiplies two integers, wrapping around the type's range.
left and right are read by value; the product is returned by copy.
Cannot fail. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
Returns: the product, wrapped into the type's range
AddSaturating<T>
pub func AddSaturating<T>(left: T, right: T) -> T
Adds two integers, clamping to the type's range instead of wrapping.
left and right are read by value; the sum is returned by copy. A sum too large becomes the maximum, and for a
signed type a sum too small becomes the minimum.
Cannot fail: the answer is always the nearest representable value to the true sum. Runs in constant time and
allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
Returns: the sum, clamped to the type's range rather than wrapped
SubSaturating<T>
pub func SubSaturating<T>(left: T, right: T) -> T
Subtracts one integer from another, clamping to the type's range instead of wrapping.
left and right are read by value; the difference is returned by copy. For an unsigned type a negative
difference becomes zero; for a signed one the difference clamps to whichever limit it ran past.
Cannot fail. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
Returns: the difference, clamped to the type's range rather than wrapped
MulSaturating<T>
pub func MulSaturating<T>(left: T, right: T) -> T
Multiplies two integers, clamping to the type's range instead of wrapping.
left and right are read by value; the product is returned by copy. A product too large becomes the maximum,
and for a signed type a product too small becomes the minimum.
Cannot fail. Runs in constant time and allocates nothing.
Type parameters
| Name | Description |
|---|---|
T | the integer or floating-point type, deduced from the arguments |
Parameters
| Name | Type | Description |
|---|---|---|
left | T | the left operand |
right | T | the right operand |
Returns: the product, clamped to the type's range rather than wrapped
CheckedAdd
pub func CheckedAdd(
left: uint64,
right: uint64,
result: *var uint64
) -> bool
Adds two unsigned 64-bit values and reports whether the true sum is representable.
left and right are read by value. result receives the sum the machine produced, which is the true sum when
this returns false and the wrapped one when it returns true; it is written in both cases.
Returns true when the sum overflowed. The operation never traps, so the caller decides what a value too large to
express becomes.
Runs in constant time and allocates nothing. The compiler emits the arithmetic and the check where the call is
written rather than calling out to a helper.
Parameters
| Name | Type | Description |
|---|---|---|
left | uint64 | the left operand |
right | uint64 | the right operand |
result | *var uint64 | receives the answer the machine produced, true or wrapped |
Returns: true when the sum does not fit; result then holds the wrapped sum
CheckedSub
pub func CheckedSub(
left: uint64,
right: uint64,
result: *var uint64
) -> bool
Subtracts one unsigned 64-bit value from another and reports whether the true difference is representable.
left and right are read by value. result receives the difference the machine produced, which is the true one
when this returns false and the wrapped one when it returns true; it is written in both cases.
Returns true when the difference is negative and therefore not representable. The operation never traps.
Runs in constant time and allocates nothing. The compiler emits the arithmetic and the check where the call is
written rather than calling out to a helper.
Parameters
| Name | Type | Description |
|---|---|---|
left | uint64 | the left operand |
right | uint64 | the right operand |
result | *var uint64 | receives the answer the machine produced, true or wrapped |
Returns: true when the difference does not fit; result then holds the wrapped difference
CheckedMul
pub func CheckedMul(
left: uint64,
right: uint64,
result: *var uint64
) -> bool
Multiplies two unsigned 64-bit values and reports whether the true product is representable.
left and right are read by value. result receives the product the machine produced, which is the true product
when this returns false and the wrapped one when it returns true; it is written in both cases.
Returns true when the product overflowed. This is the operation an allocation size is computed with: a wrapped
product is an allocation far smaller than the caller asked for, so the report has to be checked before the size is
used.
Runs in constant time and allocates nothing. The compiler emits the arithmetic and the check where the call is
written rather than calling out to a helper.
Parameters
| Name | Type | Description |
|---|---|---|
left | uint64 | the left operand |
right | uint64 | the right operand |
result | *var uint64 | receives the answer the machine produced, true or wrapped |
Returns: true when the product does not fit; result then holds the wrapped product