Sane C++ Libraries
C++ Platform Abstraction Libraries
Loading...
Searching...
No Matches
SC::FileSystem Struct Reference

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

#include <FileSystem.h>

Classes

struct  CopyFlags
 Specify copy options like overwriting existing files. More...
 
struct  CopyOperation
 Specify source, destination and flags for a copy operation. More...
 
struct  FileStat
 A structure to describe modified time. More...
 

Public Member Functions

Result init (StringView initialDirectory)
 Call init function when instantiating the class to set directory for all operations using relative paths.
 
Result changeDirectory (StringView newDirectory)
 Changes current directory.
 
Result copyFiles (Span< const CopyOperation > sourceDestination)
 Copies many files.
 
Result copyFile (StringView source, StringView destination, CopyFlags copyFlags=CopyFlags())
 Copy a single file.
 
Result copyDirectories (Span< const CopyOperation > sourceDestination)
 Copy many directories.
 
Result copyDirectory (StringView source, StringView destination, CopyFlags copyFlags=CopyFlags())
 Copy a single directory.
 
Result removeFiles (Span< const StringView > files)
 Remove multiple files.
 
Result removeFile (StringView source)
 Remove a single file.
 
Result removeFileIfExists (StringView source)
 Remove a single file, giving no error if it doesn't exist.
 
Result removeLinkIfExists (StringView source)
 Remove a single link, giving no error if it doesn't exist.
 
Result removeDirectoriesRecursive (Span< const StringView > directories)
 Remove multiple directories with their entire content (like posix rm -rf)
 
Result removeDirectoryRecursive (StringView directory)
 Remove single directory with its entire content (like posix rm -rf)
 
Result removeEmptyDirectories (Span< const StringView > directories)
 Removes multiple empty directories.
 
Result removeEmptyDirectory (StringView directory)
 Removes an empty directory.
 
Result removeEmptyDirectoriesRecursive (Span< const StringView > directories)
 Removes multiple empty directories that only contains other empty directories (but no files)
 
Result removeEmptyDirectoryRecursive (StringView directory)
 Removes an empty directory that only contains other empty directories (but no files)
 
Result makeDirectories (Span< const StringView > directories)
 Creates new directories that do not already exist.
 
Result makeDirectory (StringView directory)
 Creates a new directory that does not already exist.
 
Result makeDirectoriesIfNotExists (Span< const StringView > directories)
 Creates new directories, if they don't already exist at the given path.
 
Result makeDirectoryIfNotExists (StringView directory)
 Creates a new directory, if it doesn't already exists at the given path.
 
Result makeDirectoriesRecursive (Span< const StringView > directories)
 Create new directories, creating also intermediate non existing directories (like posix mkdir -p)
 
Result makeDirectoryRecursive (StringView directory)
 Create a new directory, creating also intermediate non existing directories (like posix mkdir -p)
 
Result createSymbolicLink (StringView sourceFileOrDirectory, StringView linkFile)
 Creates a symbolic link at location linkFile pointing at sourceFileOrDirectory.
 
bool exists (StringView fileOrDirectory)
 Check if a file or directory exists at a given path.
 
bool existsAndIsDirectory (StringView directory)
 Check if a directory exists at given path.
 
bool existsAndIsFile (StringView file)
 Check if a file exists at given path.
 
bool existsAndIsLink (StringView file)
 Check if a link exists at given path.
 
bool moveDirectory (StringView sourceDirectory, StringView destinationDirectory)
 Moves a directory from source to destination.
 
Result write (StringView file, Span< const char > data)
 Writes a block of memory to a file.
 
Result write (StringView file, Span< const uint8_t > data)
 
Result read (StringView file, Buffer &data)
 Reads contents of a file into a SC::Buffer.
 
Result writeString (StringView file, StringView text)
 Replace the entire content of a file with the provided StringView.
 
Result writeStringAppend (StringView file, StringView text)
 Appends a StringView to a file.
 
Result read (StringView file, String &data, StringEncoding encoding)
 Read contents of a file into a string with given encoding.
 
Result getFileStat (StringView file, FileStat &fileStat)
 Obtains stats (size, modified time) about a file.
 
Result setLastModifiedTime (StringView file, Time::Realtime time)
 Change last modified time of a given file.
 

Public Attributes

bool preciseErrorMessages = false
 Formats errors in an internal buffer when returning failed Result.
 

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.

// Make all operations relative to applicationRootDirectory
// 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",
// 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 Function Documentation

◆ changeDirectory()

Result SC::FileSystem::changeDirectory ( StringView newDirectory)

Changes current directory.

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

Parameters
newDirectoryThe wanted directory
Returns
Valid Result if initialWorkingDirectory exists and it's accessible

◆ copyDirectories()

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

Copy many directories.

Parameters
sourceDestinationView 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()

Result SC::FileSystem::copyDirectory ( StringView source,
StringView destination,
CopyFlags copyFlags = CopyFlags() )
inlinenodiscard

Copy a single directory.

Parameters
sourceSource directory path
destinationDestination directory path
copyFlagsCopy flags (overwrite, use clone api etc.)
Returns
Valid Result if copy succeeded

