Execute fs operations { exists, copy, delete } for { files and directories }. More...

#include <FileSystem.h>

Classes
struct	CopyOperation
	Specify source, destination and flags for a copy operation. More...

struct	Operations
	Low level filesystem API, requiring paths in native encoding (UTF-16 on Windows, UTF-8 elsewhere) More...

Public Types
using	AccessMode = FileSystemAccessMode
	Access mode for path checks.

using	CopyFlags = FileSystemCopyFlags
	Specify copy options like overwriting existing files.

using	FileStat = FileSystemStat
	A structure to describe modified time.

Public Member Functions
ResultFileSystem	init (StringSpan initialDirectory)
	Call init function when instantiating the class to set directory for all operations using relative paths.

ResultFileSystem	changeDirectory (StringSpan newDirectory)
	Changes current directory.

ResultFileSystem	copyFiles (Span< const CopyOperation > sourceDestination)
	Copies many files.

ResultFileSystem	copyFile (StringSpan source, StringSpan destination, CopyFlags copyFlags=CopyFlags())
	Copy a single file.

ResultFileSystem	copyDirectories (Span< const CopyOperation > sourceDestination)
	Copy many directories.

ResultFileSystem	copyDirectory (StringSpan source, StringSpan destination, CopyFlags copyFlags=CopyFlags())
	Copy a single directory.

ResultFileSystem	rename (StringSpan path, StringSpan newPath)
	Rename a file or directory.

ResultFileSystem	removeFiles (Span< const StringSpan > files)
	Remove multiple files.

ResultFileSystem	removeFile (StringSpan source)
	Remove a single file.

ResultFileSystem	removeFileIfExists (StringSpan source)
	Remove a single file, giving no error if it doesn't exist.

ResultFileSystem	removeLinkIfExists (StringSpan source)
	Remove a single link, giving no error if it doesn't exist.

ResultFileSystem	removeDirectoriesRecursive (Span< const StringSpan > directories)
	Remove multiple directories with their entire content (like posix `rm -rf`)

ResultFileSystem	removeDirectoryRecursive (StringSpan directory)
	Remove single directory with its entire content (like posix `rm -rf`)

ResultFileSystem	removeEmptyDirectories (Span< const StringSpan > directories)
	Removes multiple empty directories.

ResultFileSystem	removeEmptyDirectory (StringSpan directory)
	Removes an empty directory.

ResultFileSystem	makeDirectories (Span< const StringSpan > directories)
	Creates new directories that do not already exist.

ResultFileSystem	makeDirectory (StringSpan directory)
	Creates a new directory that does not already exist.

ResultFileSystem	makeDirectoriesIfNotExists (Span< const StringSpan > directories)
	Creates new directories, if they don't already exist at the given path.

ResultFileSystem	makeDirectoryIfNotExists (StringSpan directory)
	Creates a new directory, if it doesn't already exists at the given path.

ResultFileSystem	makeDirectoriesRecursive (Span< const StringSpan > directories)
	Create new directories, creating also intermediate non existing directories (like posix `mkdir -p`)

ResultFileSystem	makeDirectoryRecursive (StringSpan directory)
	Create a new directory, creating also intermediate non existing directories (like posix `mkdir -p`)

ResultFileSystem	createSymbolicLink (StringSpan sourceFileOrDirectory, StringSpan linkFile)
	Creates a symbolic link at location linkFile pointing at sourceFileOrDirectory.

ResultFileSystem	createHardLink (StringSpan sourceFile, StringSpan linkFile)
	Creates a hard link at location linkFile pointing at sourceFile.

bool	exists (StringSpan fileOrDirectory)
	Check if a file or directory exists at a given path.

ResultFileSystem	exists (StringSpan fileOrDirectory, bool &doesExist)
	Detailed query: a missing entry is a successful false answer; validation and I/O failures are errors.

bool	existsAndIsDirectory (StringSpan directory)
	Check if a directory exists at given path.

ResultFileSystem	existsAndIsDirectory (StringSpan directory, bool &isDirectory)
	Detailed query: absence or another entry type is a successful false answer.

bool	existsAndIsFile (StringSpan file)
	Check if a file exists at given path.

ResultFileSystem	existsAndIsFile (StringSpan file, bool &isFile)
	Detailed query: absence or another entry type is a successful false answer.

bool	existsAndIsLink (StringSpan file)
	Check if a link exists at given path.

ResultFileSystem	existsAndIsLink (StringSpan file, bool &isLink)
	Detailed query: absence or another entry type is a successful false answer.

bool	canAccess (StringSpan fileOrDirectory, AccessMode accessMode=AccessMode::Exists)
	Check whether the current process can access a path with the requested mode.

ResultFileSystem	canAccess (StringSpan fileOrDirectory, AccessMode accessMode, bool &canAccessPath)
	Detailed query: denied access or absence is a successful false answer.

