This class represents a directory on the filesystem. More...

#include <lfilesystem_Directory.h>

Inheritance diagram for limes::files::Directory:

Classes
struct	Iterator
	An iterator class that allows iterating a directory like a standard C++ container. More...

Public Types
Typedefs
Typedefs for callbacks used by the functions that iterate through this directory's children.
using	FileCallback = std::function< void(const File &)>
	A callback for File objects. More...

using	DirectoryCallback = std::function< void(const Directory &)>
	A callback for Directory objects. More...

using	SymLinkCallback = std::function< void(const SymLink &)>
	A callback for SymLink objects. More...

using	FilesystemEntryCallback = std::function< void(const FilesystemEntry &)>
	A callback for FilesystemEntry objects. More...

Public Types inherited from limes::files::FilesystemEntry
using	PermOptions = std::filesystem::perm_options
	Options bitfield for setting permissions. More...

using	CopyOptions = std::filesystem::copy_options
	Options bitfield for copying. More...

using	Time = std::filesystem::file_time_type
	A time point used for filesystem time. More...

Public Member Functions
	Directory (const Directory &)=default

	Directory (Directory &&)=default

Iterator	begin () const
	Returns an iterator to the first entry in this directory. More...

bool	createIfDoesntExist () const noexcept final
	Creates the directory this object refers to, if it doesn't already exist. More...

Iterator	end () const
	Returns an iterator to the last entry in this directory. More...

	FilesystemEntry ()=default
	Creates a FilesystemEntry with an empty path. More...

	FilesystemEntry (const FilesystemEntry &)=default

	FilesystemEntry (const Path &pathToUse)
	Creates a FilesystemEntry referring to the specified path. More...

	FilesystemEntry (FilesystemEntry &&)=default

Path	getRelativePath (const Path &inputPath) const
	Returns the input path made relative to this directory's path. More...

Directory &	operator= (const Directory &)=default

Directory &	operator= (Directory &&)=default

Assignment
Directory &	operator= (const Path &newPath)
	Assigns this object to refer to a new path. More...

Directory &	operator= (const std::string_view &newPath)
	Assigns this object to refer to a new path. More...

Filesystem queries
bool	contains (const FilesystemEntry &entry, std::size_t depthLimit=50) const
	Returns true if this directory contains the passed FilesystemEntry. More...

bool	contains (const std::string_view &childName) const
	Returns true if this directory contains a child with the specified name. More...

bool	isEmpty () const
	Returns true if this directory contains no children. More...

std::uintmax_t	sizeInBytes () const final
	Returns the size of this directory, calculated as the cumulative size of all of this directory's contents, including all subdirectories recursively. More...

bool	isDirectory () const noexcept final
	Returns true if this directory contains the passed FilesystemEntry. More...

bool	isFile () const noexcept final
	Returns true if this directory contains the passed FilesystemEntry. More...

bool	isSymLink () const noexcept final
	Returns true if this directory contains the passed FilesystemEntry. More...

Child files
File	getChildFile (const std::string_view &filename, bool createIfNeeded=false) const
	Returns a File object representing a file in this directory with the specified name. More...

std::vector< File >	getChildFiles (bool recurse=true, bool includeHiddenFiles=true) const
	Returns all child files that exist in this directory. More...

void	iterateFiles (FileCallback &&callback, bool recurse=true, bool includeHiddenFiles=true) const
	Calls a function for each child file that exists in this directory. More...

Child subdirectories
bool	containsSubdirectories () const
	Returns true if this directory contains at least one subdirectory. More...

Directory	getChildDirectory (const std::string_view &subdirectoryName, bool createIfNeeded=false) const
	Returns a Directory object that represents a subdirectory of this one with the specified name. More...

std::vector< Directory >	getChildDirectories (bool recurse=true, bool includeHiddenFiles=true) const
	Returns all child directories that exist in this directory. More...

void	iterateDirectories (DirectoryCallback &&callback, bool recurse=true, bool includeHiddenFiles=true) const
	Calls a function for each child directory that exists in this directory. More...


SymLink	createChildSymLink (const std::string_view &symLinkName, const FilesystemEntry &symLinkTarget) const
	Child symbolic links. More...

std::vector< SymLink >	getChildSymLinks (bool recurse=true, bool includeHiddenFiles=true) const
	Returns all child symbolic links that exist in this directory. More...

void	iterateSymLinks (SymLinkCallback &&callback, bool recurse=true, bool includeHiddenFiles=true) const
	Calls a function for each child symbolic link that exists in this directory. More...