Example:

// Make all operations relative to applicationRootDirectory
// 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()

Result SC::FileSystem::copyFile ( StringView source,
StringView destination,
CopyFlags copyFlags = CopyFlags() )
inlinenodiscard

Copy a single file.

Parameters
sourceSource file path
destinationDestination file path
copyFlagsCopy flags (overwrite, use clone api etc.)
Returns
Valid Result if copy succeeded

Example:

// Make all operations relative to applicationRootDirectory
// 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",
// Now read the destinationFile.txt content and check if it's the same as source
String content;
SC_TEST_EXPECT(fs.read("destinationFile.txt", content, StringEncoding::Ascii));
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",
// Check again if file exists and its content
SC_TEST_EXPECT(fs.existsAndIsFile("destinationFile.txt"));
SC_TEST_EXPECT(fs.read("destinationFile.txt", content, StringEncoding::Ascii));
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()

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

Copies many files.

Parameters
sourceDestinationView 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)

◆ createSymbolicLink()

Result SC::FileSystem::createSymbolicLink ( StringView sourceFileOrDirectory,
StringView linkFile )
nodiscard

Creates a symbolic link at location linkFile pointing at sourceFileOrDirectory.

Parameters
sourceFileOrDirectoryThe target of the link (can be a folder or directory)
linkFileThe location where the symbolic link will be created
Returns
Invalid result if it's not possible creating the requested symbolic link

◆ exists()

bool SC::FileSystem::exists ( StringView fileOrDirectory)
nodiscard

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

Parameters
fileOrDirectoryPath to check
Returns
true if a file or directory exists at the given path
See also
existsAndIsFile (for an usage example)

◆ existsAndIsDirectory()

bool SC::FileSystem::existsAndIsDirectory ( StringView directory)
nodiscard

Check if a directory exists at given path.

Parameters
directoryDirectory path to check
Returns
true if a directory exists at the given path

◆ existsAndIsFile()

bool SC::FileSystem::existsAndIsFile ( StringView file)
nodiscard

Check if a file exists at given path.

Parameters
fileFile path to check
Returns
true if a file exists at the given path

Example:

// Make all operations relative to applicationRootDirectory
// 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",
// Now read the destinationFile.txt content and check if it's the same as source
String content;
SC_TEST_EXPECT(fs.read("destinationFile.txt", content, StringEncoding::Ascii));
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",
// Check again if file exists and its content
SC_TEST_EXPECT(fs.existsAndIsFile("destinationFile.txt"));
SC_TEST_EXPECT(fs.read("destinationFile.txt", content, StringEncoding::Ascii));
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"));

◆ existsAndIsLink()

bool SC::FileSystem::existsAndIsLink ( StringView file)
nodiscard

Check if a link exists at given path.

Parameters
fileLink path to check
Returns
true if a file exists at the given path

◆ getFileStat()

Result SC::FileSystem::getFileStat ( StringView file,
FileStat & fileStat )
nodiscard

Obtains stats (size, modified time) about a file.

Parameters
filePath to the file of interest
[out]fileStatDestination structure that will receive statistics about the file
Returns
Valid Result if file stats for the given file was successfully read

◆ init()

Result SC::FileSystem::init ( StringView initialDirectory)

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

Parameters
initialDirectoryThe wanted directory
Returns
Valid Result if initialDirectory exists and it's accessible

◆ makeDirectories()

Result SC::FileSystem::makeDirectories ( Span< const StringView > directories)
nodiscard

Creates new directories that do not already exist.

Parameters
directoriesList of paths where to create such directories
Returns
Invalid Results if directories already exist
See also
makeDirectoryRecursive (for an usage example)

◆ makeDirectoriesIfNotExists()

Result SC::FileSystem::makeDirectoriesIfNotExists ( Span< const StringView > directories)
nodiscard

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

Parameters
directoriesList of paths where to create such directories
Returns
Invalid Results in case of I/O or access error

◆ makeDirectoriesRecursive()

Result SC::FileSystem::makeDirectoriesRecursive ( Span< const StringView > directories)
nodiscard

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

Parameters
directoriesList 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()

Result SC::FileSystem::makeDirectory ( StringView directory)
inlinenodiscard

Creates a new directory that does not already exist.

Parameters
directoryPath where the directory should be created
Returns
Invalid Results if directory already exist
See also
makeDirectoryRecursive (for an usage example)

◆ makeDirectoryIfNotExists()

Result SC::FileSystem::makeDirectoryIfNotExists ( StringView directory)
inlinenodiscard

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

Parameters
directoryPath where to create the new directory
Returns
Invalid Results in case of I/O or access error

◆ makeDirectoryRecursive()

Result SC::FileSystem::makeDirectoryRecursive ( StringView directory)
inlinenodiscard

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

Parameters
directoryPath where to create such directory
Returns
Invalid Result in case of I/O or access error
// Make all operations relative to applicationRootDirectory
// Create a directory with 2 levels of nesting
// Check that both levels have been created
SC_TEST_EXPECT(fs.existsAndIsDirectory("Test3/Subdir"));
// Remove both levels of directory
// Check that directory has been removed