ResultFileSystem	moveDirectory (StringSpan sourceDirectory, StringSpan destinationDirectory)
	Moves a directory from source to destination.

ResultFileSystem	write (StringSpan file, Span< const char > data)
	Writes a block of memory to a file.

ResultFileSystem	write (StringSpan file, Span< const uint8_t > data)

ResultFileSystem	writeString (StringSpan file, StringSpan text)
	Replace the entire content of a file with the provided StringSpan.

ResultFileSystem	writeStringAppend (StringSpan file, StringSpan text)
	Appends a StringSpan to a file.

template<typename T >
ResultFileSystem	read (StringSpan file, T &data)
	Read contents of a file into a String or Buffer.

ResultFileSystem	read (StringSpan file, IGrowableBuffer &&buffer)
	Read contents of a file into an IGrowableBuffer.

ResultFileSystem	stat (StringSpan file, FileStat &fileStat)
	Obtains richer metadata about a path, following symbolic links.

ResultFileSystem	lstat (StringSpan file, FileStat &fileStat)
	Obtains richer metadata about a path without following symbolic links.

ResultFileSystem	getFileStat (StringSpan file, FileStat &fileStat)
	Legacy convenience alias for stat(StringSpan, FileStat&)

ResultFileSystem	readSymbolicLink (StringSpan linkFile, StringPath &destination)
	Reads the target path stored by a symbolic link.

ResultFileSystem	chmod (StringSpan path, uint32_t mode)
	Change file permission bits for a path, following symbolic links.

ResultFileSystem	chown (StringSpan path, uint32_t uid, uint32_t gid)
	Change owner and group for a path, following symbolic links.

ResultFileSystem	lchown (StringSpan path, uint32_t uid, uint32_t gid)
	Change owner and group for a path without following symbolic links.

ResultFileSystem	lchmod (StringSpan path, uint32_t mode)
	Change file permission bits for a symbolic link without following it.

ResultFileSystem	setLastModifiedTime (StringSpan file, TimeMs time)
	Change last modified time of a given file.

Detailed Description

Execute fs operations { exists, copy, delete } for { files and directories }.

It will scope all operations on relative paths to the initialWorkingDirectory passed in SC::FileSystem::init. All methods can always return failure due to access or disk I/O errors, and they will be omitted in the return clauses for each method. Only the specific returned result behaviour of the given method will be described.

FileSystem fs;
// Make all operations relative to applicationRootDirectory
SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
// Create a nested directory structure with some files too
SC_TEST_EXPECT(fs.makeDirectoryRecursive("copyDirectory/subdirectory"));
SC_TEST_EXPECT(fs.write("copyDirectory/testFile.txt", "asdf"));
SC_TEST_EXPECT(fs.existsAndIsFile("copyDirectory/testFile.txt"));
SC_TEST_EXPECT(fs.write("copyDirectory/subdirectory/testFile.txt", "asdf"));
 
// Copy the directory (recursively)
SC_TEST_EXPECT(fs.copyDirectory("copyDirectory", "COPY_copyDirectory"));
 
// Check that file exists in the new copied directory
SC_TEST_EXPECT(fs.existsAndIsFile("COPY_copyDirectory/testFile.txt"));
SC_TEST_EXPECT(fs.existsAndIsFile("COPY_copyDirectory/subdirectory/testFile.txt"));
 
// Copying again fails (because we're not overwriting)
SC_TEST_EXPECT(not fs.copyDirectory("copyDirectory", "COPY_copyDirectory"));
 
// Try copying again but now we ask to overwrite destination
SC_TEST_EXPECT(fs.copyDirectory("copyDirectory", "COPY_copyDirectory",
                FileSystem::CopyFlags().setOverwrite(true)));
 
// Rename the directory (fs.rename works also for files)
SC_TEST_EXPECT(fs.rename("copyDirectory", "COPY_copyDirectory2"));
 
// Check that the directory has been renamed
SC_TEST_EXPECT(fs.existsAndIsDirectory("COPY_copyDirectory2"));
SC_TEST_EXPECT(not fs.existsAndIsDirectory("copyDirectory"));
 
// Rename the directory back to the original name
SC_TEST_EXPECT(fs.rename("COPY_copyDirectory2", "copyDirectory"));
 
// Remove all files created
SC_TEST_EXPECT(fs.removeFile("copyDirectory/testFile.txt"));
SC_TEST_EXPECT(fs.removeFile("copyDirectory/subdirectory/testFile.txt"));
SC_TEST_EXPECT(fs.removeEmptyDirectory("copyDirectory/subdirectory"));
SC_TEST_EXPECT(fs.removeEmptyDirectory("copyDirectory"));
// Remove the entire tree of directories for the copy
SC_TEST_EXPECT(fs.removeDirectoryRecursive("COPY_copyDirectory"));

Member Typedef Documentation

◆ AccessMode

using SC::FileSystem::AccessMode = FileSystemAccessMode

Access mode for path checks.

◆ CopyFlags

using SC::FileSystem::CopyFlags = FileSystemCopyFlags

Specify copy options like overwriting existing files.

◆ FileStat

using SC::FileSystem::FileStat = FileSystemStat

A structure to describe modified time.

Member Function Documentation

◆ canAccess() [1/2]

ResultFileSystem SC::FileSystem::canAccess	(	StringSpan	fileOrDirectory,
		AccessMode	accessMode,
		bool &	canAccessPath )

Detailed query: denied access or absence is a successful false answer.

◆ canAccess() [2/2]

bool SC::FileSystem::canAccess	(	StringSpan	fileOrDirectory,
		AccessMode	accessMode = AccessMode::Exists )

nodiscard

Check whether the current process can access a path with the requested mode.

Parameters

fileOrDirectory	Path to check
accessMode	Requested access mode

Returns: true if the requested access is allowed

◆ changeDirectory()

ResultFileSystem SC::FileSystem::changeDirectory ( StringSpan newDirectory )

Changes current directory.

All operations with relative paths will be relative to this directory.

Parameters

newDirectory The wanted directory

Returns: Valid Result if initialWorkingDirectory exists and it's accessible

◆ chmod()

ResultFileSystem SC::FileSystem::chmod	(	StringSpan	path,
		uint32_t	mode )

Change file permission bits for a path, following symbolic links.

Parameters

path	Path to the file or directory of interest
mode	Platform-native numeric mode bits

Returns: Valid Result if permissions were updated successfully

◆ chown()

ResultFileSystem SC::FileSystem::chown	(	StringSpan	path,
		uint32_t	uid,
		uint32_t	gid )

Change owner and group for a path, following symbolic links.

Parameters

path	Path to the file or directory of interest
uid	Platform-native numeric owner identifier
gid	Platform-native numeric group identifier

Returns: Valid Result if ownership was updated successfully

◆ copyDirectories()

ResultFileSystem SC::FileSystem::copyDirectories ( Span< const CopyOperation > sourceDestination )

Copy many directories.

Parameters

sourceDestination View over a sequence of CopyOperation describing copies to be done

Returns: Valid Result if all copies succeeded

See also: copyDirectory (for an usage example)

◆ copyDirectory()

ResultFileSystem SC::FileSystem::copyDirectory	(	StringSpan	source,
		StringSpan	destination,
		CopyFlags	copyFlags = CopyFlags() )

inline

Copy a single directory.

Parameters

source	Source directory path
destination	Destination directory path
copyFlags	Copy flags (overwrite, use clone api etc.)

Returns: Valid Result if copy succeeded

