Struct sloth::Lazy

pub struct Lazy<T, Eval> where
    Eval: FnOnce() -> T,  { /* fields omitted */ }

Contains a value of some type T, lazily evaluated using a parameterless function or a closure (FnOnce() -> T) passed to Lazy::new().

This type provides pointer-like interface to the evaluation result, implementing Deref, AsRef, Borrow and their Mut counterparts.

The result will be evaluated the first time it is accessed via any of Lazy's methods.

Accessing evaluated value

A Lazy value can be acessed in any of the following ways:

use sloth::Lazy;
 
let mut lazy_value = Lazy::new(|| 2019);
 
let value: i32 = *lazy_value;
let value_ref: &i32 = lazy_value.as_ref();
let value_mut: &mut i32 = lazy_value.as_mut();
 
let value_copy: i32 = lazy_value.value(); // only for types implementing Copy
 
let value: i32 = lazy_value.unwrap(); // consumes lazy_value

Due to Deref coercion T's methods may be called directly on Lazy<T, Eval>, while references to Lazy are coerced to references to T:

use sloth::Lazy;
 
fn print_string_len(string: &String) {
    println!("{} has length {}", string, string.len());
}
 
let mut lazy_string = Lazy::new(|| String::from("lorem "));
 
lazy_string.push_str("ipsum"); // can call T's methods
 
print_string_len(&lazy_string); // can pass as &T function param

Laziness

The evaluator function will not be called more than once, regardless of how many times the value is accessed:

use sloth::Lazy;
 
let mut evaluator_called_times = 0;
 
let lazy_value = Lazy::new(|| {
    evaluator_called_times += 1;
    25
});
 
assert_eq!(*lazy_value, 25);
 
let another_value = *lazy_value + *lazy_value;
 
assert_eq!(evaluator_called_times, 1);

If a Lazy value is never dereferenced and none of its methods are called, its evaluator function will not be invoked at all.

Methods

impl<T, Eval> Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

pub fn new(evaluator: Eval) -> Self

Constructs a lazy T instance, whose value, if needed, will later be obtained from evaluator and cached.

evaluator will be invoked only the first time this instance is dereferenced or one of its methods is invoked.

#[must_use] pub fn value_ref(&self) -> Ref<T>

Deprecated since 0.2.0:

will be removed in sloth 0.3.0; please use as_ref() or * deref operator instead

Immutably borrows the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

value_ref() will be removed in sloth 0.3.0. as_ref() or immutable * dereference should be used instead.

#[must_use] pub fn value_mut(&mut self) -> RefMut<T>

Deprecated since 0.2.0:

will be removed in sloth 0.3.0; please use as_mut() or * deref operator instead

Mutably borrows the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

value_mut() will be removed in sloth 0.3.0. as_mut() or mutable * dereference should be used instead.

#[must_use] pub fn unwrap(self) -> T

Consumes this Lazy<T, Eval> instance and extracts the evaluation result value.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

impl<T, Eval> Lazy<T, Eval> where
    T: Copy,
    Eval: FnOnce() -> T, 

#[must_use] pub fn value(&self) -> T

Returns a copy of the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

Trait Implementations

impl<T, Eval> AsMut<T> for Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

fn as_mut(&mut self) -> &mut T

Mutably borrows the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

impl<T, Eval> AsRef<T> for Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

fn as_ref(&self) -> &T

Immutably borrows the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

impl<T, Eval> Deref for Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Immutable dereference, allowing access to the contained value.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

impl<T, Eval> DerefMut for Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

fn deref_mut(&mut self) -> &mut T

Mutable dereference, allowing access to the contained value.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

impl<T, Eval> BorrowMut<T> for Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

fn borrow_mut(&mut self) -> &mut T

Mutably borrows the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.

impl<T, Eval> Borrow<T> for Lazy<T, Eval> where
    Eval: FnOnce() -> T, 

fn borrow(&self) -> &T

Immutably borrows the evaluation result.

This will invoke evaluator function if none of the methods or * deref operator were previously used.