Enum DeferredReadOrOwn 

pub enum DeferredReadOrOwn<'a, T, Vfs: VfsCore = FsVfs, const CHECK_ON_READ: bool = false> {
    Own(T),
    Deferred(DeferredRead<'a, T, Vfs, CHECK_ON_READ>),
}

A wrapper that defers the reading of a file until it is actually needed, but can also store the value.

It allows us to read the value from disk, and then store it in memory, and if we ever need it again, we can just return the stored value.

This type exposes 2 functions: DeferredReadOrOwn::get and DeferredReadOrOwn::perform_and_store_read.

The table below summarizes the differences between the two functions:

State	DeferredReadOrOwn::get	DeferredReadOrOwn::perform_and_store_read
New, not cached	Reads the value, does not cache	Reads the value, and caches it, returns reference
Cached	Clones the cached value	Returns a reference to the cached value

As such, DeferredReadOrOwn::get has the signature of fn(&self) -> Result<T> and DeferredReadOrOwn::perform_and_store_read has the signature of fn(&mut self) -> Result<&mut T>.

If you never call DeferredReadOrOwn::perform_and_store_read, and only ever call DeferredReadOrOwn::get, that would effectively be the same as using a DeferredRead, and that should be preferred instead.

Variants

Own(T)

An owned value.

Deferred(DeferredRead<'a, T, Vfs, CHECK_ON_READ>)

A deferred read.

Implementations

impl<'a, const CHECK_ON_READ: bool, T, Vfs: Vfs<'a, Path = P>, P: PathType + ?Sized + 'a> DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: ReadFrom<'a, Vfs>,

pub fn get(&self) -> VfsResult<T, Vfs>

where T: Clone,

Gets the value. If it is not already read, it will read it, but without saving it.

This is useful if you want to read the value, but you don’t want to store it.

Though never calling DeferredReadOrOwn::perform_and_store_read and only calling DeferredReadOrOwn::get is equivalent to using a DeferredRead, and that should be preferred.

See DeferredReadOrOwn for more details.

Examples

use std::path::Path;
use std::pin::Pin;
use dir_structure::traits::sync::DirStructureItem;
use dir_structure::deferred_read::DeferredRead;
use dir_structure::deferred_read_or_own::DeferredReadOrOwn;
use dir_structure::prelude::*;
use dir_structure::vfs::fs_vfs::FsVfs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let d = Path::new("dir");
    std::fs::create_dir_all(&d)?;
    let deferred = DeferredReadOrOwn::<String, FsVfs>::Deferred(
        DeferredRead::read_from(d.join("f.txt").as_ref(), Pin::new(&FsVfs)).unwrap()
    );
    assert!(deferred.get().is_err());
    std::fs::write(d.join("f.txt"), "Hello, world!")?;
    assert_eq!(deferred.get()?, "Hello, world!");
    std::fs::write(d.join("f.txt"), "Goodbye, world!")?;
    assert_eq!(deferred.get()?, "Goodbye, world!");
    Ok(())
}

pub fn perform_and_store_read(&mut self) -> VfsResult<&mut T, Vfs>

Performs the read and stores the value. If the value is already read, it will just return a reference to it.

See DeferredReadOrOwn for more details.

Examples

use std::path::Path;
use std::pin::Pin;
use dir_structure::traits::sync::DirStructureItem;
use dir_structure::deferred_read::DeferredRead;
use dir_structure::deferred_read_or_own::DeferredReadOrOwn;
use dir_structure::prelude::*;
use dir_structure::vfs::fs_vfs::FsVfs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let d = Path::new("dir");
    std::fs::create_dir_all(&d)?;
    let mut deferred = DeferredReadOrOwn::<String, FsVfs>::Deferred(
        DeferredRead::read_from(d.join("f.txt").as_ref(), Pin::new(&FsVfs)).unwrap()
    );
    assert!(deferred.perform_and_store_read().is_err());
    std::fs::write(d.join("f.txt"), "Hello, world!")?;
    assert_eq!(deferred.perform_and_store_read()?, "Hello, world!");
    std::fs::write(d.join("f.txt"), "Goodbye, world!")?;
    assert_eq!(deferred.perform_and_store_read()?, "Hello, world!");
    Ok(())
}