Other children functions
FilesystemEntry	getChild (const std::string_view &childName, bool createIfNeeded=false) const
	Returns a type-erased FilesystemEntry representing a filesystem object in this directory with the specified name. More...

std::vector< FilesystemEntry >	getAllChildren (bool recurse=true, bool includeHiddenFiles=true) const
	Returns all child filesystem entries that exist in this directory. More...

void	iterateAllChildren (FileCallback &&fileCallback, DirectoryCallback &&directoryCallback, SymLinkCallback &&symLinkCallback, bool recurse=true, bool includeHiddenFiles=true) const
	Iterates through all child objects of this directory, calling different callbacks for each object depending on if it is a file, directory, or symbolic link. More...

void	iterateAllChildren (FilesystemEntryCallback &&callback, bool recurse=true, bool includeHiddenFiles=true) const
	Iterates through all child objects of this directory, calling a single type-erased callback for each one. More...

The current working directory
bool	setAsWorkingDirectory () const
	Sets this directory as the current working directory. More...

bool	isCurrentWorkingDirectory () const
	Returns true if this directory is the system's current working directory. More...

Public Member Functions inherited from limes::files::FilesystemEntry
	FilesystemEntry (const FilesystemEntry &)=default

	FilesystemEntry (FilesystemEntry &&)=default

virtual	~FilesystemEntry ()=default
	Destructor. More...

bool	copyFrom (const FilesystemEntry &source, CopyOptions options=CopyOptions::update_existing) const noexcept

bool	copyFrom (const Path &source, CopyOptions options=CopyOptions::update_existing) const noexcept
	Overwriting. More...

FilesystemEntry &	operator= (const FilesystemEntry &)=default

FilesystemEntry &	operator= (FilesystemEntry &&)=default

bool	revealToUserInFileBrowser () const
	Uses the system's native file browser to display this file to the user. More...

	FilesystemEntry ()=default
	Creates a FilesystemEntry with an empty path. More...

	FilesystemEntry (const Path &pathToUse)
	Creates a FilesystemEntry referring to the specified path. More...

FilesystemEntry &	operator= (const Path &newPath)
	Assigns the path this filesystem entry represents. More...

FilesystemEntry &	operator= (const std::string_view &newPath)
	Assigns the path this filesystem entry represents. More...

FilesystemEntry &	assignPath (const Path &newPath) noexcept
	Assigns the path this filesystem entry represents. More...