Example:

    FileSystem fs;
    // Make all operations relative to applicationRootDirectory
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
    // Create a nested directory structure with some files too
    SC_TEST_EXPECT(fs.makeDirectory("copyDirectory"));
    SC_TEST_EXPECT(fs.write("copyDirectory/testFile.txt", "asdf"));
    SC_TEST_EXPECT(fs.existsAndIsFile("copyDirectory/testFile.txt"));
    SC_TEST_EXPECT(fs.makeDirectory("copyDirectory/subdirectory"));
    SC_TEST_EXPECT(fs.write("copyDirectory/subdirectory/testFile.txt", "asdf"));
 
    // Copy the directory (recursively)
    SC_TEST_EXPECT(fs.copyDirectory("copyDirectory", "COPY_copyDirectory"));
 
    // Check that file exists in the new copied directory
    SC_TEST_EXPECT(fs.existsAndIsFile("COPY_copyDirectory/testFile.txt"));
    SC_TEST_EXPECT(fs.existsAndIsFile("COPY_copyDirectory/subdirectory/testFile.txt"));
 
    // Copying again fails (because we're not overwriting)
    SC_TEST_EXPECT(not fs.copyDirectory("copyDirectory", "COPY_copyDirectory"));
 
    // Try copying again but now we ask to overwrite destination
    SC_TEST_EXPECT(fs.copyDirectory("copyDirectory", "COPY_copyDirectory", FileSystem::CopyFlags().setOverwrite(true)));
 
    // Remove all files created by the test
    SC_TEST_EXPECT(fs.removeFile("copyDirectory/testFile.txt"));
    SC_TEST_EXPECT(fs.removeFile("copyDirectory/subdirectory/testFile.txt"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("copyDirectory/subdirectory"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("copyDirectory"));
    SC_TEST_EXPECT(fs.removeFile("COPY_copyDirectory/testFile.txt"));
    SC_TEST_EXPECT(fs.removeFile("COPY_copyDirectory/subdirectory/testFile.txt"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("COPY_copyDirectory/subdirectory"));
    SC_TEST_EXPECT(fs.removeEmptyDirectory("COPY_copyDirectory"));

◆ copyFile()

ResultFileSystem SC::FileSystem::copyFile	(	StringSpan	source,
		StringSpan	destination,
		CopyFlags	copyFlags = CopyFlags() )

inline

Copy a single file.

Parameters

source	Source file path
destination	Destination file path
copyFlags	Copy flags (overwrite, use clone api etc.)

Returns: Valid Result if copy succeeded

Example:

    FileSystem fs;
    // Make all operations relative to applicationRootDirectory
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
    // Create a File names 'sourceFile.txt'
    StringView contentSource = "this is some content";
    SC_TEST_EXPECT(not fs.exists("sourceFile.txt"));
    SC_TEST_EXPECT(fs.writeString("sourceFile.txt", contentSource));
 
    // Check that 'sourceFile.txt' exist, but not 'destinationFile.txt'
    SC_TEST_EXPECT(fs.existsAndIsFile("sourceFile.txt"));
    SC_TEST_EXPECT(not fs.exists("destinationFile.txt"));
 
    // Ask to copy sourceFile.txt to destinationFile.txt (eventually overwriting, but without cloning)
    SC_TEST_EXPECT(fs.copyFile("sourceFile.txt", "destinationFile.txt",
                               FileSystem::CopyFlags().setOverwrite(true).setUseCloneIfSupported(false)));
 
    // Now read the destinationFile.txt content and check if it's the same as source
    String content = StringEncoding::Ascii;
    SC_TEST_EXPECT(fs.read("destinationFile.txt", content));
    SC_TEST_EXPECT(content.view() == contentSource);
 
    // Copy again sourceFile.txt to destinationFile.txt but using clone this time
    SC_TEST_EXPECT(fs.copyFile("sourceFile.txt", "destinationFile.txt",
                               FileSystem::CopyFlags().setOverwrite(true).setUseCloneIfSupported(true)));
 
    // Check again if file exists and its content
    SC_TEST_EXPECT(fs.existsAndIsFile("destinationFile.txt"));
    SC_TEST_EXPECT(fs.read("destinationFile.txt", content));
    SC_TEST_EXPECT(content.view() == contentSource);
 
    // Remove all files created by the test
    SC_TEST_EXPECT(fs.removeFiles({"sourceFile.txt", "destinationFile.txt"}));
    SC_TEST_EXPECT(not fs.exists("sourceFile.txt"));
    SC_TEST_EXPECT(not fs.exists("destinationFile.txt"));

◆ copyFiles()

ResultFileSystem SC::FileSystem::copyFiles ( Span< const CopyOperation > sourceDestination )

Copies many files.

Parameters

sourceDestination View over a sequence of CopyOperation describing copies to be done

Returns: Valid Result if all copies succeeded

Example:

See also: copyFile (for an usage example)

◆ createHardLink()

ResultFileSystem SC::FileSystem::createHardLink	(	StringSpan	sourceFile,
		StringSpan	linkFile )

Creates a hard link at location linkFile pointing at sourceFile.

Parameters

sourceFile	The target file of the hard link
linkFile	The location where the hard link will be created

Returns: Invalid result if it's not possible creating the requested hard link

◆ createSymbolicLink()

ResultFileSystem SC::FileSystem::createSymbolicLink	(	StringSpan	sourceFileOrDirectory,
		StringSpan	linkFile )

Creates a symbolic link at location linkFile pointing at sourceFileOrDirectory.

Parameters

sourceFileOrDirectory	The target of the link (can be a folder or directory)
linkFile	The location where the symbolic link will be created

Returns: Invalid result if it's not possible creating the requested symbolic link

◆ exists() [1/2]

bool SC::FileSystem::exists ( StringSpan fileOrDirectory )

nodiscard

Check if a file or directory exists at a given path.

Parameters

fileOrDirectory Path to check

Returns: true if a file or directory exists at the given path

See also: existsAndIsFile (for an usage example)

◆ exists() [2/2]

ResultFileSystem SC::FileSystem::exists	(	StringSpan	fileOrDirectory,
		bool &	doesExist )

Detailed query: a missing entry is a successful false answer; validation and I/O failures are errors.

◆ existsAndIsDirectory() [1/2]

bool SC::FileSystem::existsAndIsDirectory ( StringSpan directory )

nodiscard

Check if a directory exists at given path.

Parameters

directory Directory path to check

Returns: true if a directory exists at the given path

◆ existsAndIsDirectory() [2/2]

ResultFileSystem SC::FileSystem::existsAndIsDirectory	(	StringSpan	directory,
		bool &	isDirectory )

Detailed query: absence or another entry type is a successful false answer.

◆ existsAndIsFile() [1/2]

bool SC::FileSystem::existsAndIsFile ( StringSpan file )

nodiscard

Check if a file exists at given path.

Parameters

file	File path to check

Returns: true if a file exists at the given path

Example:

    FileSystem fs;
    // Make all operations relative to applicationRootDirectory
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
    // Create a File names 'sourceFile.txt'
    StringView contentSource = "this is some content";
    SC_TEST_EXPECT(not fs.exists("sourceFile.txt"));
    SC_TEST_EXPECT(fs.writeString("sourceFile.txt", contentSource));
 
    // Check that 'sourceFile.txt' exist, but not 'destinationFile.txt'
    SC_TEST_EXPECT(fs.existsAndIsFile("sourceFile.txt"));
    SC_TEST_EXPECT(not fs.exists("destinationFile.txt"));
 
    // Ask to copy sourceFile.txt to destinationFile.txt (eventually overwriting, but without cloning)
    SC_TEST_EXPECT(fs.copyFile("sourceFile.txt", "destinationFile.txt",
                               FileSystem::CopyFlags().setOverwrite(true).setUseCloneIfSupported(false)));
 
    // Now read the destinationFile.txt content and check if it's the same as source
    String content = StringEncoding::Ascii;
    SC_TEST_EXPECT(fs.read("destinationFile.txt", content));
    SC_TEST_EXPECT(content.view() == contentSource);
 
    // Copy again sourceFile.txt to destinationFile.txt but using clone this time
    SC_TEST_EXPECT(fs.copyFile("sourceFile.txt", "destinationFile.txt",
                               FileSystem::CopyFlags().setOverwrite(true).setUseCloneIfSupported(true)));
 
    // Check again if file exists and its content
    SC_TEST_EXPECT(fs.existsAndIsFile("destinationFile.txt"));
    SC_TEST_EXPECT(fs.read("destinationFile.txt", content));
    SC_TEST_EXPECT(content.view() == contentSource);
 
    // Remove all files created by the test
    SC_TEST_EXPECT(fs.removeFiles({"sourceFile.txt", "destinationFile.txt"}));
    SC_TEST_EXPECT(not fs.exists("sourceFile.txt"));
    SC_TEST_EXPECT(not fs.exists("destinationFile.txt"));

◆ existsAndIsFile() [2/2]

ResultFileSystem SC::FileSystem::existsAndIsFile	(	StringSpan	file,
		bool &	isFile )

Detailed query: absence or another entry type is a successful false answer.

◆ existsAndIsLink() [1/2]

bool SC::FileSystem::existsAndIsLink ( StringSpan file )

nodiscard

Check if a link exists at given path.

Parameters

file	Link path to check

Returns: true if a file exists at the given path

◆ existsAndIsLink() [2/2]

ResultFileSystem SC::FileSystem::existsAndIsLink	(	StringSpan	file,
		bool &	isLink )

Detailed query: absence or another entry type is a successful false answer.

◆ getFileStat()

ResultFileSystem SC::FileSystem::getFileStat	(	StringSpan	file,
		FileStat &	fileStat )

Legacy convenience alias for stat(StringSpan, FileStat&)

Parameters

	file	Path to the file of interest
[out]	fileStat	Destination structure that will receive statistics about the file

Returns: Valid Result if file stats for the given file was successfully read

◆ init()

ResultFileSystem SC::FileSystem::init ( StringSpan initialDirectory )

Call init function when instantiating the class to set directory for all operations using relative paths.

Parameters

initialDirectory The wanted directory

Returns: Valid Result if initialDirectory exists and it's accessible

◆ lchmod()

ResultFileSystem SC::FileSystem::lchmod	(	StringSpan	path,
		uint32_t	mode )

Change file permission bits for a symbolic link without following it.

Parameters

path	Path to the symbolic link of interest
mode	Platform-native numeric mode bits

Returns: Valid Result if permissions were updated successfully

◆ lchown()

ResultFileSystem SC::FileSystem::lchown	(	StringSpan	path,
		uint32_t	uid,
		uint32_t	gid )

Change owner and group for a path without following symbolic links.

Parameters

path	Path to the file or directory of interest
uid	Platform-native numeric owner identifier
gid	Platform-native numeric group identifier

Returns: Valid Result if ownership was updated successfully

◆ lstat()

ResultFileSystem SC::FileSystem::lstat	(	StringSpan	file,
		FileStat &	fileStat )

Obtains richer metadata about a path without following symbolic links.

Parameters

	file	Path to the file of interest
[out]	fileStat	Destination structure that will receive statistics about the file

Returns: Valid Result if file stats for the given file was successfully read

◆ makeDirectories()

ResultFileSystem SC::FileSystem::makeDirectories ( Span< const StringSpan > directories )

Creates new directories that do not already exist.

Parameters

directories List of paths where to create such directories

Returns: Invalid Results if directories already exist

See also: makeDirectoryRecursive (for an usage example)

◆ makeDirectoriesIfNotExists()

ResultFileSystem SC::FileSystem::makeDirectoriesIfNotExists ( Span< const StringSpan > directories )

Creates new directories, if they don't already exist at the given path.

Parameters

directories List of paths where to create such directories

Returns: Invalid Results in case of I/O or access error

◆ makeDirectoriesRecursive()

ResultFileSystem SC::FileSystem::makeDirectoriesRecursive ( Span< const StringSpan > directories )

Create new directories, creating also intermediate non existing directories (like posix mkdir -p)

Parameters

directories List of paths where to create such directories

Returns: Invalid Result in case of I/O or access error

See also: makeDirectoryRecursive (for an usage example)

◆ makeDirectory()

ResultFileSystem SC::FileSystem::makeDirectory ( StringSpan directory )

inline

Creates a new directory that does not already exist.

Parameters

directory Path where the directory should be created

Returns: Invalid Results if directory already exist

See also: makeDirectoryRecursive (for an usage example)

◆ makeDirectoryIfNotExists()

ResultFileSystem SC::FileSystem::makeDirectoryIfNotExists ( StringSpan directory )

inline

Creates a new directory, if it doesn't already exists at the given path.

Parameters

directory Path where to create the new directory

Returns: Invalid Results in case of I/O or access error

◆ makeDirectoryRecursive()

ResultFileSystem SC::FileSystem::makeDirectoryRecursive ( StringSpan directory )

inline

Create a new directory, creating also intermediate non existing directories (like posix mkdir -p)

Parameters

directory Path where to create such directory

Returns: Invalid Result in case of I/O or access error
FileSystem fs;

// Make all operations relative to applicationRootDirectory

SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));

// Create a directory with 2 levels of nesting

SC_TEST_EXPECT(fs.makeDirectoryRecursive("Test3/Subdir"));

// Check that both levels have been created

SC_TEST_EXPECT(fs.existsAndIsDirectory("Test3"));

SC_TEST_EXPECT(fs.existsAndIsDirectory("Test3/Subdir"));

// Remove both levels of directory

SC_TEST_EXPECT(fs.removeEmptyDirectory("Test3/Subdir"));

SC_TEST_EXPECT(fs.removeEmptyDirectory("Test3"));

◆ moveDirectory()

ResultFileSystem SC::FileSystem::moveDirectory	(	StringSpan	sourceDirectory,
		StringSpan	destinationDirectory )

nodiscard

Moves a directory from source to destination.

Parameters

sourceDirectory	The source directory that will be moved to destination
destinationDirectory	The destination directory

Returns: Valid Result if the move succeeded

◆ read() [1/2]

ResultFileSystem SC::FileSystem::read	(	StringSpan	file,
		IGrowableBuffer &&	buffer )

Read contents of a file into an IGrowableBuffer.

Parameters

[in]	file	Path to the file to read
[out]	buffer	Destination IGrowableBuffer that will receive file contents

Returns: Valid Result if the entire file has been read successfully

◆ read() [2/2]

template<typename T >

ResultFileSystem SC::FileSystem::read	(	StringSpan	file,
		T &	data )

inline

Read contents of a file into a String or Buffer.

Parameters

[in]	file	Path to the file to read
[out]	data	Destination String or Buffer that will receive file contents

Returns: Valid Result if the entire file has been read successfully

See also: write (for an usage example)

◆ readSymbolicLink()

ResultFileSystem SC::FileSystem::readSymbolicLink	(	StringSpan	linkFile,
		StringPath &	destination )

Reads the target path stored by a symbolic link.

Parameters

	linkFile	Path to the symbolic link
[out]	destination	Destination receiving the native-encoded target path

Returns: Valid Result if link target was successfully read

◆ removeDirectoriesRecursive()

ResultFileSystem SC::FileSystem::removeDirectoriesRecursive ( Span< const StringSpan > directories )

Remove multiple directories with their entire content (like posix rm -rf)

Parameters

directories List of directories to remove

Returns: Valid Result if all directories and their contents have been successfully removed

See also: removeDirectoryRecursive (for an usage example)

◆ removeDirectoryRecursive()

ResultFileSystem SC::FileSystem::removeDirectoryRecursive ( StringSpan directory )

inline

Remove single directory with its entire content (like posix rm -rf)

Parameters

directory Directory to remove

Returns: Valid Result if directory contents has been successfully deleted

Example:

    FileSystem fs;
    // Make all operations relative to applicationRootDirectory
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
    // Create a nested directory structure with some files too
    SC_TEST_EXPECT(fs.makeDirectory("removeDirectoryTest"));
    SC_TEST_EXPECT(fs.write("removeDirectoryTest/testFile.txt", "asdf"));
    SC_TEST_EXPECT(fs.makeDirectory("removeDirectoryTest/another"));
    SC_TEST_EXPECT(fs.write("removeDirectoryTest/another/yeah.txt", "asdf"));
 
    // Remove the entire tree of directories
    SC_TEST_EXPECT(fs.removeDirectoryRecursive("removeDirectoryTest"));
 
    // Check that all files and directories have been removed
    SC_TEST_EXPECT(not fs.existsAndIsFile("removeDirectoryTest/testFile.txt"));
    SC_TEST_EXPECT(not fs.existsAndIsFile("removeDirectoryTest/another/yeah.txt"));
    SC_TEST_EXPECT(not fs.existsAndIsDirectory("removeDirectoryTest/another"));
    SC_TEST_EXPECT(not fs.existsAndIsDirectory("removeDirectoryTest"));

◆ removeEmptyDirectories()

ResultFileSystem SC::FileSystem::removeEmptyDirectories ( Span< const StringSpan > directories )

Removes multiple empty directories.

Parameters

directories List of empty directories to remove

Returns: Invalid Result if one of the directories doesn't exist or it's not empty

See also: makeDirectoryRecursive (for an usage example)

◆ removeEmptyDirectory()

ResultFileSystem SC::FileSystem::removeEmptyDirectory ( StringSpan directory )

inline

Removes an empty directory.

Parameters

directory Empty directory to remove

Returns: Invalid Result if the directory doesn't exist or it's not empty

See also: makeDirectoryRecursive (for an usage example)

◆ removeFile()

ResultFileSystem SC::FileSystem::removeFile ( StringSpan source )

inline

Remove a single file.

Parameters

source A single file path to be removed

Returns: Valid Result if file was existing and it has been removed successfully

See also: write (for an usage example)

◆ removeFileIfExists()

ResultFileSystem SC::FileSystem::removeFileIfExists ( StringSpan source )

Remove a single file, giving no error if it doesn't exist.

Parameters

source The file to be removed if it exists

Returns: Valid Result if the file doesn't exist or if it exists and it has been successfully removed.

◆ removeFiles()

ResultFileSystem SC::FileSystem::removeFiles ( Span< const StringSpan > files )

Remove multiple files.

Parameters

files View over a list of paths

Returns: Valid Result if file was removed

◆ removeLinkIfExists()

ResultFileSystem SC::FileSystem::removeLinkIfExists ( StringSpan source )

Remove a single link, giving no error if it doesn't exist.

Parameters

source The link to be removed if it exists

Returns: Valid Result if the file doesn't exist or if it exists and it has been successfully removed.

◆ rename()

ResultFileSystem SC::FileSystem::rename	(	StringSpan	path,
		StringSpan	newPath )

Rename a file or directory.

Parameters

path	The path to the file or directory to rename
newPath	The new path to the file or directory

Returns: Valid Result if the file or directory was renamed

Example:

    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
    // Create a file and check that it exists
    SC_TEST_EXPECT(fs.writeString("renameTest.txt", "asdf"));
    SC_TEST_EXPECT(fs.existsAndIsFile("renameTest.txt"));
 
    // Rename the file
    SC_TEST_EXPECT(fs.rename("renameTest.txt", "renameTest2.txt"));
 
    // Check that the file has been renamed
    SC_TEST_EXPECT(fs.existsAndIsFile("renameTest2.txt"));
    SC_TEST_EXPECT(not fs.existsAndIsFile("renameTest.txt"));
 
    // Rename the file again
    SC_TEST_EXPECT(fs.rename("renameTest2.txt", "renameTest.txt"));
 
    // Check that the file has been renamed
    SC_TEST_EXPECT(fs.existsAndIsFile("renameTest.txt"));
    SC_TEST_EXPECT(not fs.existsAndIsFile("renameTest2.txt"));
 
    // Remove all files created by the test
    SC_TEST_EXPECT(fs.removeFile("renameTest.txt"));

    FileSystem fs;
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
 
    // Create a directory and check that it exists
    SC_TEST_EXPECT(fs.makeDirectory("renameDirectoryTest"));
    SC_TEST_EXPECT(fs.existsAndIsDirectory("renameDirectoryTest"));
    // Create a file in the directory
    SC_TEST_EXPECT(fs.writeString("renameDirectoryTest/testFile.txt", "asdf"));
    SC_TEST_EXPECT(fs.existsAndIsFile("renameDirectoryTest/testFile.txt"));
    // Create a subdirectory in the directory
    SC_TEST_EXPECT(fs.makeDirectory("renameDirectoryTest/subdirectory"));
    SC_TEST_EXPECT(fs.existsAndIsDirectory("renameDirectoryTest/subdirectory"));
 
    // Create a file in the subdirectory
    SC_TEST_EXPECT(fs.writeString("renameDirectoryTest/subdirectory/testFile.txt", "asdf"));
    SC_TEST_EXPECT(fs.existsAndIsFile("renameDirectoryTest/subdirectory/testFile.txt"));
 
    // Rename the directory
    SC_TEST_EXPECT(fs.rename("renameDirectoryTest", "renameDirectoryTest2"));
 
    // Check that the directory has been renamed
    SC_TEST_EXPECT(fs.existsAndIsDirectory("renameDirectoryTest2"));
    SC_TEST_EXPECT(not fs.existsAndIsDirectory("renameDirectoryTest"));
 
    // Check that the file in the directory has been renamed
    SC_TEST_EXPECT(fs.existsAndIsFile("renameDirectoryTest2/testFile.txt"));
    SC_TEST_EXPECT(not fs.existsAndIsFile("renameDirectoryTest/testFile.txt"));
    // Check that the file in the subdirectory has been renamed
    SC_TEST_EXPECT(fs.existsAndIsFile("renameDirectoryTest2/subdirectory/testFile.txt"));
    SC_TEST_EXPECT(not fs.existsAndIsFile("renameDirectoryTest/subdirectory/testFile.txt"));
 
    // Remove all directories created by the test
    SC_TEST_EXPECT(fs.removeDirectoryRecursive("renameDirectoryTest2"));

◆ setLastModifiedTime()

ResultFileSystem SC::FileSystem::setLastModifiedTime	(	StringSpan	file,
		TimeMs	time )

Change last modified time of a given file.

Parameters

file	Path to the file of interest
time	The new last modified time, as specified in the AbsoluteTime struct

Returns: Valid Result if file time for the given file was successfully set

◆ stat()

ResultFileSystem SC::FileSystem::stat	(	StringSpan	file,
		FileStat &	fileStat )

Obtains richer metadata about a path, following symbolic links.

Parameters

	file	Path to the file of interest
[out]	fileStat	Destination structure that will receive statistics about the file

Returns: Valid Result if file stats for the given file was successfully read

◆ write()

ResultFileSystem SC::FileSystem::write	(	StringSpan	file,
		Span< const char >	data )

Writes a block of memory to a file.

Parameters

file	Path to the file that is meant to be written
data	Block of memory to write

Returns: Valid Result if the memory was successfully written

Example:

    FileSystem fs;
    // Make all operations relative to applicationRootDirectory
    SC_TEST_EXPECT(fs.init(report.applicationRootDirectory.view()));
    StringView content = "ASDF content";
 
    // Check that file doesn't exists before write-ing it and then check that it exist
    SC_TEST_EXPECT(not fs.exists("file.txt"));
    SC_TEST_EXPECT(fs.writeString("file.txt", content));
    SC_TEST_EXPECT(fs.existsAndIsFile("file.txt"));
 
    // Read the file and check its content
    String newString = StringEncoding::Ascii;
    SC_TEST_EXPECT(fs.read("file.txt", newString));
    SC_TEST_EXPECT(newString.view() == content);
 
    // Remove all files created by the test
    SC_TEST_EXPECT(fs.removeFile("file.txt"));
    SC_TEST_EXPECT(not fs.exists("file.txt"));

◆ writeString()

ResultFileSystem SC::FileSystem::writeString	(	StringSpan	file,
		StringSpan	text )

Replace the entire content of a file with the provided StringSpan.

Parameters

file	Path to the file that is meant to be written
text	Text to be written

Returns: Valid Result if the memory was successfully written

See also: write (for an usage example)

◆ writeStringAppend()

ResultFileSystem SC::FileSystem::writeStringAppend	(	StringSpan	file,
		StringSpan	text )

Appends a StringSpan to a file.

Parameters

file	Path to the file that is meant to be appended
text	Text to be appended

Returns: Valid Result if the memory was successfully appended

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

FileSystem.h

Classes

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ AccessMode

◆ CopyFlags

◆ FileStat

Member Function Documentation

◆ canAccess() [1/2]

◆ canAccess() [2/2]

◆ changeDirectory()

◆ chmod()

◆ chown()

◆ copyDirectories()

◆ copyDirectory()

◆ copyFile()

◆ copyFiles()

◆ createHardLink()

◆ createSymbolicLink()

◆ exists() [1/2]

◆ exists() [2/2]

◆ existsAndIsDirectory() [1/2]

◆ existsAndIsDirectory() [2/2]

◆ existsAndIsFile() [1/2]

◆ existsAndIsFile() [2/2]

◆ existsAndIsLink() [1/2]

◆ existsAndIsLink() [2/2]

◆ getFileStat()

◆ init()

◆ lchmod()

◆ lchown()

◆ lstat()

◆ makeDirectories()

◆ makeDirectoriesIfNotExists()

◆ makeDirectoriesRecursive()

◆ makeDirectory()

◆ makeDirectoryIfNotExists()

◆ makeDirectoryRecursive()

◆ moveDirectory()

◆ read() [1/2]

◆ read() [2/2]

◆ readSymbolicLink()

◆ removeDirectoriesRecursive()

◆ removeDirectoryRecursive()

◆ removeEmptyDirectories()

◆ removeEmptyDirectory()

◆ removeFile()

◆ removeFileIfExists()

◆ removeFiles()

◆ removeLinkIfExists()

◆ rename()

◆ setLastModifiedTime()

◆ stat()

◆ write()

◆ writeString()

◆ writeStringAppend()