Various file system utilities

Files
file	fileUtils.hpp
	Declarations of utilities for working with files.

file	fileUtils.cpp
	Definitions of utilities for working with files.

Functions
template<class verboseT >
error_t	mx::ioutils::string2path (std::filesystem::path &path, const std::string &str)
	Convert a string to a path, handling exceptions.

template<class verboseT = verbose::d>
bool	mx::ioutils::exists (const std::string &path, mx::error_t &errc)
	Check if a path exists.

template<class verboseT = verbose::d>
bool	mx::ioutils::dir_exists_is (const std::string &dir, mx::error_t &errc)
	Check if a path exists and is a directory.

error_t	mx::ioutils::createDirectories (const std::string &path)
	Create a directory or directories.

std::string	mx::ioutils::pathStem (const std::string &fname)
	Get the stem of the filename.

std::string	mx::ioutils::pathFilename (const std::string &fname)
	Get the base filename.

std::string	mx::ioutils::parentPath (const std::string &fname)
	Get the parent path from a filename.

template<class verboseT = verbose::d>
error_t	mx::ioutils::getFileNames (std::vector< std::string > &fileNames, const std::string &directory, const std::string &prefix, const std::string &substr, const std::string &extension)
	Get a list of file names from the specified directory, specifying a prefix, a substring to match, and an extension.

std::string	mx::ioutils::fileNamePrependAppend (const std::string &fname, const std::string &prepend, const std::string &append)
	Prepend and/or append strings to a file name, leaving the directory and extension unaltered.

std::string	mx::ioutils::fileNameAppend (const std::string &fname, const std::string &append)
	Append a string to a file name, leaving the directory and extension unaltered.

std::string	mx::ioutils::fileNamePrepend (const std::string &fname, const std::string &prepend)
	Prepend strings to a file name, leaving the directory and extension unaltered.

std::string	mx::ioutils::getSequentialFilename (const std::string &basename, const std::string &extension="", const int startat=0, int ndigit=4)
	Get the next file in a numbered sequence.

off_t	mx::ioutils::fileSize (int fd)
	Get the size in bytes of a file.

off_t	mx::ioutils::fileSize (FILE *f)
	Get the size in bytes of a file pointed to by a FILE pointer.

Function Documentation

◆ createDirectories()

error_t mx::ioutils::createDirectories ( const std::string & path )

Create a directory or directories.

This will create any directories in path that don't exist. It silently ignores already existing directories.

Returns: error_t::noerror on success, indicating the directories were created or already existed.; other codes, error_t::exxxx (from errno) or error_t::filesystem, on errors.

Parameters

[in] path the path of the directory(ies)to create

Definition at line 54 of file fileUtils.cpp.

References mx::errno2error_t(), mx::error, mx::filesystem, and mx::noerror.

Referenced by mx::AO::analysis::fourierTemporalPSD< _realT, aosysT >::analyzePSDGrid(), mx::AO::path::dm::basisRoot(), mx::AO::path::dm::M2c(), mx::AO::path::dm::projectedModes(), mx::AO::path::basis::root(), mx::AO::path::dm::root(), mx::AO::path::pupil::root(), mx::AO::path::sys::root(), mx::AO::path::sys::cal::root(), and mx::AO::path::sys::cal::sysResp().

◆ dir_exists_is()

template<class verboseT = verbose::d>

bool mx::ioutils::dir_exists_is	(	const std::string &	dir,
		mx::error_t &	errc
	)

Check if a path exists and is a directory.

Returns: true only if dir both exists and is a directory, and no errors occur; false otherwise

Parameters

[in]	dir	the path to check
[out]	errc	error code. Typically convereted as errno from std::filesystem

Definition at line 311 of file fileUtils.hpp.

References mx::exception< verboseT >::code(), mx::ioutils::dir_exists_is(), mx::errno2error_t(), mx::error, mx::ioutils::exists(), and mx::filesystem.

Referenced by mx::ioutils::dir_exists_is(), and unitTest::ioutilsTest::fileUtilsTest::TEST_CASE().

◆ exists()

template<class verboseT = verbose::d>

bool mx::ioutils::exists	(	const std::string &	path,
		mx::error_t &	errc
	)

Check if a path exists.

Returns: true if the path exists and no errors occur; false otherwise

Parameters

[in]	path	the path to check for existence
[out]	errc	error code. Typically convereted as errno from std::filesystem

Definition at line 270 of file fileUtils.hpp.

References mx::exception< verboseT >::code(), mx::errno2error_t(), and mx::ioutils::exists().

Referenced by mx::ioutils::dir_exists_is(), and mx::ioutils::exists().

◆ fileNameAppend()

std::string mx::ioutils::fileNameAppend	(	const std::string &	fname,
		const std::string &	append
	)

Append a string to a file name, leaving the directory and extension unaltered.

Returns: the new file name

Parameters

[in]	fname	the original file name, possibly including a directory and extension
[in]	append	is the string to insert at the end of the file name, before the extension

Definition at line 114 of file fileUtils.cpp.

References mx::ioutils::fileNamePrependAppend().

◆ fileNamePrepend()

std::string mx::ioutils::fileNamePrepend	(	const std::string &	fname,
		const std::string &	prepend
	)

Prepend strings to a file name, leaving the directory and extension unaltered.

Returns: the new file name

Parameters

[in]	fname	the original file name, possibly including a directory and extension
[in]	prepend	is the string to insert at the beginning of the file name after the path

Definition at line 119 of file fileUtils.cpp.

References mx::ioutils::fileNamePrependAppend().

