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

Public Attributes

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

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.

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)

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() 
)
inline

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:

FileSystem fs;
// Make all operations relative to applicationRootDirectory
SC_TEST_EXPECT(fs.init(report.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"));
#define SC_TEST_EXPECT(e)
Records a test expectation (eventually aborting or breaking o n failed test)
Definition: Testing.h:113

◆ copyFile()

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

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:

FileSystem fs;
// Make all operations relative to applicationRootDirectory
SC_TEST_EXPECT(fs.init(report.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",
FileSystem::CopyFlags().setOverwrite(true).setUseCloneIfSupported(false)));
// 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",
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, 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"));
@ Ascii
Encoding is ASCII.

◆ copyFiles()

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

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 
)

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)

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)

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)

Check if a file exists at given path.

Parameters
fileFile 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));
// 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;
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",
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, 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)

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 
)

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)

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)

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)

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)
inline

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)
inline

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)
inline

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
FileSystem fs;
// Make all operations relative to applicationRootDirectory
SC_TEST_EXPECT(fs.init(report.applicationRootDirectory));
// 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.removeEmptyDirectoryRecursive("Test3/Subdir"));
// Check that directory has been removed
SC_TEST_EXPECT(not fs.existsAndIsDirectory("Test3"));

◆ moveDirectory()

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

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,
String data,
StringEncoding  encoding 
)

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)

◆ read() [2/2]

Result SC::FileSystem::read ( StringView  file,
Vector< char > &  data 
)

Reads contents of a file into a SC::Vector 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)

◆ removeDirectoriesRecursive()

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

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)
inline

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:

FileSystem fs;
// Make all operations relative to applicationRootDirectory
SC_TEST_EXPECT(fs.init(report.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)

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)

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)
inline

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)
inline

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)
inline

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)

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)

Remove multiple files.

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

◆ removeLinkIfExists()

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

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::Absolute  time 
)

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 
)

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:

FileSystem fs;
// Make all operations relative to applicationRootDirectory
SC_TEST_EXPECT(fs.init(report.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));
SC_TEST_EXPECT(fs.existsAndIsFile("file.txt"));
// 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 
)

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 
)

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: