This section contains file management functions and classes. More...

Classes
struct	dirscan
	State management struct for directory scanning generators. More...

struct	fileHandle
	State management struct for file streaming generator. More...

class	info
	A class to allow a platform-independent way to get information on a file. More...

class	library
	A class for loading dynamic libraries. More...

class	unreadable
	Exception thrown when a file cannot be opened for reading. More...

class	unwritable
	Exception thrown when a file cannot be opened for writing. More...

Functions
zpath	basename (const zpath &path) noexcept
	Get the directory part of a file name.

bool	chdir (const zpath &path) noexcept
	Change the current working directory.

void	copy (const zpath &fileInput, const zpath &fileOutput)
	Copy data from one file to another.

zpath	dir () noexcept
	Get the current working directory.

zpath	dirname (const zpath &path) noexcept
	Get the directory part of a file name.

zpath	execdir () noexcept
	Get the directory path of the running executable.

zpath	executable () noexcept
	Get the full path of the running executable.

bool	exists (const zpath &pathname) noexcept
	Check whether a file or directory with the given name exists.

core::generator< zstring, fileHandle >	lines (const zpath &filename)
	Reads the contents of a file line-by-line.

core::generator< zstring, fileHandle >	lines (std::istream &stream) noexcept
	Reads the contents of a stream line-by-line.

core::generator< zpath, dirscan >	listFiles (const zpath &dir, const zpath &fileType="*", bool showAll=true) noexcept
	List all files of a given type in the given directory.

core::generator< zpath, dirscan >	listDirs (const zpath &dir, bool showAll=false) noexcept
	List all sub-directories in the given directory.

bool	makeDir (const zpath &dir) noexcept
	Make a directory with the given path.

zpath	path (const zpath &filePath) noexcept
	Get the full file path from a relative path.

zstring	read (const zpath &filename)
	Reads the entire contents of a specified file.

bool	remove (const zpath &filename) noexcept
	Remove a file from the filesystem.

zpath	shorten (const zpath &dir) noexcept
	Shorten the given directory string.

size_t	size (const zpath &path)
	Get the size of a file in bytes.

void	write (const zstring &contents, const zpath &filename, bool append=false)
	Writes the contents of a string to a specified file.

Detailed Description

This section contains file management functions and classes.

Function Documentation

◆ basename()

zpath z::file::basename ( const zpath & path )

noexcept

Get the directory part of a file name.

Returns: A string containing the directory above a given path.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

◆ chdir()

bool z::file::chdir ( const zpath & path )

noexcept

Change the current working directory.

Parameters

path	A string containing the new working directory.

Returns: true on success, false on failure.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

◆ copy()

void z::file::copy	(	const zpath &	fileInput,
		const zpath &	fileOutput
	)

Copy data from one file to another.

Parameters

fileInput	the path of the file to copy from.
fileOutput	the path of the file to copy to.

Exceptions

unreadable	if the input file could not be read.
unwritable	if the output file could not be written.

◆ dir()

zpath z::file::dir ( )

noexcept

Get the current working directory.

Returns: A string containing the current directory the executable is running from.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

◆ dirname()

zpath z::file::dirname ( const zpath & path )

noexcept

Get the directory part of a file name.

Returns: A string containing the directory above a given path.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

◆ execdir()

zpath z::file::execdir ( )

inlinenoexcept

Get the directory path of the running executable.

Returns: A string containing the directory of the currently running executable.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

Examples: file.cpp, lines.cpp, and loadLib.cpp.

◆ executable()

zpath z::file::executable ( )

noexcept

Get the full path of the running executable.

Returns: A string containing the path of the currently running executable.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

◆ exists()

bool z::file::exists ( const zpath & pathname )

noexcept

Check whether a file or directory with the given name exists.

Parameters

pathname the relative or absolute path of the file or directory.

Returns: True if the file or directory exists. False otherwise.

◆ lines() [1/2]

core::generator< zstring, fileHandle > z::file::lines ( const zpath & filename )

Reads the contents of a file line-by-line.

This function uses a generator to read files, which can be particularly useful with files that may be too large to load all at once.

Parameters

filename The path and name of the file to read from.

