Enum Unknown 

#[non_exhaustive]
pub enum Unknown<T> {
    Discarded(PhantomData<T>),
    Retained(T),
}

Information about unknown values, which may have been retained as a T

Won’t grow additional variants - but, Retained is only included conditionally.

Also used in the form Unknown<()> to indicate whether unknown values should be retained.

Example

#![cfg(feature = "retain-unknown")]

use tor_netdoc::types::Unknown;

let mut unk: Unknown<Vec<String>> = Unknown::new_retained_default();
unk.with_mut_unknown(|u| u.push("something-we-found".into()));
assert_eq!(unk.into_retained().unwrap(), ["something-we-found"]);

Equality comparison, semantics

Two Unknown are consider equal if both have the same record of unknown values, or if neither records unknown values at all.

Unknown is not Eq or Ord because we won’t want to relate a Discarded to a Retained. That would be a a logic error. partial_cmp gives None for this.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Discarded(PhantomData<T>)

The parsing discarded unknown values and they are no longer available.

Retained(T)

Available on crate feature retain-unknown only.

The document parsing retained (or should retain) unknown values.

Implementations

impl<T> Unknown<T>

pub fn new_discard() -> Self

Create an Unknown which specifies that values were discarded (or should be)

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

Map the Retained, if there is one

pub fn try_map<U, E>( self, f: impl FnOnce(T) -> Result<U, E>, ) -> Result<Unknown<U>, E>

Map the Retained, fallibly

pub fn as_ref(&self) -> Option<&T>

Obtain an Unknown containing (maybe) a reference

pub fn into_retained(self) -> Result<T, Bug>

Available on crate feature retain-unknown only.

Obtain the Retained data

Treats lack of retention as an internal error.

pub fn new_retained_default() -> Self

where T: Default,

Available on crate feature retain-unknown only.

Start recording unknown information, with a default value for T

pub fn with_mut_unknown(&mut self, f: impl FnOnce(&mut T))

Update the Retained, if there is one

Intended for use in parsing, when we encounter an unknown value.

Not provided in try_ form. If you think you need this, instead, unconditionally parse and verify the unknown value, and then conditionally insert it with this function. Don’t parse it conditionally - that would skip some validation.

Trait Implementations

impl<T: Clone> Clone for Unknown<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Unknown<T>

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

Formats the value using the given formatter.

impl<T: Hash> Hash for Unknown<T>

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<T: PartialEq> PartialEq for Unknown<T>

fn eq(&self, other: &Unknown<T>) -> 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<T: PartialOrd> PartialOrd for Unknown<T>

fn partial_cmp(&self, other: &Self) -> 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<T: Copy> Copy for Unknown<T>

impl<T> StructuralPartialEq for Unknown<T>