Crate abstract_integers

Expand description

This crate defines specification-friendly natural integers with an upper bound. Operations on these integers can be defined as modular (modulo the upper bound) or regular (with a panic on underflow or overflow).

As each integer gets its own Rust type, the compiler detects and prevent any mixing between all the diffent integers you would have defined.

§Defining a new integer type

Here is the macro used to defined the SizeNatExample type of this crate:

define_abstract_integer_checked!(SizeNatExample, 64);

SizeNat is the name of the newly-created type. 64 is the number of bits of the machine representation of the type. From the number of bits is derived an upper bound for the integer for which all operations are checked for overflow.

The resulting integer type is copyable, and supports addition, substraction, multiplication, integer division, remainder, comparison and equality. The from_literal method allows you to convert integer literals into your new type.

§Refining an integer type for modular arithmetic

On top of a previously defined abstract integer, you can define another type that lets you implement modular arithmetic. For instance, this crate defines the arithmetic field over the 9th Mersenne prime with:

define_refined_modular_integer!(
   SizeNatFieldExample,
   SizeNatExample,
   SizeNatExample::pow2(61) - SizeNatExample::from_literal(1)
);

The first argument of this new macro is the name of the newly defined refined type. The second argument is the name of the base abstract integer that will act as the representation. The third example is the modulo for all operations, defined as a value of the base type.

§Example

use abstract_integers::*;

abstract_public_nat_mod!(SizeNatFieldExample, SizeNatExample, 64, "1fffffffffffffff");

let x1 = SizeNatExample::from_literal(687165654266415);
let x2 = SizeNatExample::from_literal(4298832000156);
let x3 = x1 + x2;
assert_eq!(SizeNatExample::from_literal(691464486266571), x3);
let x4 = SizeNatExample::from_literal(8151084996540);
let x5 = x3 - x4;
assert_eq!(SizeNatExample::from_literal(683313401270031), x5.into());
let x6 = x5 / SizeNatExample::from_literal(1541654268);
assert_eq!(SizeNatExample::from_literal(443233), x6.into());
let x7 : SizeNatFieldExample = SizeNatFieldExample::from_literal(2305843009213693951) + x6.into();
assert_eq!(x7, x6.into());

Modules§

abstract_int
nat_mod
traits

Macros§

abstract_int
abstract_nat_mod
abstract_public
abstract_public_modular_integer
abstract_public_nat_mod
abstract_secret
abstract_secret_modular_integer
abstract_signed
abstract_signed_public_integer
abstract_signed_secret_integer
abstract_unsigned
abstract_unsigned_public_integer
abstract_unsigned_secret_integer
define_abstract_integer_checked: Defines a bounded natural integer with regular arithmetic operations, checked for overflow and underflow.
define_refined_modular_integer: Defines a bounded natural integer with modular arithmetic operations
modular_integer

Structs§

BigInt: A big signed integer type.
BigUint: A big unsigned integer type.
ParseIntError: An error which can be returned when parsing an integer.
Range: A (half-open) range bounded inclusively below and exclusively above (start..end).
RangeFrom: A range only bounded inclusively below (start..).
RangeFull: An unbounded range (..).
RangeInclusive: A range bounded inclusively below and above (start..=end).
RangeTo: A range only bounded exclusively above (..end).
RangeToInclusive: A range only bounded inclusively above (..=end).
YeetExperimental: Implement FromResidual<Yeet<T>> on your type to enable do yeet expr syntax in functions returning your type.

Enums§

Bound: An endpoint of a range of keys.
ControlFlow: Used to tell an operation whether it should exit early or go on as usual.
Ordering: An Ordering is the result of a comparison between two values.
Sign: A Sign is a BigInt’s composing element.
CoroutineStateExperimental: The result of a coroutine resumption.
OneSidedRangeBoundExperimental: An internal helper for split_off functions indicating which end a OneSidedRange is bounded on.

Traits§

