Struct Pair

pub struct Pair<L, R, C = StdConverter> { /* private fields */ }

A pair of values where one can be converted to the other.

This data structure stores a pair or either a left or right value. The left and right values can be converted to each other using the Converter trait. By default, the StdConverter, which converts using From and TryFrom traits is used, but you can use custom closures by using fn_converter(), or you can implement Converter for your own type.

The getter methods like left() and right() use this converter when that side’s value is not present. Once a value is accessed, it is cached and will not be converted again. This caching can happen even in non-mutable methods.

On the other hand, the optional getter methods like left_opt() and right_opt() do not use the converter and always return the original value, thus they can return None.

Mutable accessors

Note that mutable accessors like left_mut() and right_mut() will erase the other value. This is because this pair is designed so that one side of the pair is a cache of the other side, so once either side is mutated, the other side becomes dirty and should be cleared.

Example

use cached_pair::{Pair, fn_converter};
use std::convert::Infallible;
use std::num::ParseIntError;

// Define a converter between i32 and String using fn_converter
let converter = fn_converter(
    |s: &String| s.parse::<i32>(),  // String -> i32 (may fail)
    |i: &i32| Ok::<String, Infallible>(i.to_string()),    // i32 -> String (never fails)
);

// Construct a pair from a left value.
let pair: Pair<i32, String, _> = Pair::from_left_conv(42i32, converter);

// Left value is present, but right value is not.
assert_eq!(pair.left_opt(), Some(&42));
assert_eq!(pair.right_opt(), None);

// Get a right value by converting the left value.
assert_eq!(pair.right(), &"42".to_string());

// Once we get the right value, it is cached.
assert_eq!(pair.right_opt(), Some(&"42".to_string()));

// mutable access
let mut pair = pair;

// Get a mutable reference to the left value.
*pair.left_opt_mut().unwrap() = 123;

// ...then the right value is cleared.
assert_eq!(pair.right_opt(), None);

Implementations

impl<L, R, C> Pair<L, R, C>

pub fn from_left(left: L) -> Self

where C: Default,

Creates a new pair from a left value.

pub fn from_right(right: R) -> Self

where C: Default,

Creates a new pair from a right value.

pub fn from_left_conv(left: L, converter: C) -> Self

Creates a new pair from a left value with a custom converter.

pub fn from_right_conv(right: R, converter: C) -> Self

Creates a new pair from a right value with a custom converter.

pub fn left_opt(&self) -> Option<&L>

Returns a reference to the left value if available.

Returns None if the left value is not present.

pub fn right_opt(&self) -> Option<&R>

Returns a reference to the right value if available.

Returns None if the right value is not present.

pub fn left_opt_mut(&mut self) -> Option<&mut L>

Returns a mutable reference to the left value if available.

Returns None if the left value is not present. Note: Obtaining a mutable reference will erase the right value.

pub fn right_opt_mut(&mut self) -> Option<&mut R>

Returns a mutable reference to the right value if available.

Returns None if the right value is not present. Note: Obtaining a mutable reference will erase the left value.

pub unsafe fn left_with<F: FnOnce(&R) -> L>(&self, f: F) -> &L

Returns a left value if it is available. If the left value is not available, converts the right value using the given closure. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn right_with<F: FnOnce(&L) -> R>(&self, f: F) -> &R

Returns a right value if it is available. If the right value is not available, converts the left value using the given closure. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_left_with<F: FnOnce(&R) -> Result<L, E>, E>( &self, f: F, ) -> Result<&L, E>

Returns a left value if it is available. If the left value is not available, attempts to convert the right value using the given closure.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_right_with<F: FnOnce(&L) -> Result<R, E>, E>( &self, f: F, ) -> Result<&R, E>

Returns a right value if it is available. If the right value is not available, attempts to convert the left value using the given closure.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn left_mut_with<F: FnOnce(&R) -> L>(&mut self, f: F) -> &mut L

Returns a mutable reference to the left value if it is available. Note: Obtaining a mutable reference will erase the right value. If the left value is not available, converts the right value using the given closure. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn right_mut_with<F: FnOnce(&L) -> R>(&mut self, f: F) -> &mut R

