# Module hacspec_lib::prelude

source · [−]## Expand description

This module conveniently exports common subroutines necessary for hacspecs

## Re-exports

`pub use crate::array::*;`

`pub use crate::buf::*;`

`pub use crate::math_integers::*;`

`pub use crate::seq::*;`

`pub use crate::*;`

`pub use num;`

## Modules

Utilities for formatting and printing strings.

A contiguous growable array type with heap-allocated contents, written
`Vec<T>`

.

## Macros

Derive macro generating an impl of the trait `Debug`

.

Derive macro generating an impl of the trait `PartialEq`

.

Defines a bounded natural integer with regular arithmetic operations, checked for overflow and underflow.

Defines a bounded natural integer with modular arithmetic operations

Creates a `String`

using interpolation of runtime expressions.

## Structs

A big signed integer type.

A big unsigned integer type.

Implement `FromResidual<Yeet<T>>`

on your type to enable
`do yeet expr`

syntax in functions returning your type.

An error which can be returned when parsing an integer.

A (half-open) range bounded inclusively below and exclusively above
(`start..end`

).

A range only bounded inclusively below (`start..`

).

An unbounded range (`..`

).

A range bounded inclusively below and above (`start..=end`

).

A range only bounded exclusively above (`..end`

).

A range only bounded inclusively above (`..=end`

).

A UTF-8–encoded, growable string.

Fixed length byte array.

Fixed length byte array.

Fixed length byte array.

Fixed length byte array.

Implement `FromResidual<Yeet<T>>`

on your type to enable
`do yeet expr`

syntax in functions returning your type.

A (half-open) range bounded inclusively below and exclusively above
(`start..end`

).

A range only bounded inclusively below (`start..`

).

An unbounded range (`..`

).

A range bounded inclusively below and above (`start..=end`

).

A range only bounded exclusively above (`..end`

).

A range only bounded inclusively above (`..=end`

).

A contiguous growable array type, written as `Vec<T>`

, short for ‘vector’.

Fixed length byte array.

Fixed length byte array.

Fixed length byte array.

Fixed length byte array.

## Enums

The result of a generator resumption.

An endpoint of a range of keys.

Used to tell an operation whether it should exit early or go on as usual.

An `Ordering`

is the result of a comparison between two values.

A Sign is a `BigInt`

’s composing element.

## Traits

Trait that indicates that this is a pointer or a wrapper for one, where unsizing can be performed on the pointee.

`DispatchFromDyn`

is used in the implementation of object safety checks (specifically allowing
arbitrary self types), to guarantee that a method’s receiver type can be dispatched on.

Used to specify which residuals can be converted into which `crate::ops::Try`

types.

The trait implemented by builtin generator types.

The addition operator `+`

.

The addition assignment operator `+=`

.

The bitwise AND operator `&`

.

The bitwise AND assignment operator `&=`

.

The bitwise OR operator `|`

.

The bitwise OR assignment operator `|=`

.

The bitwise XOR operator `^`

.

The bitwise XOR assignment operator `^=`

.

Performs subtraction that returns `None`

instead of wrapping around on underflow.

Trait that indicates that this is a pointer or a wrapper for one, where unsizing can be performed on the pointee.

`DispatchFromDyn`

is used in the implementation of object safety checks (specifically allowing
arbitrary self types), to guarantee that a method’s receiver type can be dispatched on.

Used to specify which residuals can be converted into which `crate::ops::Try`

types.

The trait implemented by builtin generator types.

`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.

Allows retrieving the canonical type implementing `Try`

that has this type
as its residual and allows it to hold an `O`

as its output.

The `?`

operator and `try {}`

blocks.

`?`

formatting.

Used for immutable dereferencing operations, like `*v`

.

Used for mutable dereferencing operations, like in `*v = 1;`

.

Format trait for an empty format, `{}`

.

The division operator `/`

.

The division assignment operator `/=`

.

Custom code within the destructor.

The version of the call operator that takes an immutable receiver.

The version of the call operator that takes a mutable receiver.

The version of the call operator that takes a by-value receiver.

Parse a value from a string

Used for indexing operations (`container[index]`

) in immutable contexts.

Used for indexing operations (`container[index]`

) in mutable contexts.

This trait extends the `Numeric`

trait and is implemented by all integer
types. It offers bit manipulation, instantiation from literal, and convenient
constants.

The multiplication operator `*`

.

The multiplication assignment operator `*=`

.

The unary negation operator `-`

.

The unary logical negation operator `!`

.

The base trait for numeric types, covering `0`

and `1`

values,
comparisons, basic numeric operations, and string conversion.

The `Numeric`

trait has to be implemented by all numeric objects.

Defines a multiplicative identity element for `Self`

.

`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.