Exceptions

z::file::unreadable If the file cannot be opened or read from.

Examples: file.cpp, and lines.cpp.

◆ lines() [2/2]

core::generator< zstring, fileHandle > z::file::lines ( std::istream & stream )

noexcept

Reads the contents of a stream line-by-line.

This function uses a generator to read from an arbitrary stream, which may or may not be a file.

Parameters

stream The input stream to read from.

◆ listDirs()

core::generator< zpath, dirscan > z::file::listDirs	(	const zpath &	dir,
		bool	showAll = `false`
	)

noexcept

List all sub-directories in the given directory.

This function is meant to be a platform-independent way of allowing the user to get a list of all sub-directories in the given directory with the given file extension.

Parameters

dir	the working directory. If dir is "", then it is assumed to be the current working directory.
showAll	flag specifying whether to include hidden directories in the output.

Returns: A generator that will list all directories in the given directory.

◆ listFiles()

core::generator< zpath, dirscan > z::file::listFiles	(	const zpath &	dir,
		const zpath &	fileType = `"*"`,
		bool	showAll = `true`
	)

noexcept

List all files of a given type in the given directory.

This function is meant to be a platform-independent way of allowing the user to get a list of all files in the given directory with the given file extension.

Parameters

dir	the working directory. If dir is "", then it is assumed to be the current working directory.
fileType	the file extension. If the type is *""**, then all types are accepted. Otherwise, the file type is expected to have no leading period.
showAll	flag specifying whether to include hidden files in the output.

Returns: A generator that will list all files of the given type in the given directory.

◆ makeDir()

bool z::file::makeDir ( const zpath & dir )

noexcept

Make a directory with the given path.

This function is meant as a platform-independent way to create a new directory, for both Windows and Linux.

Parameters

dir	the desired path of the directory to make.

Returns: True if the directory was created successfully. False otherwise.

◆ path()

zpath z::file::path ( const zpath & filePath )

noexcept

Get the full file path from a relative path.

Parameters

filePath The path to a file object.

Returns: A string containing the full path to that file object.

Re-Entry: This function is thread-safe. Simultaneous calls will not cause data races.

◆ read()

zstring z::file::read ( const zpath & filename )

Reads the entire contents of a specified file.

Parameters

filename The path and name of the file to read from.

Exceptions

z::file::unreadable If the file cannot be opened or read from.

◆ remove()

bool z::file::remove ( const zpath & filename )

noexcept

Remove a file from the filesystem.

Parameters

filename the path of the file to remove.

Returns: True if the file was removed successfully. False otherwise.

◆ shorten()

zpath z::file::shorten ( const zpath & dir )

noexcept

Shorten the given directory string.

Removes any extra symbols from the given directory string. Extra slashes are removed, as well as redundant symbols like "/./". Unnecessary directory backtracking is also removed.
(e.g. "C:/a1/b1/../b2/foo.bar" -> "C:/a1/b2/foo.bar")

Parameters

dir	the given directory.

Returns: The directory with redundant symbols removed.

◆ size()

size_t z::file::size ( const zpath & path )

Get the size of a file in bytes.

Parameters

path	The file name.

Returns: The length of the file in bytes, or 0 if the file does not exist.

Exceptions

z::file::unreadable If the file cannot be opened or read from.

◆ write()

void z::file::write	(	const zstring &	contents,
		const zpath &	filename,
		bool	append = `false`
	)

Writes the contents of a string to a specified file.

On success, the entire contents of the file will be overwritten.

Parameters

contents	The contents to be written to the file.
filename	The path and name of the file to write to.
append	If true, appends to the file. Otherwise overwrites contents.

Exceptions

z::file::unwritable If the file cannot be opened or written to.

Classes

Functions

Detailed Description

Function Documentation

◆ basename()

◆ chdir()

◆ copy()

◆ dir()

◆ dirname()

◆ execdir()

◆ executable()

◆ exists()

◆ lines() [1/2]

◆ lines() [2/2]

◆ listDirs()

◆ listFiles()

◆ makeDir()

◆ path()

◆ read()

◆ remove()

◆ shorten()

◆ size()

◆ write()