Returns a mutable reference to the right value if it is available. Note: Obtaining a mutable reference will erase the left value. If the right value is not available, converts the left value using the given closure. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_left_mut_with<F: FnOnce(&R) -> Result<L, E>, E>( &mut self, f: F, ) -> Result<&mut L, E>

Returns a mutable reference to the left value if it is available. Note: Obtaining a mutable reference will erase the right value. If the left value is not available, attempts to convert the right value using the given closure.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_right_mut_with<F: FnOnce(&L) -> Result<R, E>, E>( &mut self, f: F, ) -> Result<&mut R, E>

Returns a mutable reference to the right value if it is available. Note: Obtaining a mutable reference will erase the left value. If the right value is not available, attempts to convert the left value using the given closure.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn into_left_with<F: FnOnce(R) -> L>(self, f: F) -> L

Consumes the pair and returns the left value. If the left value is not available, converts the right value using the given closure. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn into_right_with<F: FnOnce(L) -> R>(self, f: F) -> R

Consumes the pair and returns the right value. If the right value is not available, converts the left value using the given closure. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_into_left_with<F: FnOnce(R) -> Result<L, E>, E>( self, f: F, ) -> Result<L, E>

Consumes the pair and attempts to return the left value. If the left value is not available, attempts to convert the right value using the given closure.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_into_right_with<F: FnOnce(L) -> Result<R, E>, E>( self, f: F, ) -> Result<R, E>

Consumes the pair and attempts to return the right value. If the right value is not available, attempts to convert the left value using the given closure.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub fn as_ref(&self) -> EitherOrBoth<&L, &R>

Returns a reference to the pair as EitherOrBoth enum.

Provides a view of the pair’s current state using the EitherOrBoth type. If you specify the itertools feature, it uses the itertools::EitherOrBoth type. Otherwise, it uses the EitherOrBoth enum defined in this crate.

pub unsafe fn extract_left_with<F: FnOnce(&L) -> R>( &mut self, f: F, ) -> Option<L>

Clears the left value if it exists and returns it. If the left value is the only value in the pair, converts it to a right value using the given closure before clearing. Returns None if the left value doesn’t exist. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn extract_right_with<F: FnOnce(&R) -> L>( &mut self, f: F, ) -> Option<R>

Clears the right value if it exists and returns it. If the right value is the only value in the pair, converts it to a left value using the given closure before clearing. Returns None if the right value doesn’t exist. The closure must not fail.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_extract_left_with<F: FnOnce(&L) -> Result<R, E>, E>( &mut self, f: F, ) -> Result<Option<L>, E>

Clears the left value if it exists and returns it. If the left value is the only value in the pair, attempts to convert it to a right value using the given closure before clearing. Returns None if the left value doesn’t exist. Returns Err if conversion fails when needed.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub unsafe fn try_extract_right_with<F: FnOnce(&R) -> Result<L, E>, E>( &mut self, f: F, ) -> Result<Option<R>, E>

Clears the right value if it exists and returns it. If the right value is the only value in the pair, attempts to convert it to a left value using the given closure before clearing. Returns None if the right value doesn’t exist. Returns Err if conversion fails when needed.

Safety

The conversion function must be consistent with the converter’s behavior. Inconsistent conversions may lead to invalid state.

pub fn converter(&self) -> &C

Returns a reference to the converter used by this pair.

pub fn converter_mut(&mut self) -> &mut C

Returns a mutable reference to the converter used by this pair.

impl<L, R, C> Pair<L, R, C>

where C: Converter<L, R>,

pub fn try_left(&self) -> Result<&L, C::ToLeftError>

Attempts to get a reference to the left value, converting if necessary.

If the left value is not available, attempts to convert the right value using the converter.

pub fn try_right(&self) -> Result<&R, C::ToRightError>

Attempts to get a reference to the right value, converting if necessary.

If the right value is not available, attempts to convert the left value using the converter.

pub fn try_left_mut(&mut self) -> Result<&mut L, C::ToLeftError>