Add: The addition operator +.
AddAssign: The addition assignment operator +=.
AsyncFn: An async-aware version of the Fn trait.
AsyncFnMut: An async-aware version of the FnMut trait.
AsyncFnOnce: An async-aware version of the FnOnce trait.
BitAnd: The bitwise AND operator &.
BitAndAssign: The bitwise AND assignment operator &=.
BitOr: The bitwise OR operator |.
BitOrAssign: The bitwise OR assignment operator |=.
BitXor: The bitwise XOR operator ^.
BitXorAssign: The bitwise XOR assignment operator ^=.
CheckedSub: Performs subtraction that returns None instead of wrapping around on underflow.
ConstOne: Defines an associated constant representing the multiplicative identity element for Self.
ConstZero: Defines an associated constant representing the additive identity element for Self.
Deref: Used for immutable dereferencing operations, like *v.
DerefMut: Used for mutable dereferencing operations, like in *v = 1;.
Div: The division operator /.
DivAssign: The division assignment operator /=.
Drop: Custom code within the destructor.
Fn: The version of the call operator that takes an immutable receiver.
FnMut: The version of the call operator that takes a mutable receiver.
FnOnce: The version of the call operator that takes a by-value receiver.
Index: Used for indexing operations (container[index]) in immutable contexts.
IndexMut: Used for indexing operations (container[index]) in mutable contexts.
Mul: The multiplication operator *.
MulAssign: The multiplication assignment operator *=.
Neg: The unary negation operator -.
Not: The unary logical negation operator !.
One: Defines a multiplicative identity element for Self.
RangeBounds: RangeBounds is implemented by Rust’s built-in range types, produced by range syntax like .., a.., ..b, ..=c, d..e, or f..=g.
Rem: The remainder operator %.
RemAssign: The remainder assignment operator %=.
Shl: The left shift operator <<. Note that because this trait is implemented for all integer types with multiple right-hand-side types, Rust’s type checker has special handling for _ << _, setting the result type for integer operations to the type of the left-hand-side operand. This means that though a << b and a.shl(b) are one and the same from an evaluation standpoint, they are different when it comes to type inference.
ShlAssign: The left shift assignment operator <<=.
Shr: The right shift operator >>. Note that because this trait is implemented for all integer types with multiple right-hand-side types, Rust’s type checker has special handling for _ >> _, setting the result type for integer operations to the type of the left-hand-side operand. This means that though a >> b and a.shr(b) are one and the same from an evaluation standpoint, they are different when it comes to type inference.
ShrAssign: The right shift assignment operator >>=.
Sub: The subtraction operator -.
SubAssign: The subtraction assignment operator -=.
Zero: Defines an additive identity element for Self.
CoerceUnsizedExperimental: Trait that indicates that this is a pointer or a wrapper for one, where unsizing can be performed on the pointee.
CoroutineExperimental: The trait implemented by builtin coroutine types.
DerefPureExperimental: Perma-unstable marker trait. Indicates that the type has a well-behaved Deref (and, if applicable, DerefMut) implementation. This is relied on for soundness of deref patterns.
DispatchFromDynExperimental: DispatchFromDyn is used in the implementation of dyn-compatibility checks (specifically allowing arbitrary self types), to guarantee that a method’s receiver type can be dispatched on.
FromResidualExperimental: Used to specify which residuals can be converted into which crate::ops::Try types.
IntoBoundsExperimental: Used to convert a range into start and end bounds, consuming the range by value.
OneSidedRangeExperimental: OneSidedRange is implemented for built-in range types that are unbounded on one side. For example, a.., ..b and ..=c implement OneSidedRange, but .., d..e, and f..=g do not.
ReceiverExperimental: Indicates that a struct can be used as a method receiver. That is, a type can use this type as a type of self, like this:
ResidualExperimental: Allows retrieving the canonical type implementing Try that has this type as its residual and allows it to hold an O as its output.
TryExperimental: The ? operator and try {} blocks.

Functions§

one: Returns the multiplicative identity, 1.
zero: Returns the additive identity, 0.

Crate abstract_integersCopy item path