MoReFEM::FilesystemNS Namespace Reference

Namespace that enclose filesystem utilities (check a folder do exist, remove a file, and so forth...) More...

Namespaces
namespace	DirectoryNS
	Placeholder namespace description needed for it to appear in Doxygen namespace list.
namespace	File
	Subnamespace to deal with files.
namespace	Folder
	Subnamespace to deal with folders.

Data Structures
class	Directory
	Class used to manage directories in MoReFEM. More...
class	File
	Class used in MoReFEM to represent files on the filesystem. More...

Enumerations
enum class	behaviour {   overwrite , ask , quit , read ,   create , create_if_necessary , ignore }
	Enum class to determine how to handle the case. More...
enum class	add_rank { no , yes }
	Whether a subdirectory with 'Rank_' + * rank id * must be added to the directory or not. More...
enum class	autocopy { yes , no }
	Convenient enum class for copy.
enum class	fail_if_already_exist { yes , no }
	Convenient enum class for copy.

Functions
std::ostream &	operator<< (std::ostream &out, behaviour rhs)
	Overload of operator<< for user-defined class.
std::ostream &	operator<< (std::ostream &out, const Directory &rhs)
	Overload of operator<< for user-defined class.
bool	IsSameDirectory (const Directory &lhs, const Directory &rhs)
	Check whether two Directory refers to the same directory on the filesystem.
Directory	GetRankDirectory (const Directory &root_directory, std::size_t rank)
	Create a Directory which contains path related to rank - where rank is NOT necessarily the one held by mpi object.
bool	IsFirstSubfolderOfSecond (const Directory &possible_enclosed_directory, const Directory &possible_enclosing_directory)
	Check whether possible_enclosed_directory is a directory inside possible_enclosing_directory.
bool	IsSameFile (const File &lhs, const File &rhs)
	Check whether two File refers to the same file on the filesystem.
std::ostream &	operator<< (std::ostream &out, const File &rhs)
	Overload of operator<< for user-defined class.
void	Copy (const File &source, const File &target, fail_if_already_exist do_fail_if_already_exist, autocopy allow_autocopy, const std::source_location location=std::source_location::current())
	Copy a file.
void	ConcatenateAsciiFiles (const std::vector< File > &file_list, const File &amalgamated_file, const std::source_location location=std::source_location::current())
	Concatenate several files assumed to be in ascii format.
bool	AreEquals (const File &lhs, const File &rhs, const std::source_location location=std::source_location::current())
	Check two files share exactly the same content.

Detailed Description

Namespace that enclose filesystem utilities (check a folder do exist, remove a file, and so forth...)

Enumeration Type Documentation

behaviour

enum class MoReFEM::FilesystemNS::behaviour

strong

Enum class to determine how to handle the case.

• overwrite: Remove the pre-existing one and recreate it.
• quit: Quit the program if the directory exists.
• read: this mode expects the directory to exist and throws an exception otherwise.
• create: create a new directory - it is expected here it doesn't exist yet (and an exception is thrown if it does).
• create_if_necessary: create the directory if it doesn't exist yet
• ask: Ask the end user if he wants to override or not. If he chooses not to do so, the program ends. Mpi is properly handled (the interface is properly rerouted to root processor which is the sole able to communicate with stdin).
• ignore: Do nothing - whether the directory exist or not. This might be useful if you want to set the behaviour later; I would nonetheless not recommend using this possibility much as we lose part of the appeal of using a class such as Directory doing so.

Remember that Directory constructor never acts directly on the filesystem; you need to call ActOnFilesystem method if you want an action on the filesystem (typically create a directory).

add_rank

enum class MoReFEM::FilesystemNS::add_rank

strong

Whether a subdirectory with 'Rank_' + * rank id * must be added to the directory or not.

This should be the standard case for output directories, but it is obviously not relevant for most of the input ones...

Function Documentation

operator<<() [1/3]

std::ostream & MoReFEM::FilesystemNS::operator<<	(	std::ostream &	out,
		behaviour	rhs )

Overload of operator<< for user-defined class.

Parameters

[in,out]	out	Output stream.
[in]	rhs	Object which content is to be written to output stream.

Returns

Output stream.

operator<<() [2/3]

std::ostream & MoReFEM::FilesystemNS::operator<<	(	std::ostream &	out,
		const Directory &	rhs )

Overload of operator<< for user-defined class.

Parameters

[in,out]	out	Output stream.
[in]	rhs	Object which content is to be written to output stream.

Returns

Output stream.

IsSameDirectory()

bool MoReFEM::FilesystemNS::IsSameDirectory	(	const Directory &	lhs,
		const Directory &	rhs )

Check whether two Directory refers to the same directory on the filesystem.

Parameters

[in]	lhs	First File object
[in]	rhs	Second File object

Returns

True of both actually shares the same path. If one is a symbolic link toward the other, false will be written: we really check only the lexicographic value of the path.

std::filesystem::equivalent() is not used as one of its prerequisite is that both files exist on the filesystem.

