Struct testdir::NumberedDir

pub struct NumberedDir { /* private fields */ }

A sequentially numbered directory.

This struct represents a directory is a sequentially numbered list of directories. It allows creating the next sequential directory safely across processes or threads without any coordination as well as cleanup of older directories.

The directory has a parent directory in which the numbered directory is created, as well as a base which is used as the directory name to which to affix the number.

Implementations

impl NumberedDir

pub fn create(
    parent: impl AsRef<Path>,
    base: &str,
    count: NonZeroU8
) -> Result<Self>

Creates the next sequential numbered directory.

The directory will be created inside parent and will start with the name given in base to which the next available number is suffixed.

If there are concurrent directories being created this will retry incrementing the number up to 16 times before giving up.

The count specifies the total number of directories to leave in place, including the newly created directory. Other previous directories with all their files and subdirectories are recursively removed. Care is taken to avoid removing new directories concurrently created by parallel invocations in other threads or processes..

pub fn iterate(parent: impl AsRef<Path>, base: &str) -> Result<NumberedDirIter>

Returns an iterator over all NumberedDir entries in a parent directory.

This iterator can be used to get access to existing NumberedDir directories without creating a new one.

pub fn path(&self) -> &Path

Returns the path of this numbered directory instance.

pub fn base(&self) -> &str

Returns the base of this NumberedDir instance.

The base is the name of the final NumberedDir::path component without the numbered suffix.

pub fn number(&self) -> u16

Returns the number suffix of this NumberedDir instance.

The number is the suffix of the final component of NumberedDir::path.

pub fn create_subdir(&self, rel_path: impl AsRef<Path>) -> Result<PathBuf>

Creates a new subdirecotry within this numbered directory.

This function will always create a new subdirecotry, if such a directory already exists the last component will get an incremental number suffix.

Limitations

Only up to u16::MAX numbered suffixes are created so this is the maximum number of “identically” named directories that can be created. Creating so many directories will become expensive however as the suffixes are linearly searched for the next available suffix. This is not meant for a high number of conflicting subdirectories, if this is required ensure the rel_path passed in already avoids conflicts.

There is no particular safety from malicious input, the numbered directory can be trivially escaped using the parent directory location: ../somewhere/else.

Trait Implementations

impl Clone for NumberedDir

fn clone(&self) -> NumberedDir

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for NumberedDir

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

Formats the value using the given formatter.

impl PartialEq<NumberedDir> for NumberedDir

fn eq(&self, other: &NumberedDir) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for NumberedDir

impl StructuralEq for NumberedDir

impl StructuralPartialEq for NumberedDir