Enum Stat 

pub enum Stat<T> {
    Known {
        value: T,
        class: Class,
    },
    Unknown,
}

One statistic, or the honest absence of one.

Known carries the value and how much to trust it. Unknown is what a question has no answer to, and the whole design rests on callers treating it as a case rather than as a zero.

Variants

Known

A value, and what kind of knowledge it is.

Fields

value: T

The number, bound, flag or set the question asked for.

class: Class

How much of it is known rather than guessed.

Unknown

No answer. Not a zero, not a one and not a default.

Implementations

impl<T> Stat<T>

pub const fn exact(value: T) -> Self

A value that was counted, compared or maintained rather than guessed.

pub const fn certified(value: T, bound: f64) -> Self

A value wrong by no more than bound as a fraction of itself.

pub const fn estimated(value: T, source: Source) -> Self

A guess, and where it came from.

pub const fn is_known(&self) -> bool

Whether there is an answer at all.

pub const fn is_unknown(&self) -> bool

Whether there is no answer.

pub const fn value(&self) -> Option<&T>

The value, whatever its class, for a decision that only chooses between equivalent plans.

pub const fn exact_value(&self) -> Option<&T>

The value, but only when it is exact.

The one door for a decision that changes an answer if the number is wrong. Folding a predicate away, narrowing arithmetic, dropping an aggregate: all of them ask here, and all of them take today’s path when the answer is None. See spec/stats/05-every-query.md section 5.10, which is where the rule is stated and where the warning about breaking it in good faith is written down.

pub const fn class(&self) -> Option<Class>

How much of the answer is knowledge, or None when there is no answer.

pub fn unwrap_or(self, default: T) -> T

The value, or what the caller decided to do without one.

pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Stat<U>

The same answer about a different quantity, with the class carried across unchanged.

For a transformation that cannot lose knowledge, such as reading a row count as a byte count through a fixed width. A transformation that does lose knowledge should build its answer with the class it deserves rather than mapping.

pub fn zip<U, V>(self, other: Stat<U>, f: impl FnOnce(T, U) -> V) -> Stat<V>

An answer computed from two, unknown when either is unknown, classed by Class::combine.

Trait Implementations

impl<T: Clone> Clone for Stat<T>

fn clone(&self) -> Stat<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Copy> Copy for Stat<T>

impl<T: Debug> Debug for Stat<T>

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

Formats the value using the given formatter.

impl<T> Default for Stat<T>

fn default() -> Self

Unknown, because a statistic nobody filled in is a statistic nobody knows.

impl<T: Display> Display for Stat<T>

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

Formats the value using the given formatter.

impl<T: PartialEq> PartialEq for Stat<T>

fn eq(&self, other: &Stat<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: PartialEq> StructuralPartialEq for Stat<T>