Trait for equality comparisons which are partial equivalence relations.

Allows retrieving the canonical type implementing `Try`

that has this type
as its residual and allows it to hold an `O`

as its output.

`RangeBounds`

is implemented by Rust’s built-in range types, produced
by range syntax like `..`

, `a..`

, `..b`

, `..=c`

, `d..e`

, or `f..=g`

.

The remainder operator `%`

.

The remainder assignment operator `%=`

.

Common trait for all byte arrays and sequences.

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.

The left shift assignment operator `<<=`

.

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.

The right shift assignment operator `>>=`

.

Useful functions for signed numbers (i.e. numbers that can be negative).

The `?`

operator and `try {}`

blocks.

`RangeBounds`

is implemented by Rust’s built-in range types, produced
by range syntax like `..`

, `a..`

, `..b`

, `..=c`

, `d..e`

, or `f..=g`

.

The remainder operator `%`

.

The remainder assignment operator `%=`

.

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.

The left shift assignment operator `<<=`

.

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.

The right shift assignment operator `>>=`

.

The subtraction operator `-`

.

The subtraction assignment operator `-=`

.

A trait for converting a value to a `String`

.

Simple and safe type conversions that may fail in a controlled
way under some circumstances. It is the reciprocal of `TryInto`

.

Defines an additive identity element for `Self`

.

## Functions

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

*This function is within the hacspec subset of Rust: its signature and body use only hacspec constructs and
call functions whose signatures are in hacspec.*

*This function is within the hacspec subset of Rust: its signature and body use only hacspec constructs and
call functions whose signatures are in hacspec.*

*This function is within the hacspec subset of Rust: its signature and body use only hacspec constructs and
call functions whose signatures are in hacspec.*

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

**Warning:** wrapping semantics.

*This function can be called from hacspec programs but its body features Rust constructs that are not part of hacspec*
Polynomial Addition, calculates a + b mod modulo

*Function that is not part of the language but is offered as a helper for tests, etc.*
Add two numerics if condition `c`

is set (all bits 1).
Returns `x`

if condition `c`

is `0`

.
Note: Addition is always wrapping.

*Function that is not part of the language but is offered as a helper for tests, etc.*
Multiply two numerics if condition `c`

is set (all bits 1).
Returns `x`

if condition `c`

is `0`

.
Note: Multiplication is always wrapping.

*Function that is not part of the language but is offered as a helper for tests, etc.*
Set bit at position `i`

in `x`

to `b`

if `c`

is all 1 and return the restult.
Returns `x`

if `c`

is `0`

.

*Function that is not part of the language but is offered as a helper for tests, etc.*
Subtract two numerics if condition `c`

is set (all bits 1).
Returns `x`

if condition `c`

is `0`

.
Note: Addition is always wrapping.

*Function that is not part of the language but is offered as a helper for tests, etc.*
Conditional, constant-time swapping.
Returns `(x, y)`

if `c == 0`

and `(y, x)`

if `c == T::max`

.
The return value is undefined if `c`

has any other value.

*Function that is not part of the language but is offered as a helper for tests, etc.*
Conditional, constant-time swapping.
Returns `(x, y)`

if `c == 0`

and `(y, x)`

if `c == 1`

.

*Function that is not part of the language but is offered as a helper for tests, etc.*
Constant time division for Numerics.
Note that this function is only constant time if `T`

is a secret integer and
hence provides constant time implementations for the used functions.

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

**Warning:** conversion can be lossy!

*This function can be called from hacspec programs but its body features Rust constructs that are not part of hacspec*
Returns degree of polynomial, e.g. for 3x² + 2x + 1 -> 2

Euclidean polynomial division, calculates `a/b`

in `R_n`

.
Returns `Ok(quotient, remainder)`

or `Err("Can't divide these two polynomials")`

*Function that is not part of the language but is offered as a helper for tests, etc.*
Scalar division in `R_p`

.
Returns `a / scalar mod p`

.

*This function can be called from hacspec programs but its body features Rust constructs that are not part of hacspec*
Euclidean algorithm to compute the inverse of x in yℤ[x]

*Function that is not part of the language but is offered as a helper for tests, etc.*

makes coefficients positiv, e.g. -3 mod 4 = 1

Compares and returns the minimum of two values.

Simple polynomial multiplication for two fixed size polynomials O(n²) with `a * b mod n`

Returns the multiplicative identity, `1`

.

*Function that is not part of the language but is offered as a helper for tests, etc.*

**Warning:** conversion can be lossy!

Returns number of coefficient != 0, e.g. for -3x⁵ + 3x² + 2x + 1 -> 4

Returns the additive identity, `0`

.

## Attribute Macros

Function that is not part of the language but is offered as a helper for tests, etc.