Attempts to get a mutable reference to the left value, converting if necessary.

If the left value is not available, attempts to convert the right value using the converter. Note: Obtaining a mutable reference will erase the right value.

pub fn try_right_mut(&mut self) -> Result<&mut R, C::ToRightError>

Attempts to get a mutable reference to the right value, converting if necessary.

If the right value is not available, attempts to convert the left value using the converter. Note: Obtaining a mutable reference will erase the left value.

pub fn try_into_left(self) -> Result<L, C::ToLeftError>

Attempts to consume the pair and return the left value, converting if necessary.

If the left value is not available, attempts to convert the right value using the converter.

pub fn try_into_right(self) -> Result<R, C::ToRightError>

Attempts to consume the pair and return the right value, converting if necessary.

If the right value is not available, attempts to convert the left value using the converter.

pub fn try_extract_left(&mut self) -> Result<Option<L>, C::ToRightError>

Attempts to extract the left value, converting if necessary.

If the left value is the only value in the pair, attempts to convert it to a right value before clearing. Returns None if the left value doesn’t exist. Returns Err if conversion fails when needed.

pub fn try_extract_right(&mut self) -> Result<Option<R>, C::ToLeftError>

Attempts to extract the right value, converting if necessary.

If the right value is the only value in the pair, attempts to convert it to a left value before clearing. Returns None if the right value doesn’t exist. Returns Err if conversion fails when needed.

impl<L, R, C> Pair<L, R, C>

where C: Converter<L, R, ToLeftError = Infallible>,

pub fn left(&self) -> &L

Returns a reference to the left value, converting from right if necessary.

If the left value is not available, converts the right value using the converter. This method is only available when the conversion is infallible.

pub fn left_mut(&mut self) -> &mut L

Returns a mutable reference to the left value, converting from right if necessary.

If the left value is not available, converts the right value using the converter. This method is only available when the conversion is infallible. Note: Obtaining a mutable reference will erase the right value.

pub fn into_left(self) -> L

Consumes the pair and returns the left value, converting from right if necessary.

If the left value is not available, converts the right value using the converter. This method is only available when the conversion is infallible.

pub fn extract_right(&mut self) -> Option<R>

Extracts and returns the right value if it exists.

If the right value is the only value in the pair, attempts to convert it to a left value before clearing. Returns None if the right value doesn’t exist. This method is only available when the conversion is infallible.

impl<L, R, C> Pair<L, R, C>

where C: Converter<L, R, ToRightError = Infallible>,

pub fn right(&self) -> &R

Returns a reference to the right value, converting from left if necessary.

If the right value is not available, converts the left value using the converter. This method is only available when the conversion is infallible.

pub fn right_mut(&mut self) -> &mut R

Returns a mutable reference to the right value, converting from left if necessary.

If the right value is not available, converts the left value using the converter. This method is only available when the conversion is infallible. Note: Obtaining a mutable reference will erase the left value.

pub fn into_right(self) -> R

Consumes the pair and returns the right value, converting from left if necessary.

If the right value is not available, converts the left value using the converter. This method is only available when the conversion is infallible.

pub fn extract_left(&mut self) -> Option<L>

Extracts and returns the left value if it exists.

If the left value is the only value in the pair, attempts to convert it to a right value before clearing. Returns None if the left value doesn’t exist. This method is only available when the conversion is infallible.

Trait Implementations

impl<L: Clone, R: Clone, C: Clone> Clone for Pair<L, R, C>

fn clone(&self) -> Pair<L, R, C>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<L: Debug, R: Debug, C> Debug for Pair<L, R, C>

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

Formats the value using the given formatter.

impl<L, R, C> From<Pair<L, R, C>> for EitherOrBoth<L, R>

fn from(pair: Pair<L, R, C>) -> Self

Converts to this type from the input type.

impl<L: Hash, R: Hash, C> Hash for Pair<L, R, C>

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<L: PartialEq, R: PartialEq, C> PartialEq for Pair<L, R, C>

fn eq(&self, other: &Self) -> 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.