◆ fileNamePrependAppend()

std::string mx::ioutils::fileNamePrependAppend	(	const std::string &	fname,
		const std::string &	prepend,
		const std::string &	append
	)

Prepend and/or append strings to a file name, leaving the directory and extension unaltered.

Returns: the new file name

Parameters

[in]	fname	the original file name, possibly including a directory and extension
[in]	prepend	is the string to insert at the beginning of the file name after the path
[in]	append	is the string to insert at the end of the file name, before the extension

Definition at line 102 of file fileUtils.cpp.

Referenced by mx::ioutils::fileNameAppend(), and mx::ioutils::fileNamePrepend().

◆ fileSize() [1/2]

off_t mx::ioutils::fileSize ( FILE * f )

Get the size in bytes of a file pointed to by a FILE pointer.

Uses fileno to get the associated descriptor, then uses fstat.

Returns: the file size if fd is valid and no errors occur; -1 on an error

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

[in] f an open file

Definition at line 178 of file fileUtils.cpp.

References mx::ioutils::fileSize().

◆ fileSize() [2/2]

off_t mx::ioutils::fileSize ( int fd )

Get the size in bytes of a file.

Uses fstat.

Returns: the file size if fd is valid and no errors occur; -1 on an error

Parameters

[in] fd an open file descriptor

Definition at line 161 of file fileUtils.cpp.

Referenced by mx::ioutils::fileSize().

◆ getFileNames()

template<class verboseT = verbose::d>

error_t mx::ioutils::getFileNames	(	std::vector< std::string > &	fileNames,
		const std::string &	directory,
		const std::string &	prefix,
		const std::string &	substr,
		const std::string &	extension
	)

Get a list of file names from the specified directory, specifying a prefix, a substring to match, and an extension.

Returns: mx::error_t::success on success; mx::error_t::invalidarg if directory is not a directory; mx::error_t::dirnotfound if directory does not exist; mx::error_t::exception if an exception is thrown from the standard library

Template Parameters

verbose if true then error messages are printed as they occur

Parameters

[out]	directory	The populated list of file names. [in] The path to the directory to search. Can not be empty.
[in]	prefix	The file name prefix (the beginning characters of the file name) to search for. If "" then not used.
[in]	substr	A substring of the filename to search for. If "" then not used. Only matches after the first character.
[in]	extension	The file name extension to search for. If "" then not used. This does not need to include the ".", as in".ext".

Definition at line 384 of file fileUtils.hpp.

References mx::ioutils::getFileNames().

Referenced by mx::ioutils::getFileNames(), and unitTest::ioutilsTest::fileUtilsTest::TEST_CASE().

◆ getSequentialFilename()

std::string mx::ioutils::getSequentialFilename	(	const std::string &	basename,
		const std::string &	extension = `""`,
		const int	startat = `0`,
		int	ndigit = `4`
	)

Get the next file in a numbered sequence.

Searches for files in the path designated by basename of the form basenameXXXXextension where the number of digits in XXXX is set by the ndigit parameter.

Warning: this does not currently detect missing files in the sequence, e.g. if you have 0,1,3 in the directory this will start with 2!

Todo:: switch to using a regex or something so we can detect the missing file.

Return values

std::string containing the next filename.

Parameters

[in]	basename	path and initial name of the file*‍/
[in]	extension	[optional] extension to append after the number. Default is empty.
[in]	startat	[optional] number to start the search from. Default is 0.
[in]	ndigit	[optional] number of digits in string representation of the number.Default is 4.

Definition at line 125 of file fileUtils.cpp.

Referenced by unitTest::ioutilsTest::fileUtilsTest::TEST_CASE().

◆ parentPath()

std::string mx::ioutils::parentPath ( const std::string & fname )

Get the parent path from a filename.

Returns: the parent path of the file

Definition at line 84 of file fileUtils.cpp.

Referenced by mx::astro::phoenixSpectrum< _units >::readSpectrum(), and mx::astro::rewritePhoenixSpectrum().

◆ pathFilename()

std::string mx::ioutils::pathFilename ( const std::string & fname )

Get the base filename.

Returns: the filename, including the extension but without the path

Definition at line 78 of file fileUtils.cpp.

Referenced by mx::sys::gitRepo::getGitName().

◆ pathStem()

std::string mx::ioutils::pathStem ( const std::string & fname )

Get the stem of the filename.

Returns: the stem for the filename, that is without the path or extension

Definition at line 72 of file fileUtils.cpp.

◆ string2path()

template<class verboseT >

error_t mx::ioutils::string2path	(	std::filesystem::path &	path,
		const std::string &	str
	)

Convert a string to a path, handling exceptions.

Wrapper for path = str assignment that handles exceptions and implements mxlib standard error handling.

Returns: error_t::noerror if no exceptions; error_t::std_bad_alloc if std::bad_alloc is caught; error_t::std_filesystem_error if std::filesystem::filesystem_error is caught; error_t::std_exception if any other exceptions are caught

Exceptions

a	nested mx::exception for any uncaught exceptions.

Definition at line 219 of file fileUtils.hpp.

References mx::ioutils::string2path().

Referenced by mx::ioutils::string2path().

Files

Functions

Function Documentation

◆ createDirectories()

◆ dir_exists_is()

◆ exists()

◆ fileNameAppend()

◆ fileNamePrepend()

◆ fileNamePrependAppend()

◆ fileSize() [1/2]

◆ fileSize() [2/2]

◆ getFileNames()

◆ getSequentialFilename()

◆ parentPath()

◆ pathFilename()

◆ pathStem()

◆ string2path()