Struct Directory 

pub struct Directory<T> {
    pub stat: Stat,
    pub(crate) entries: BTreeMap<Box<OsStr>, Inode<T>>,
}

A directory node containing named entries.

Fields

stat: Stat

Metadata for this directory.

entries: BTreeMap<Box<OsStr>, Inode<T>>

Map of filenames to inodes within this directory.

Implementations

impl<T> Directory<T>

pub fn new(stat: Stat) -> Self

Creates a new directory with the given metadata.

pub fn inodes(&self) -> impl Iterator<Item = &Inode<T>> + use<'_, T>

Iterates over all inodes in the current directory, in no particular order.

pub fn entries(&self) -> impl Iterator<Item = (&OsStr, &Inode<T>)> + use<'_, T>

Iterates over all entries in the current directory, in no particular order. The iterator returns pairs of (&OsStr, &Inode) and is probably used like so:

Currently this is equivalent to Directory::sorted_entries() but that might change at some point.

use composefs::{tree::{FileSystem, Stat}, fsverity::Sha256HashValue};
let fs = FileSystem::<Sha256HashValue>::new(Stat::uninitialized());

// populate the fs...

for (name, inode) in fs.root.entries() {
  // name: &OsStr, inode: &Inode
}

pub fn sorted_entries( &self, ) -> impl Iterator<Item = (&OsStr, &Inode<T>)> + use<'_, T>

Iterates over all entries in the current directory, in asciibetical order of name. The iterator returns pairs of (&OsStr, &Inode).

pub fn get_directory( &self, pathname: &OsStr, ) -> Result<&Directory<T>, ImageError>

Gets a reference to a subdirectory of this directory.

The given path may be absolute or relative and it makes no difference. It may not contain any Windows-like prefixes, or “.” or “..” components. It may or may not end in “/” and it makes no difference.

See Directory::get_directory_mut() for the mutable verison of this function.

Arguments

• pathname: the full pathname of the directory to fetch, taken as being relative to the current directory even if it starts with ‘/’

Return value

On success, this returns a reference to the named directory.

On failure, can return any number of errors from ImageError.

pub fn get_directory_opt( &self, pathname: &OsStr, ) -> Result<Option<&Directory<T>>, ImageError>

Like Self::get_directory() but maps ImageError::NotFound to Option.

pub fn get_directory_mut( &mut self, pathname: &OsStr, ) -> Result<&mut Directory<T>, ImageError>

Gets a mutable reference to a subdirectory of this directory.

This is the mutable version of Directory::get_directory().

pub fn split<'d, 'n>( &'d self, pathname: &'n OsStr, ) -> Result<(&'d Directory<T>, &'n OsStr), ImageError>

Splits a pathname into a directory and the filename within that directory. The directory must already exist. The filename within the directory may or may not exist.

This is the main entry point for most operations based on pathname. The expectation is that the returned filename will be used to perform a more concrete operation on the returned directory.

See Directory::get_directory() for more information about path traversal. See Directory::split_mut() for the mutable version of this function.

Arguments

• pathname: the full pathname to the file of interest

Return value

On success (the pathname is not invalid and the directory exists), returns a tuple of the Directory containing the file at the given path, and the basename of that file.

On failure, can return any number of errors from ImageError.

pub fn split_mut<'d, 'n>( &'d mut self, pathname: &'n OsStr, ) -> Result<(&'d mut Directory<T>, &'n OsStr), ImageError>

Splits a pathname into a directory and the filename within that directory. The directory must already exist. The filename within the directory may or may not exist.

This is the _mut version of Directory::split().

pub fn ref_leaf(&self, filename: &OsStr) -> Result<Rc<Leaf<T>>, ImageError>

Takes a reference to the “leaf” file (not directory) with the given filename directly contained in this directory. This is usually done in preparation for creating a hardlink or in order to avoid issues with the borrow checker when mutating the tree.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split() first.

Return value

On success (the entry exists and is not a directory) the Rc is cloned and a new reference is returned.

On failure, can return any number of errors from ImageError.

pub fn get_file<'a>(&'a self, filename: &OsStr) -> Result<&'a T, ImageError>

Obtains information about the regular file with the given filename directly contained in this directory.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split() first.

Return value

On success (the entry exists and is a regular file) then the return value is either:

• the inline data
• an external reference, with size information

On failure, can return any number of errors from ImageError.

pub fn get_file_opt<'a>( &'a self, filename: &OsStr, ) -> Result<Option<&'a T>, ImageError>

Like Self::get_file() but maps ImageError::NotFound to Option.

pub fn merge(&mut self, filename: &OsStr, inode: Inode<T>)

Inserts the given inode into the directory with special handling for directories. In case the inode is a directory and there is already a subdirectory with the given filename, the stat field will be updated with the value from the provided inode but the old directory entries will be left in place.

In all other cases, this function is equivalent to Directory::insert().

This is something like extracting an archive or an overlay: directories are merged with existing directories, but otherwise the new content replaces what was there before.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split() first.
• inode: the inode to store under the filename

pub fn insert(&mut self, filename: &OsStr, inode: Inode<T>)

Inserts the given inode into the directory.

If the filename existed previously, the content is completely overwritten, including the case that it was a directory.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split() first.
• inode: the inode to store under the filename

pub fn remove(&mut self, filename: &OsStr)

Removes the named file from the directory, if it exists. If it doesn’t exist, this is a no-op.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split() first.

pub fn lookup(&self, filename: &OsStr) -> Option<&Inode<T>>

Does a directory lookup on the given filename, returning the Inode if it exists.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split() first.

pub fn pop(&mut self, filename: &OsStr) -> Option<Inode<T>>

Removes an item from the directory, if it exists, returning the Inode value.

Arguments

• filename: the filename in the current directory. If you need to support full pathnames then you should call Directory::split_mut() first.

pub fn clear(&mut self)

Removes all content from this directory, making the directory empty. The stat data remains unmodified.

pub fn newest_file(&self) -> i64

Recursively finds the newest modification time in this directory tree.

Returns the maximum modification time among this directory’s metadata and all files and subdirectories it contains.

Trait Implementations

impl<T: Debug> Debug for Directory<T>

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

Formats the value using the given formatter.