GetRankDirectory()

Directory MoReFEM::FilesystemNS::GetRankDirectory	(	const Directory &	root_directory,
		std::size_t	rank )

Create a Directory which contains path related to rank - where rank is NOT necessarily the one held by mpi object.

Attention

Should only be used on mpi root processor!

This is only for some specific functions and should be used with great care; behaviour is set to 'read' and should be changed with even greater care...

Parameters

[in]	root_directory	The directory matching the root rank.
[in]	rank	Rank for which the new directory is required.

Returns

The directory related to the chosen rank argument. It is created with the 'read' behaviour - and this one should changed with great care! (or better left unchanged).

IsFirstSubfolderOfSecond()

bool MoReFEM::FilesystemNS::IsFirstSubfolderOfSecond	(	const Directory &	possible_enclosed_directory,
		const Directory &	possible_enclosing_directory )

Check whether possible_enclosed_directory is a directory inside possible_enclosing_directory.

This function use the canonical path so is assumed to handle properly the symbolic links or relative paths.

Parameters

[in]	possible_enclosing_directory	The Directory that might be enclosed by the other.
[in]	possible_enclosed_directory	The Directory that might be enclosing by the other.

Returns

True if possible_enclosed_directory is inside possible_enclosing_directory

std::filesystem::path iterator doesn't behave as I want, so I perform the std::mismatch check upon the strings, not the folder parts. That is not very satisfactory and may prove to be brittle (even if of course I took all the precaution I could think of about the normalization of the path); see the implementation for more details put in a comment there.

IsSameFile()

bool MoReFEM::FilesystemNS::IsSameFile	(	const File &	lhs,
		const File &	rhs )

Check whether two File refers to the same file on the filesystem.

Friendship.

This is not a check upon the content: you are looking for AreEqual if you want to check that.

Parameters

[in]	lhs	First File object
[in]	rhs	Second File object

Returns

True of both actually shares the same path. If one is a symbolic link toward the other, false will be written: we really check only the lexicographic value of the path.

std::filesystem::equivalent() is not used as one of its prerequisite is that both files exist on the filesystem.

operator<<() [3/3]

std::ostream & MoReFEM::FilesystemNS::operator<<	(	std::ostream &	out,
		const File &	rhs )

Overload of operator<< for user-defined class.

Parameters

[in,out]	out	Output stream.
[in]	rhs	Object which content is to be written to output stream.

Returns

Output stream.

The underlying path of File class is written.

Copy()

void MoReFEM::FilesystemNS::Copy	(	const File &	source,
		const File &	target,
		fail_if_already_exist	do_fail_if_already_exist,
		autocopy	allow_autocopy,
		const std::source_location	location = std::source_location::current() )

Copy a file.

Friendship.

Parameters

[in]	source	Path of the source file.
[in]	target	Path of the target file.
[in]	do_fail_if_already_exist	If yes, the target must not exist yet.
[in]	allow_autocopy	If no, an exception is thrown is source is the same path as target. If yes, nothing is done. The reason for this is that I'm not sure underlying library Yuni can cope with this case. It will be replaced by future STL filesystem library that should be shipped along with C++17.

Parameters

[in]

location

STL object with relevant information about the calling site (usually to help when an exception is thrown.

Attention

This function is syntactic sugar for file or directory manipulation and has no pretension to handle by itself thread safety.

ConcatenateAsciiFiles()

void MoReFEM::FilesystemNS::ConcatenateAsciiFiles	(	const std::vector< File > &	file_list,
		const File &	amalgamated_file,
		const std::source_location	location = std::source_location::current() )

Concatenate several files assumed to be in ascii format.

Parameters

[in]	file_list	List of files to concatenate.
[out]	amalgamated_file	File into which the amalgated files are written.

Parameters

[in]

location

STL object with relevant information about the calling site (usually to help when an exception is thrown.

All files must be valid (or in a valid path for output one); if not an exception is raised.

Attention

This function is syntactic sugar for file or directory manipulation and has no pretension to handle by itself thread safety.

AreEquals()

bool MoReFEM::FilesystemNS::AreEquals	(	const File &	lhs,
		const File &	rhs,
		const std::source_location	location = std::source_location::current() )

Check two files share exactly the same content.

Friendship.

Parameters

[in]	lhs	Left-hand side.
[in]	rhs	Right-hand side.

Parameters

[in]

location

STL object with relevant information about the calling site (usually to help when an exception is thrown.

This function checks both files do exist first.

This code is lifted from https://stackoverflow.com/questions/6163611/compare-two-files with very small adaptation; http://www.cplusplus.com/forum/general/94032/ provides a Boost-dependent implementation which is seemingly more efficient.

Upcoming STL filesystem library doesn't seem to provide the functionality; currently it is used only for a test with very small files involved. So if this is deemed to be used more often and on much bigger file some profiling would be interesting here!

Returns

True if the files share exactly the same content.

Attention

This function is syntactic sugar for file or directory manipulation and has no pretension to handle by itself thread safety.