FixedNat structv0.1.0

pub struct FixedNat {
    // private fields
}

Copy, and 520 bytes wide, so it is passed by reference rather than by value everywhere in this package. The limbs are least significant first and length counts the ones in use, so zero is length == 0 and there are never leading zero limbs above it — every operation restores that before it returns.

Constructors

FixedNat

pub func FixedNat() -> FixedNat

Zero. Cannot fail; runs in constant time and allocates nothing.

Returns: the value zero

Source

Associated functions

FromUint64

pub func FromUint64(initial: uint64) -> FixedNat

The value initial. Cannot fail: one limb always fits. Runs in constant time and allocates nothing.

Returns: a FixedNat equal to initial

Source

Methods

IsZero

pub func IsZero(self: &FixedNat) -> bool

Whether this is zero. Borrows the value. Cannot fail; runs in constant time and allocates nothing.

Returns: true when no limb is in use

Source

BitLength

pub func BitLength(self: &FixedNat) -> uint

How many bits the value occupies, counting from its highest set bit. Zero has no bits. Borrows the value; runs in time proportional to one limb and allocates nothing.

Returns: the position one past the highest set bit

Source

Compare

pub func Compare(self: &FixedNat, other: &FixedNat) -> int32

How this value orders against other. Borrows both. Cannot fail; runs in time proportional to the length and allocates nothing.

Returns: -1 when this is smaller, 0 when they are equal, and 1 when this is larger

Source

Assign

pub func Assign(self: &var FixedNat, other: &FixedNat)

Replaces this value with other. Cannot fail: both have the same capacity. Runs in time proportional to the capacity and allocates nothing.

Source

MultiplyAddSmall

pub func MultiplyAddSmall(
    self: &var FixedNat,
    factor: uint64,
    addend: uint64
) -> bool

Multiplies by factor and adds addend, in one pass over the limbs. The pair is one operation because that is how a digit is absorbed while reading a number, and doing it in two passes would double the work for no gain. Answers false when the product needs more limbs than the capacity holds, leaving the value exactly as it was — a caller that sees this has passed the bound Docs/NarrowFloat.md proves is not reached.

Returns: true when the result fits

Source

MultiplySmall

pub func MultiplySmall(
    self: &var FixedNat,
    factor: uint64
) -> bool

Multiplies by factor. Answers false when the product does not fit, leaving the value as it was.

Returns: true when the result fits

Source

AddSmall

pub func AddSmall(
    self: &var FixedNat,
    addend: uint64
) -> bool

Adds addend. Answers false when the sum does not fit, leaving the value as it was.

Returns: true when the result fits

Source

ShiftLeft

pub func ShiftLeft(self: &var FixedNat, bits: uint) -> bool

Shifts left by bits, which multiplies by two to that power. Answers false when the result needs more limbs than the capacity holds, leaving the value as it was: the width a shift needs is known before any of it happens.

Returns: true when the result fits

Source

Add

pub func Add(self: &var FixedNat, other: &FixedNat) -> bool

Adds other. Answers false when the sum needs more limbs than the capacity holds, leaving the value as it was.

Returns: true when the result fits

Source

Subtract

pub func Subtract(self: &var FixedNat, other: &FixedNat)

Subtracts other, which must not be larger than this value. The caller establishes other <= self first, by Compare or by construction. Subtracting a larger value has no answer in an unsigned type, and this borrows past the top rather than reporting it.

Source

MultiplyPowerOfTen

pub func MultiplyPowerOfTen(
    self: &var FixedNat,
    power: uint
) -> bool

Multiplies by ten to the power. Done as one pass per limb-sized chunk of the power rather than one per digit: ten to the nineteenth is the largest power of ten a uint64 holds, so a power of three hundred and twenty-four costs seventeen passes instead of three hundred and twenty-four. Answers false when the result does not fit. A power applied in chunks stops at the chunk that does not fit, so the value is left part-scaled rather than untouched — the one place in this file where that is so, and it is reached only past a bound that is proved not to be.

Returns: true when the result fits

Source

SetPowerOfTwo

pub func SetPowerOfTwo(
    self: &var FixedNat,
    bits: uint
) -> bool

Replaces this value with two to the bits. Answers false when bits is past the capacity, leaving the value as it was.

Returns: true when the result fits

Source

Low64

pub func Low64(self: &FixedNat) -> uint64

The value's low sixty-four bits. Useful where a caller has already established the value is small, such as a quotient digit. Borrows the value; cannot fail, runs in constant time and allocates nothing.

Returns: the least significant limb, or zero

Source

Related

FixedNatLimbs

pub const FixedNatLimbs: uint = 64;

How many sixty-four-bit limbs a FixedNat holds. Sixty-four, which is 4,096 bits: the 3,681 the narrow conversion reaches at worst, and 415 bits of headroom over it. See Docs/NarrowFloat.md for where the 3,681 comes from.

Source

FixedNatBits

pub const FixedNatBits: uint = 4096;

How many bits a FixedNat holds in total.

Source