Struct Versioned 

pub struct Versioned<T, P: PathType + ?Sized = Path> { /* private fields */ }

A versioned value. This is a wrapper around a value that will keep track of how many times it has been changed. This is useful to not write the value to disk if it hasn’t changed.

You can get a reference to the value via its Deref implementation, and you can get a mutable reference to the value via its DerefMut implementation.

The version is incremented every time DerefMut::deref_mut is called.

Alternatively, for Eq types, you can use the Versioned::edit_eq_check method to edit the value, and it will increment the version if the value has changed.

Example

use std::path::Path;
use dir_structure::versioned::VersionedString;

let mut v = VersionedString::<Path>::new("value".to_owned(), "path".to_owned());
assert!(v.is_clean());
assert!(!v.is_dirty());

*v = "new value".to_owned();
assert!(v.is_dirty());

Implementations

impl<T, P: PathType + ?Sized> Versioned<T, P>

pub fn new(value: T, path: impl Into<P::OwnedPath>) -> Self

Creates a new Versioned with the specified value.

The version is set to the default value.

pub fn new_dirty(value: T, path: impl Into<P::OwnedPath>) -> Self

Creates a new Versioned with the specified value, and in a dirty state.

Example

use std::path::Path;
use dir_structure::versioned::VersionedString;

let v = VersionedString::<Path>::new_dirty("value".to_owned(), "path".to_owned());
assert!(v.is_dirty());

pub fn is_dirty(&self) -> bool

Checks if the value has been changed.

Example

use std::path::Path;
use dir_structure::versioned::VersionedString;

let mut v = VersionedString::<Path>::new("value".to_owned(), "path".to_owned());
assert!(!v.is_dirty());
*v = "new value".to_owned();
assert!(v.is_dirty());

pub fn is_clean(&self) -> bool

Checks if the value has not been changed.

Example

use std::path::Path;
use dir_structure::versioned::VersionedString;

let mut v = VersionedString::<Path>::new("value".to_owned(), "path".to_owned());
assert!(v.is_clean());
*v = "new value".to_owned();
assert!(!v.is_clean());

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

where T: Eq + Clone,

Edits the value using the provided closure, and increments the version if the value has changed.

Example

use std::path::Path;
use dir_structure::versioned::VersionedString;

let mut v = VersionedString::<Path>::new("value".to_owned(), "path".to_owned());

v.edit_eq_check(|s| *s = "value".to_owned());
assert!(v.is_clean());
v.edit_eq_check(|s| *s = "new value".to_owned());
assert!(v.is_dirty());

pub unsafe fn reset(&mut self)

Resets the version to the default value, making the value clean. This is useful if you want to mark the value as not changed, without actually changing it.

Safety

This function is unsafe because it allows you to reset the version to 0, which means that the value will be considered clean, and any unsaved changes will be lost. Trying to save a clean value (e.g. after calling this function) will not write it to disk!

Use with caution!

Examples

use std::path::Path;
use dir_structure::{traits::sync::DirStructureItem, versioned::VersionedString};
std::fs::write("path", "value").unwrap();

let mut v = VersionedString::<Path>::new("value".to_owned(), "path".to_owned());
assert!(v.is_clean());
v.edit_eq_check(|s| *s = "new value".to_owned());
assert!(v.is_dirty());
unsafe { v.reset(); }
assert!(v.is_clean());

// if you try to write it now, it won't write anything,
v.write("path").unwrap();

assert_eq!(std::fs::read_to_string("path").unwrap(), "value");

Trait Implementations

impl<T, P: PathType + ?Sized> AssertEq for Versioned<T, P>

where for<'__trivial> T: AssertEq<T> + Debug, for<'__trivial> usize: AssertEq<usize> + Debug, for<'__trivial> P::OwnedPath: AssertEq<P::OwnedPath> + 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<T, P: PathType + ?Sized> Clone for Versioned<T, P>

where T: Clone, P::OwnedPath: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug, P: Debug + PathType + ?Sized> Debug for Versioned<T, P>

where P::OwnedPath: Debug,

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

Formats the value using the given formatter.

impl<T, P: PathType + ?Sized> Deref for Versioned<T, P>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, P: PathType + ?Sized> DerefMut for Versioned<T, P>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T, P: PathType + ?Sized> DynamicHasField for Versioned<T, P>

where T: DynamicHasField,

Available on crate feature resolve-path only.

type Inner = <T as DynamicHasField>::Inner

The type of the field.

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

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

impl<const NAME: [char; 32], T, P: PathType + ?Sized> HasField<NAME> for Versioned<T, P>

where T: HasField<NAME>,

Available on crate feature resolve-path only.

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

The type of the field.

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

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

impl<T: Hash, P: Hash + PathType + ?Sized> Hash for Versioned<T, P>

where P::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<T: PartialEq, P: PartialEq + PathType + ?Sized> PartialEq for Versioned<T, P>

where P::OwnedPath: PartialEq,

fn eq(&self, other: &Versioned<T, P>) -> 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<'a, Vfs: Vfs<'a>, T> ReadFrom<'a, Vfs> for Versioned<T, Vfs::Path>

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, Vfs: VfsAsync + 'static, T: ReadFromAsync<'a, Vfs> + Send + 'static> ReadFromAsync<'a, Vfs> for Versioned<T, Vfs::Path>

Available on crate feature async only.

type Future = VersionedReadFuture<'a, Vfs, T>

The future type returned by the async read function.

fn read_from_async( path: <<Vfs as VfsCore>::Path as PathType>::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, Vfs: WriteSupportingVfs<'a>, T: WriteTo<'a, Vfs>> WriteTo<'a, Vfs> for Versioned<T, Vfs::Path>

where Vfs::Path: PartialEq,

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

Writes the structure to the specified path.

impl<'a, T, Vfs: WriteSupportingVfsAsync + 'static> WriteToAsync<'a, Vfs> for Versioned<T, Vfs::Path>

where T: WriteToAsync<'a, Vfs> + Send + Sync + 'static, <T as WriteToAsync<'a, Vfs>>::Future: Future<Output = VfsResult<(), Vfs>> + Unpin, Vfs::Path: PartialEq,

Available on crate feature async only.

type Future = VersionedWriteFuture<'a, T, Vfs>

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.

impl<'r, T, Vfs: WriteSupportingVfsAsync + 'static> WriteToAsyncRef<'r, Vfs> for Versioned<T, Vfs::Path>

where T: WriteToAsyncRef<'r, Vfs> + Send + Sync + 'static, for<'f> <T as WriteToAsyncRef<'r, Vfs>>::Future<'f>: Future<Output = VfsResult<(), Vfs>> + Unpin + 'f, Vfs::Path: PartialEq,

Available on crate feature async only.

type Future<'a> = VersionedWriteRefFuture<'r, 'a, T, Vfs> where Self: 'a, Vfs: 'a, 'r: 'a

The future type returned by the async write function.

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

where 'r: 'a,

Asynchronously writes the structure to the specified path.

impl<T: Eq, P: Eq + PathType + ?Sized> Eq for Versioned<T, P>

where P::OwnedPath: Eq,

impl<T, P: PathType + ?Sized> StructuralPartialEq for Versioned<T, P>