Struct Literal

pub struct Literal(/* private fields */);

A possibly negated variable

There are three kinds of variables: constants (Literal::FALSE and Literal::TRUE), circuit inputs, and gates.

Concerning ordering, the following properties hold: Given two Literals a, b, a <= b is equivalent to the lexicographic comparison (a.positive(), a.is_negative()) <= (b.positive(), b.is_negative()). Furthermore, Literal::FALSE <= a holds (and thus Literal::TRUE <= a if a != Literal::FALSE).

Implementations

impl Literal

pub const MAX_INPUT: usize = 4_611_686_018_427_387_901usize

Maximum input number representable as literal

pub const MAX_GATE: usize = 4_611_686_018_427_387_903usize

Maximum gate number representable as literal

pub const FALSE: Self

Literal representing the constant ⊥

This is literal is considered to be positive (i.e., not negated):

assert!(Literal::FALSE.is_positive());
assert!(Literal::FALSE < Literal::TRUE);

pub const TRUE: Self

Literal representing the constant ⊤

This is literal is considered to be negated:

assert!(Literal::TRUE.is_negative());
assert!(Literal::TRUE < Literal::from_input(false, 0));
assert!(Literal::TRUE < Literal::from_gate(false, 0));

pub const UNDEF: Self

Undefined literal

This is considered to be a positive (i.e., not negated) input, but its variable number is larger than Self::MAX_INPUT. Attempting to create this literal using Self::from_input() will trigger a debug assertion.

assert!(Literal::UNDEF.is_positive());
assert!(Literal::UNDEF.is_input());
assert_eq!(Literal::UNDEF.get_input(), Some(Literal::MAX_INPUT + 1));

pub const fn from_input(negative: bool, input: Var) -> Self

Create a new literal from an input variable

pub const fn from_gate(negative: bool, gate: Var) -> Self

Create a new literal from a gate number

pub const fn is_positive(self) -> bool

Is the literal positive?

Same as !self.is_negative()

assert!(Literal::from_input(false, 42).is_positive());
assert!(!Literal::from_input(true, 1337).is_positive());

pub const fn is_negative(self) -> bool

Is the literal negative?

Same as !self.is_positive()

assert!(Literal::from_gate(true, 42).is_negative());
assert!(!Literal::from_gate(false, 1337).is_negative());

pub const fn positive(self) -> Self

Get the positive variant of this literal

assert!(Literal::from_input(true, 42).positive().is_positive());

pub const fn negative(self) -> Self

Get the negative variant of this literal

assert_eq!(Literal::from_input(true, 42), Literal::from_input(false, 42).negative());
assert!(Literal::from_input(false, 42).negative().is_negative());

pub const fn is_input(self) -> bool

Does this literal refer to an input?

assert!(Literal::from_input(false, 42).is_input());
assert!(!Literal::FALSE.is_input());
assert!(!Literal::TRUE.is_input());
assert!(!Literal::from_gate(false, 1337).is_input());

pub const fn is_gate(self) -> bool

Check if this literal refers to a gate

assert!(Literal::from_gate(false, 42).is_gate());
assert!(!Literal::FALSE.is_gate());
assert!(!Literal::TRUE.is_gate());
assert!(!Literal::from_input(false, 1337).is_gate());

pub const fn get_input(self) -> Option<Var>

Get the input number (if this literal refers to an input)

assert_eq!(Literal::from_input(false, 42).get_input(), Some(42));
assert_eq!(Literal::FALSE.get_input(), None);
assert_eq!(Literal::TRUE.get_input(), None);
assert_eq!(Literal::from_gate(false, 42).get_input(), None);

pub const fn get_gate_no(self) -> Option<Var>

Get the gate number (if this literal refers to an input)

assert_eq!(Literal::from_gate(false, 42).get_gate_no(), Some(42));
assert_eq!(Literal::FALSE.get_gate_no(), None);
assert_eq!(Literal::TRUE.get_gate_no(), None);
assert_eq!(Literal::from_input(false, 42).get_gate_no(), None);

See also: Circuit::gate()

pub fn apply_gate_map(self, gate_map: &[Literal]) -> Self

Map this literal based on gate_map

If this literal refers to a gate, the method performs a lookup for the gate number in gate_map. If the gate number is in bounds, the return value is the mapped literal with its sign adjusted, otherwise the return value is Literal::UNDEF. Non-gate literals are returned as they are.

Trait Implementations

impl BitXor<bool> for Literal

type Output = Literal

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: bool) -> Self::Output

Performs the ^ operation.

impl Clone for Literal

fn clone(&self) -> Literal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Literal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Literal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Literal

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Not for Literal

type Output = Literal

The resulting type after applying the ! operator.

fn not(self) -> Self

Performs the unary ! operation.

impl Ord for Literal

fn cmp(&self, other: &Literal) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Literal

fn eq(&self, other: &Literal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Literal

fn partial_cmp(&self, other: &Literal) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Literal

impl Eq for Literal

impl StructuralPartialEq for Literal