◆ moveDirectory()

bool SC::FileSystem::moveDirectory ( StringView sourceDirectory,
StringView destinationDirectory )
nodiscard

Moves a directory from source to destination.

Parameters
sourceDirectoryThe source directory that will be moved to destination
destinationDirectoryThe destination directory
Returns
true if the move succeeded

◆ read() [1/2]

Result SC::FileSystem::read ( StringView file,
Buffer & data )
nodiscard

Reads contents of a file into a SC::Buffer.

Parameters
filePath to the file to read
[out]dataDestination buffer that will receive data
Returns
Valid Result if file was fully read successfully
See also
write (for an usage example)

◆ read() [2/2]

Result SC::FileSystem::read ( StringView file,
String & data,
StringEncoding encoding )
nodiscard

Read contents of a file into a string with given encoding.

Parameters
[in]filePath to the file to read
[out]dataDestination string that will receive the file contents
[in]encodingThe wanted encoding of the resulting string
Returns
Valid Result if the entire content of the file was read into the String
See also
write (for an usage example)

◆ removeDirectoriesRecursive()

Result SC::FileSystem::removeDirectoriesRecursive ( Span< const StringView > directories)
nodiscard

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

Parameters
directoriesList 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()

Result SC::FileSystem::removeDirectoryRecursive ( StringView directory)
inlinenodiscard

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

Parameters
directoryDirectory to remove
Returns
Valid Result if directory contents has been successfully deleted

Example:

// Make all operations relative to applicationRootDirectory
// 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()

Result SC::FileSystem::removeEmptyDirectories ( Span< const StringView > directories)
nodiscard

Removes multiple empty directories.

Parameters
directoriesList 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)

◆ removeEmptyDirectoriesRecursive()

Result SC::FileSystem::removeEmptyDirectoriesRecursive ( Span< const StringView > directories)
nodiscard

Removes multiple empty directories that only contains other empty directories (but no files)

Parameters
directoriesList of empty directories to remove
Returns
Invalid Result if one of the directories doesn't exist or if it contains files somewhere inside of it
See also
makeDirectoryRecursive (for an usage example)

◆ removeEmptyDirectory()

Result SC::FileSystem::removeEmptyDirectory ( StringView directory)
inlinenodiscard

Removes an empty directory.

Parameters
directoryEmpty directory to remove
Returns
Invalid Result if the directory doesn't exist or it's not empty
See also
makeDirectoryRecursive (for an usage example)

◆ removeEmptyDirectoryRecursive()

Result SC::FileSystem::removeEmptyDirectoryRecursive ( StringView directory)
inlinenodiscard

Removes an empty directory that only contains other empty directories (but no files)

Parameters
directoryList of empty directories to remove
Returns
Invalid Result if the directory doesn't exist or if it contains files somewhere inside of it
See also
makeDirectoryRecursive (for an usage example)

◆ removeFile()

Result SC::FileSystem::removeFile ( StringView source)
inlinenodiscard

Remove a single file.

Parameters
sourceA 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()

Result SC::FileSystem::removeFileIfExists ( StringView source)
nodiscard

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

Parameters
sourceThe 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()

Result SC::FileSystem::removeFiles ( Span< const StringView > files)
nodiscard

Remove multiple files.

Parameters
filesView over a list of paths
Returns
Valid Result if file was removed

◆ removeLinkIfExists()

Result SC::FileSystem::removeLinkIfExists ( StringView source)
nodiscard

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

Parameters
sourceThe 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.

◆ setLastModifiedTime()

Result SC::FileSystem::setLastModifiedTime ( StringView file,
Time::Realtime time )
nodiscard

Change last modified time of a given file.

Parameters
filePath to the file of interest
timeThe new last modified time, as specified in the AbsoluteTime struct
Returns
Valid Result if file time for the given file was successfully set

◆ write()

Result SC::FileSystem::write ( StringView file,
Span< const char > data )
nodiscard

Writes a block of memory to a file.

Parameters
filePath to the file that is meant to be written
dataBlock of memory to write
Returns
Valid Result if the memory was successfully written

Example:

// Make all operations relative to applicationRootDirectory
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));
// Read the file and check its content
String newString;
SC_TEST_EXPECT(fs.read("file.txt", newString, StringEncoding::Ascii));
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()

Result SC::FileSystem::writeString ( StringView file,
StringView text )
nodiscard

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

Parameters
filePath to the file that is meant to be written
textText to be written
Returns
Valid Result if the memory was successfully written
See also
write (for an usage example)

◆ writeStringAppend()

Result SC::FileSystem::writeStringAppend ( StringView file,
StringView text )
nodiscard

Appends a StringView to a file.

Parameters
filePath to the file that is meant to be appended
textText to be appended
Returns
Valid Result if the memory was successfully appended

Member Data Documentation

◆ preciseErrorMessages

bool SC::FileSystem::preciseErrorMessages = false

Formats errors in an internal buffer when returning failed Result.


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