pub fn flush_to<'t, TargetVfs: WriteSupportingVfs<'t, Path = P>>( &self, path: &P, vfs: Pin<&'t TargetVfs>, ) -> VfsResult<(), Vfs>

where T: WriteTo<'t, TargetVfs>,

Flushes the current value to the specified path.

impl<'a, const CHECK_ON_READ: bool, T, Vfs: VfsAsync<Path = P> + 'a, P: PathType + ?Sized + 'a> DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: ReadFromAsync<'a, Vfs> + Send + 'static,

pub async fn get_async(&'a self) -> VfsResult<T, Vfs>

where T: Clone,

Available on crate feature async only.

Gets the value, asynchronously. This is an async version of get.

pub async fn perform_and_store_read_async( &'a mut self, ) -> VfsResult<&'a mut T, Vfs>

Available on crate feature async only.

Performs the read and stores the value. If the value is already read, it will just return a reference to it.

See DeferredReadOrOwn for more details.

This is an async version of perform_and_store_read.

impl<'a, const CHECK_ON_READ: bool, T, Vfs: VfsAsync<Path = P> + 'a, P: PathType + ?Sized + 'a> DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where P::OwnedPath: 'a,

pub async fn flush_to_async<TargetVfs: WriteSupportingVfsAsync<Path = P> + 'a, ReadFutTy>( &'a self, path: P::OwnedPath, vfs: Pin<&'a TargetVfs>, ) -> VfsResult<(), Vfs>

where for<'b> T: ReadFromAsync<'b, Vfs, Future = ReadFutTy> + WriteToAsync<'b, TargetVfs> + WriteToAsyncRef<'b, TargetVfs> + Send + 'b, ReadFutTy: Future<Output = VfsResult<T, Vfs>> + Unpin + 'static,

Available on crate feature async only.

Flushes the current value to the specified path. Async version of flush_to.

Trait Implementations

impl<'a, T, Vfs: VfsCore<Path = P>, P, const CHECK_ON_READ: bool> AssertEq for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: AssertEq, P: PathType + ?Sized, P::OwnedPath: AssertEq + Debug,

fn assert_eq( &self, other: &Self, path: &mut AssertPath, init_left: &impl Display, init_right: &impl Display, )

Asserts that self is equal to other, panicking if they are not equal.

impl<'a, T: Clone, Vfs: Clone + VfsCore, const CHECK_ON_READ: bool> Clone for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

fn clone(&self) -> DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, const CHECK_ON_READ: bool, T, Vfs: VfsCore<Path = P>, P> Debug for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: Debug, P: PathType + ?Sized, P::OwnedPath: Debug,

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

Formats the value using the given formatter.

impl<'a, const CHECK_ON_READ: bool, T, Vfs> DynamicHasField for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: DynamicHasField, Vfs: VfsCore,

Available on crate feature resolve-path only.

type Inner = <T as DynamicHasField>::Inner

The type of the field.

fn resolve_path<P: OwnedPathType>(p: P, name: &str) -> P

How to resolve the path for the field, from the path of Self, given the name passed into the resolve_path! macro.

impl<'a, const CHECK_ON_READ: bool, const NAME: [char; 32], T, Vfs> HasField<NAME> for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: HasField<NAME>, Vfs: VfsCore,

Available on crate feature resolve-path only.

type Inner = <T as HasField<NAME>>::Inner

The type of the field.

fn resolve_path<P: OwnedPathType>(p: P) -> P

How to resolve the path for the field, from the path of Self.

impl<'a, T, Vfs: VfsCore, const CHECK_ON_READ: bool> Hash for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: Hash, <Vfs::Path as PathType>::OwnedPath: Hash,

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<'a, const CHECK_ON_READ: bool, T, Vfs: Vfs<'a>> ReadFrom<'a, Vfs> for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: ReadFrom<'a, Vfs>,

fn read_from(path: &Vfs::Path, vfs: Pin<&'a Vfs>) -> VfsResult<Self, Vfs>

where Self: Sized,

Reads the structure from the specified path, which can be either a file or a directory.

impl<'a, const CHECK_ON_READ: bool, T, Vfs: VfsAsync<Path = P> + 'static, P: PathType + ?Sized + 'a> ReadFromAsync<'a, Vfs> for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: ReadFromAsync<'a, Vfs> + Send + 'static, P::OwnedPath: Send + Sync,

Available on crate feature async only.

type Future = Pin<Box<dyn Future<Output = Result<DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>, Error<<<Vfs as VfsCore>::Path as PathType>::OwnedPath>>> + Send + 'a>>

The future type returned by the async read function.

fn read_from_async(path: P::OwnedPath, vfs: Pin<&'a Vfs>) -> Self::Future

Asynchronously reads the structure from the specified path, which can be either a file or a directory.

impl<'a, 't, const CHECK_ON_READ: bool, T, P: PathType + ?Sized + 'a, SelfVfs: Vfs<'a, Path = P>, TargetVfs: WriteSupportingVfs<'t, Path = P>> WriteTo<'t, TargetVfs> for DeferredReadOrOwn<'a, T, SelfVfs, CHECK_ON_READ>

where T: ReadFrom<'a, SelfVfs> + WriteTo<'t, TargetVfs>,

fn write_to( &self, path: &P, vfs: Pin<&'t TargetVfs>, ) -> Result<(), P::OwnedPath>

Writes the structure to the specified path.

impl<'a, const CHECK_ON_READ: bool, T, Vfs: WriteSupportingVfsAsync + 'static> WriteToAsync<'a, Vfs> for DeferredReadOrOwn<'a, T, Vfs, CHECK_ON_READ>

where T: for<'b> ReadFromAsync<'b, Vfs> + for<'b> WriteToAsync<'b, Vfs> + Send + 'static, for<'b> <T as ReadFromAsync<'b, Vfs>>::Future: Future<Output = VfsResult<T, Vfs>> + Unpin + 'b, for<'b> <T as WriteToAsync<'b, Vfs>>::Future: Future<Output = VfsResult<(), Vfs>> + Unpin + 'b,

Available on crate feature async only.

type Future = DeferredReadOrOwnWriteFuture<'a, T, Vfs, CHECK_ON_READ>

The future type returned by the async write function.

fn write_to_async( self, path: <<Vfs as VfsCore>::Path as PathType>::OwnedPath, vfs: Pin<&'a Vfs>, ) -> Self::Future

Asynchronously writes the structure to the specified path.