bool	operator== (const FilesystemEntry &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator== (const Path &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator!= (const FilesystemEntry &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator!= (const Path &other) const noexcept
	Compares this filesystem entry's absolute path with the other one's for equality. More...

bool	operator< (const FilesystemEntry &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

bool	operator> (const FilesystemEntry &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

bool	operator< (const Path &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

bool	operator> (const Path &other) const noexcept
	Lexicographically compares this filesystem entry's absolute path with another path. More...

FilesystemEntry	operator/ (const std::string_view &subpathName) const
	Returns a new FilesystemEntry referring to a subpath of this one. More...

FilesystemEntry &	operator/= (const std::string_view &subpathName)
	Assigns this object's path to a subpath of the current path. More...

FilesystemEntry &	changeName (const std::string_view &newName)
	Changes the last section of the path (the filename). More...

bool	makeAbsoluteRelativeTo (const Path &basePath) noexcept
	If the path this object holds is already absolute, this function does nothing and returns false. More...

bool	makeAbsoluteRelativeToCWD () noexcept
	Similar to `makeAbsoluteRelativeTo()`, but uses the current working directory as the base path. More...

Path	getPath (bool makePreferred=false) const noexcept
	Returns the current path held by this object. More...

Path	getAbsolutePath (bool makePreferred=false) const noexcept
	Returns the full, absolute path of this filesystem entry. More...

	operator Path () const noexcept
	Converts this filesystem entry to the path it holds. More...

std::string	getName () const noexcept
	Returns the last section of the path (the filename). More...

Directory	getDirectory () const
	Returns the directory containing this filesystem entry. More...

Directory	getParentDirectory () const
	Returns the parent directory of this filesystem entry. More...

bool	isBelow (const Directory &directory, std::size_t depthLimit=50) const
	Returns true if this filesystem entry is in a subdirectory of the given `directory` – ie, if that directory is a parent or grandparent of this filepath. More...

bool	isAbsolutePath () const noexcept
	Returns true if the path this object holds is an absolute path. More...

bool	isRelativePath () const noexcept
	Returns true if the path this object holds is a relative path. More...

bool	isValid () const noexcept
	Returns true if this object holds a valid filesystem path. More...

bool	isHidden () const
	Returns true if this path is a hidden file or directory. More...

FilesystemEntry	getSibling (const std::string_view &siblingName) const
	Returns a filesystem entry with the given name in the same directory as this one. More...

bool	exists () const noexcept
	Returns true if the filesystem object this object refers to exists on disk. More...

	operator bool () const noexcept
	Returns true if this filesystem object exists. More...

Time	getLastModificationTime () const noexcept
	Returns the last modification time of the filesystem entry. More...

std::optional< Volume >	getVolume () const noexcept
	Returns a Volume object representing the logical filesystem volume that this object exists on. More...

std::optional< File >	getFileObject () const noexcept
	If this object refers to a file, constructs a File object referring to the same file. More...

std::optional< Directory >	getDirectoryObject () const noexcept
	If this object refers to a directory, constructs a Directory object referring to the same directory. More...

std::optional< SymLink >	getSymLinkObject () const noexcept
	If this object refers to a symbolic link, constructs a SymLink object referring to the same link. More...

bool	deleteIfExists () const noexcept
	Deletes the filesystem entry this object refers to, if it exists. More...

bool	moveToTrash () noexcept
	Attempts to move this filesystem object to the system's trash folder. More...

void	touch () const
	If the filesystem entry this object refers do doesn't exist, this function creates it. More...

bool	touch_noCreate () const
	The same as `touch()` , except this function does not create the filesystem entry if it didn't already exist. More...

bool	rename (const Path &newPath) noexcept
	Renames this filesystem object to a new path. More...

bool	setPermissions (FSPerms permissions, PermOptions options=PermOptions::replace) const noexcept
	Sets the permissions for the filesystem entry. More...

Permissions	getPermissions () const
	Returns the current permissions of the filesystem entry this object refers to. More...

bool	copyTo (const Path &dest, CopyOptions options=CopyOptions::update_existing) const noexcept
	Creates a copy of this filesystem entry at a new location on disk. More...

bool	copyTo (const FilesystemEntry &dest, CopyOptions options=CopyOptions::update_existing) const noexcept
	Creates a copy of this filesystem entry at a new location on disk. More...

std::optional< FilesystemEntry >	copyToDirectory (const Path &destDirectory, CopyOptions options=CopyOptions::update_existing) const noexcept
	Creates a copy of this filesystem object, with the same filename, in a different directory. More...

Additional Inherited Members
Related Functions inherited from limes::files::FilesystemEntry
std::ostream &	operator<< (std::ostream &os, const FilesystemEntry &value)
	Writes a FilesystemEntry's path to the output stream. More...

Detailed Description

This class represents a directory on the filesystem.

This class provides a high-level API for treating directories almost like containers, with methods for iterating over its children.

For example, this code prints all filenames present in a directory and all its subdirectories:

const limes::files::Directory dir { "/my/directory" };
 
dir.iterateFiles ([](const limes::files::File& f){ std::cout << f.getFilename() });

Todo:: getNonexistentChild()

Examples: files_dir_listen.cpp.

Definition at line 53 of file lfilesystem_Directory.h.

Member Typedef Documentation

◆ DirectoryCallback

using limes::files::Directory::DirectoryCallback = std::function<void (const Directory&)>

A callback for Directory objects.

Definition at line 73 of file lfilesystem_Directory.h.

◆ FileCallback

using limes::files::Directory::FileCallback = std::function<void (const File&)>

A callback for File objects.

Definition at line 70 of file lfilesystem_Directory.h.

◆ FilesystemEntryCallback

using limes::files::Directory::FilesystemEntryCallback = std::function<void (const FilesystemEntry&)>

A callback for FilesystemEntry objects.

Definition at line 79 of file lfilesystem_Directory.h.

◆ SymLinkCallback

using limes::files::Directory::SymLinkCallback = std::function<void (const SymLink&)>

A callback for SymLink objects.

Definition at line 76 of file lfilesystem_Directory.h.

Member Function Documentation

◆ begin()

Iterator limes::files::Directory::begin ( ) const

Returns an iterator to the first entry in this directory.

◆ contains() [1/2]

bool limes::files::Directory::contains	(	const FilesystemEntry &	entry,
		std::size_t	depthLimit = `50`
	)		const

Returns true if this directory contains the passed FilesystemEntry.

Parameters

depthLimit Specifies the number of parent paths of the entry that will be checked for equivalence to this directory . Setting this to 1 will only allow this function to return true if this is the immediate parent directory of entry ; 2 would return true this is the entry's directory or that directory's parent directory, etc.

See also: FilesystemEntry::isBelow()

Examples: files_dir_listen.cpp.

◆ contains() [2/2]

bool limes::files::Directory::contains ( const std::string_view & childName ) const

Returns true if this directory contains a child with the specified name.

Note: This function is not recursive; this only searches this directory's immediate children for a matching filename.

◆ containsSubdirectories()

bool limes::files::Directory::containsSubdirectories ( ) const

Returns true if this directory contains at least one subdirectory.

◆ createChildSymLink()

SymLink limes::files::Directory::createChildSymLink	(	const std::string_view &	symLinkName,
		const FilesystemEntry &	symLinkTarget
	)		const

Child symbolic links.

Returns a SymLink object that represents a symbolic link in the current directory with the specified name. Note that this function always creates the symbolic link if it doesn't exist.

Exceptions

std::runtime_error An exception will be thrown if creating the symbolic link fails.

See also: getChild()

◆ createIfDoesntExist()

bool limes::files::Directory::createIfDoesntExist ( ) const

finalvirtualnoexcept

Creates the directory this object refers to, if it doesn't already exist.

Returns: True if the directory needed to be created, and was successfully created. False if the directory already existed.

Reimplemented from limes::files::FilesystemEntry.

◆ end()

Iterator limes::files::Directory::end ( ) const

Returns an iterator to the last entry in this directory.

◆ FilesystemEntry() [1/2]

limes::files::FilesystemEntry::FilesystemEntry

default

Creates a FilesystemEntry with an empty path.

After creating a FilesystemEntry with this default constructor, calling isValid() on it will return false. You can use the assignPath() function to assign this object to a path after it has been constructed.

◆ FilesystemEntry() [2/2]

limes::files::FilesystemEntry::FilesystemEntry

explicit

Creates a FilesystemEntry referring to the specified path.

Parameters

pathToUse The path to this filesystem entry. This can be an absolute or relative path, and it is not an error if the passed path doesn't actually exist on disk. The path will be normalized using the normalizePath() function.

◆ getAllChildren()

std::vector<FilesystemEntry> limes::files::Directory::getAllChildren	(	bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Returns all child filesystem entries that exist in this directory.

See also: iterateAllChildren(), getChild()

◆ getChild()

FilesystemEntry limes::files::Directory::getChild	(	const std::string_view &	childName,
		bool	createIfNeeded = `false`
	)		const

Returns a type-erased FilesystemEntry representing a filesystem object in this directory with the specified name.

See also: getChildFile(), getChildDirectory(), createChildSymLink(), getAllChildren()

◆ getChildDirectories()

std::vector<Directory> limes::files::Directory::getChildDirectories	(	bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Returns all child directories that exist in this directory.

See also: iterateDirectories()

◆ getChildDirectory()

Directory limes::files::Directory::getChildDirectory	(	const std::string_view &	subdirectoryName,
		bool	createIfNeeded = `false`
	)		const

Returns a Directory object that represents a subdirectory of this one with the specified name.

See also: getChild()

◆ getChildFile()

File limes::files::Directory::getChildFile	(	const std::string_view &	filename,
		bool	createIfNeeded = `false`
	)		const

Returns a File object representing a file in this directory with the specified name.

See also: getChild()

Examples: files_dir_enumerate.cpp.

◆ getChildFiles()

std::vector<File> limes::files::Directory::getChildFiles	(	bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Returns all child files that exist in this directory.

See also: iterateFiles()

◆ getChildSymLinks()

std::vector<SymLink> limes::files::Directory::getChildSymLinks	(	bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Returns all child symbolic links that exist in this directory.

See also: iterateSymLinks()

◆ getRelativePath()

Path limes::files::Directory::getRelativePath ( const Path & inputPath ) const

Returns the input path made relative to this directory's path.

For example:

const limes::files::Directory dir { "/path/to/a/directory" };
 
const auto path = dir.getRelativePath ("/path/to/a/directory/with/nested/subdirs/and/filename.txt");
 
assert (path == "with/nested/subdirs/and/filename.txt");

◆ isCurrentWorkingDirectory()

bool limes::files::Directory::isCurrentWorkingDirectory ( ) const

Returns true if this directory is the system's current working directory.

See also: setAsWorkingDirectory(), dirs::cwd()

◆ isDirectory()

bool limes::files::Directory::isDirectory ( ) const

finalvirtualnoexcept

Returns true if this directory contains the passed FilesystemEntry.

Parameters

depthLimit Specifies the number of parent paths of the entry that will be checked for equivalence to this directory . Setting this to 1 will only allow this function to return true if this is the immediate parent directory of entry ; 2 would return true this is the entry's directory or that directory's parent directory, etc.

See also: FilesystemEntry::isBelow()

Reimplemented from limes::files::FilesystemEntry.

◆ isEmpty()

bool limes::files::Directory::isEmpty ( ) const

Returns true if this directory contains no children.

◆ isFile()

bool limes::files::Directory::isFile ( ) const

finalvirtualnoexcept

Returns true if this directory contains the passed FilesystemEntry.

Parameters

depthLimit Specifies the number of parent paths of the entry that will be checked for equivalence to this directory . Setting this to 1 will only allow this function to return true if this is the immediate parent directory of entry ; 2 would return true this is the entry's directory or that directory's parent directory, etc.

See also: FilesystemEntry::isBelow()

Reimplemented from limes::files::FilesystemEntry.

◆ isSymLink()

bool limes::files::Directory::isSymLink ( ) const

finalvirtualnoexcept

Returns true if this directory contains the passed FilesystemEntry.

Parameters

depthLimit Specifies the number of parent paths of the entry that will be checked for equivalence to this directory . Setting this to 1 will only allow this function to return true if this is the immediate parent directory of entry ; 2 would return true this is the entry's directory or that directory's parent directory, etc.

See also: FilesystemEntry::isBelow()

Reimplemented from limes::files::FilesystemEntry.

◆ iterateAllChildren() [1/2]

void limes::files::Directory::iterateAllChildren	(	FileCallback &&	fileCallback,
		DirectoryCallback &&	directoryCallback,
		SymLinkCallback &&	symLinkCallback,
		bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Iterates through all child objects of this directory, calling different callbacks for each object depending on if it is a file, directory, or symbolic link.

It is not an error for any of these callbacks to be nullptr .

See also: getAllChildren()

Todo:: test coverage

◆ iterateAllChildren() [2/2]

void limes::files::Directory::iterateAllChildren	(	FilesystemEntryCallback &&	callback,
		bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Iterates through all child objects of this directory, calling a single type-erased callback for each one.

See also: getAllChildren()

Todo:: test coverage

◆ iterateDirectories()

void limes::files::Directory::iterateDirectories	(	DirectoryCallback &&	callback,
		bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Calls a function for each child directory that exists in this directory.

See also: getChildDirectories()

Todo:: test coverage

◆ iterateFiles()

void limes::files::Directory::iterateFiles	(	FileCallback &&	callback,
		bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Calls a function for each child file that exists in this directory.

See also: getChildFiles()

Todo:: test coverage

Examples: files_dir_enumerate.cpp.

◆ iterateSymLinks()

void limes::files::Directory::iterateSymLinks	(	SymLinkCallback &&	callback,
		bool	recurse = `true`,
		bool	includeHiddenFiles = `true`
	)		const

Calls a function for each child symbolic link that exists in this directory.

See also: getChildSymLinks()

Todo:: test coverage

◆ operator=() [1/2]

Directory& limes::files::Directory::operator= ( const Path & newPath )

Assigns this object to refer to a new path.

Todo:: test coverage

◆ operator=() [2/2]

Directory& limes::files::Directory::operator= ( const std::string_view & newPath )

Assigns this object to refer to a new path.

Todo:: test coverage

◆ setAsWorkingDirectory()

bool limes::files::Directory::setAsWorkingDirectory ( ) const

Sets this directory as the current working directory.

See also: isCurrentWorkingDirectory(), dirs::setCWD()

Todo:: test coverage

◆ sizeInBytes()

std::uintmax_t limes::files::Directory::sizeInBytes ( ) const

finalvirtual

Returns the size of this directory, calculated as the cumulative size of all of this directory's contents, including all subdirectories recursively.

Reimplemented from limes::files::FilesystemEntry.

The documentation for this class was generated from the following file:

lfilesystem_Directory.h

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ DirectoryCallback

◆ FileCallback

◆ FilesystemEntryCallback

◆ SymLinkCallback

Member Function Documentation

◆ begin()

◆ contains() [1/2]

◆ contains() [2/2]

◆ containsSubdirectories()

◆ createChildSymLink()

◆ createIfDoesntExist()

◆ end()

◆ FilesystemEntry() [1/2]

◆ FilesystemEntry() [2/2]

◆ getAllChildren()

◆ getChild()

◆ getChildDirectories()

◆ getChildDirectory()

◆ getChildFile()

◆ getChildFiles()

◆ getChildSymLinks()

◆ getRelativePath()

◆ isCurrentWorkingDirectory()

◆ isDirectory()

◆ isEmpty()

◆ isFile()

◆ isSymLink()

◆ iterateAllChildren() [1/2]

◆ iterateAllChildren() [2/2]

◆ iterateDirectories()

◆ iterateFiles()

◆ iterateSymLinks()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ setAsWorkingDirectory()

◆ sizeInBytes()