CeresEngine::FileHandle Class Reference

Handle for a file or directory. More...

#include <CeresEngine/Foundation/IO/FileHandle.hpp>

Public Types
enum class	RemoveDirectoryFlag { FollowSymlinks = (1u << 0u) , Recursive = (1u << 1u) , None = 0 , Default = None }
	A set of flags that customize removeDirectory() behavior. More...
using	ImplementationType = Poly< IFileHandle, sizeof(void *) *4 >
using	VisitFunc = std::function< bool(const FileHandle &)>
using	RemoveDirectoryFlags = Flags< RemoveDirectoryFlag >
	A set of flags that customize removeDirectory() behavior.

Public Member Functions
	FileHandle () noexcept
	Constructs a new empty FileHandle.
	FileHandle (const FilePath &path)
	Creates a new FileHandle from a path on the local file system.
	FileHandle (ImplementationType &&backend)
	Creates a new FileHandle from a concrete implementation.
	FileHandle (const FileHandle &other)
	Copies a FileHandle from another.
FileHandle &	operator= (const FileHandle &other)
	Copies a FileHandle from another.
	FileHandle (FileHandle &&other) noexcept
	Moves a FileHandle from another.
FileHandle &	operator= (FileHandle &&fileHandle) noexcept
	Moves a FileHandle from another.
	~FileHandle () noexcept
	Destroys the FileHandle and releases any resources it may have allocated.
IFileSystem *	getFileSystem () const
	Gets the backing IFileSystem for the handle.
StringView	getPath () const
StringView	getFileName () const
void	updateFileInfo () const
	Update file information.
bool	exists () const
	Checks if the file exists on the file system.
bool	isFile () const
	Checks if item is a file.
bool	isDirectory () const
	Checks if item is a directory.
bool	isSymbolicLink () const
	Checks if item is a symbolic link.
Vector< String >	listFiles () const
	List files in directory.
void	traverse (VisitFunc funcFileEntry) const
	Traverse directory tree with callback functions.
void	traverse (VisitFunc funcFile, VisitFunc funcDirectory) const
	Traverse directory tree with callback functions.
void	traverse (FileVisitor &visitor) const
	Traverse directory tree with a visitor.
FileIterator	begin () const
	Gets an iterator that points to the first directory entry.
FileIterator	end () const
	Gets an iterator that points after the last directory entry.
UInt64	getSize () const
	Gets the file size.
Int64	getAccessTime () const
	Gets the time of last access.
Int64	getModificationTime () const
	Gets time of last modification.
FileHandle	getParentDirectory () const
	Gets a FileHandle to the parent directory.
FileHandle	open (StringView path) const
	Opens a new file handle using a relative path from the current file/directory.
bool	createDirectory () const
	Creates a new directory.
bool	removeDirectory (const RemoveDirectoryFlags &flags=RemoveDirectoryFlag::Default) const
	Removes a directory.
void	copyDirectory (const FileHandle &dstDir) const
	Copies a directory recursively.
bool	copy (const FileHandle &dest) const
	Copies a file.
bool	move (const FileHandle &dest) const
	Moves a file.
bool	createLink (const FileHandle &dest) const
	Creates a hard link.
bool	createSymbolicLink (const FileHandle &dest) const
	Creates a symbolic link.
bool	rename (StringView filename) const
	Renames a file or directory.
bool	remove () const
	Removes a file.
FileWatcher	watch (ExecutionContext &executionContext, const FileEvents &events=FileEvent::Default, bool recursive=true) const
	Creates new file system watcher for this file handle.
InputStream	createInputStream (std::ios_base::openmode mode=std::ios_base::in) const
	Creates an input stream to read from the file.
OutputStream	createOutputStream (std::ios_base::openmode mode=std::ios_base::out) const
	Creates an output stream to write to the file.
Optional< String >	readFile () const
	Reads the file contents to a string.
bool	writeFile (StringView content) const
	Write the contents of a string to the file.
	operator bool () const noexcept
bool	operator== (const FileHandle &other) const noexcept
bool	operator!= (const FileHandle &other) const noexcept

Private Member Functions
bool	genericCopy (const FileHandle &dest) const
	Copies the file by stream copy.
bool	genericMove (const FileHandle &dest) const
	Moves a file by stream copy and delete.

Private Attributes
ImplementationType	mImplementation = nullptr
	The file handle implementation.

Detailed Description

Handle for a file or directory.

A file handle is used to access a file or directory. It can be obtained either by calling open() on a FileSystem object, or by iterating over directories using the FileSystemIterator.

If the handle points to a valid file or directory, exists() returns true, otherwise false. The type of the entry can be determined by the methods isFile() and isDirectory().

File handles can be copied or moved. Overhead for these functions are limited, so for example, file or directories will not be opened automatically.

Member Typedef Documentation

ImplementationType

using CeresEngine::FileHandle::ImplementationType = Poly<IFileHandle, sizeof(void*) * 4>

RemoveDirectoryFlags

using CeresEngine::FileHandle::RemoveDirectoryFlags = Flags<RemoveDirectoryFlag>

A set of flags that customize removeDirectory() behavior.

VisitFunc

using CeresEngine::FileHandle::VisitFunc = std::function<bool(const FileHandle&)>

Member Enumeration Documentation

RemoveDirectoryFlag

enum class CeresEngine::FileHandle::RemoveDirectoryFlag

strong

A set of flags that customize removeDirectory() behavior.

Enumerator
FollowSymlinks	To enter/follow symlink directories or not.
Recursive	Whether the file removal should be recursive or not.
None
Default

Constructor & Destructor Documentation

FileHandle() [1/5]

CeresEngine::FileHandle::FileHandle ( )

noexcept

Constructs a new empty FileHandle.

FileHandle() [2/5]

CeresEngine::FileHandle::FileHandle ( const FilePath &  path )

explicit

Creates a new FileHandle from a path on the local file system.

FileHandle() [3/5]

CeresEngine::FileHandle::FileHandle

(

ImplementationType &&

backend

)

Creates a new FileHandle from a concrete implementation.

FileHandle() [4/5]

CeresEngine::FileHandle::FileHandle

(

const FileHandle &

other

)

Copies a FileHandle from another.

FileHandle() [5/5]

CeresEngine::FileHandle::FileHandle ( FileHandle &&  other )

noexcept

Moves a FileHandle from another.

~FileHandle()

CeresEngine::FileHandle::~FileHandle ( )

noexcept

Destroys the FileHandle and releases any resources it may have allocated.

The file won't be deleted.

Member Function Documentation

begin()

FileIterator CeresEngine::FileHandle::begin

(

)

const

Gets an iterator that points to the first directory entry.

Returns

An iterator to the directory contents.

copy()

bool CeresEngine::FileHandle::copy

(

const FileHandle &

dest

)

const

Copies a file.

Parameters

dest	The destination file or directory.

Returns

true if successful, else false.

copyDirectory()

void CeresEngine::FileHandle::copyDirectory

(

const FileHandle &

dstDir

)

const

Copies a directory recursively.

Parameters

dstDir

The destination directory.

Note

The destination directory points to the actual directory that is to be created, not its parent! Example:

FileHandle directory = open("/projects/project1");
directory.copyDirectory(open("/backup/projects/project1"))

createDirectory()

bool CeresEngine::FileHandle::createDirectory

(

)

const

Creates a new directory.

Returns

true if successful, else false.

createInputStream()

InputStream CeresEngine::FileHandle::createInputStream

(

std::ios_base::openmode

mode = std::ios_base::in

)

const

Creates an input stream to read from the file.

Returns

The input stream. Can be nullptr if opening the stream failed.

createLink()

bool CeresEngine::FileHandle::createLink

(

const FileHandle &

dest

)

const

Creates a hard link.

Parameters

dest	The destination file or directory.

Returns

true if successful, else false.

createOutputStream()

OutputStream CeresEngine::FileHandle::createOutputStream

(

std::ios_base::openmode

mode = std::ios_base::out

)

const

Creates an output stream to write to the file.

Returns

The output stream. Can be nullptr if opening the stream failed.

createSymbolicLink()

bool CeresEngine::FileHandle::createSymbolicLink

(

const FileHandle &

dest

)

const

Creates a symbolic link.

Parameters

dest	The destination file or directory.

Returns

true if successful, else false.

end()

FileIterator CeresEngine::FileHandle::end

(

)

const

Gets an iterator that points after the last directory entry.

Returns

An iterator to the directory contents.

exists()

bool CeresEngine::FileHandle::exists

(

)

const

Checks if the file exists on the file system.

Returns

true if it exists, else false.

genericCopy()

bool CeresEngine::FileHandle::genericCopy ( const FileHandle &  dest ) const

private

Copies the file by stream copy.

Parameters

dest	The destination file or directory.

Returns

true if successful, else false.

genericMove()

bool CeresEngine::FileHandle::genericMove ( const FileHandle &  dest ) const

private

Moves a file by stream copy and delete.

Parameters

dest	The destination file or directory.

Returns

true if successful, else false.

getAccessTime()

Int64 CeresEngine::FileHandle::getAccessTime

(

)

const

Gets the time of last access.

getFileName()

StringView CeresEngine::FileHandle::getFileName

(

)

const

Returns

The base name to file or directory

getFileSystem()

IFileSystem * CeresEngine::FileHandle::getFileSystem

(

)

const

Gets the backing IFileSystem for the handle.

Can be nullptr if the handle is empty.

getModificationTime()

Int64 CeresEngine::FileHandle::getModificationTime

(

)

const

Gets time of last modification.

getParentDirectory()

FileHandle CeresEngine::FileHandle::getParentDirectory

(

)

const

Gets a FileHandle to the parent directory.

getPath()

StringView CeresEngine::FileHandle::getPath

(

)

const

Returns

The path to file or directory

getSize()

UInt64 CeresEngine::FileHandle::getSize

(

)

const

Gets the file size.

Returns

The file size if handle points to a file, else 0.

isDirectory()

bool CeresEngine::FileHandle::isDirectory

(

)

const

Checks if item is a directory.

Returns

true if it is a directory, else false.

isFile()

bool CeresEngine::FileHandle::isFile

(

)

const

Checks if item is a file.

Returns

true if it is a file, else false.

isSymbolicLink()

bool CeresEngine::FileHandle::isSymbolicLink

(

)

const

Checks if item is a symbolic link.

Returns

true if it is a symbolic link, else false.

listFiles()

Vector< String > CeresEngine::FileHandle::listFiles

(

)

const

List files in directory.

Returns

The list of files, or an empty list if this is not a valid directory.

move()

bool CeresEngine::FileHandle::move

(

const FileHandle &

dest

)

const

Moves a file.

Parameters

dest	The destination file or directory.

Returns

true if successful, else false.

open()

FileHandle CeresEngine::FileHandle::open

(

StringView

path

)

const

Opens a new file handle using a relative path from the current file/directory.

Parameters

path	The relative path of the new file to open.

Returns

A file handle to the normalize path file.

operator bool()

CeresEngine::FileHandle::operator bool ( ) const

inlineexplicitnoexcept

operator!=()

bool CeresEngine::FileHandle::operator!= ( const FileHandle &  other ) const

noexcept

operator=() [1/2]

FileHandle & CeresEngine::FileHandle::operator=

(

const FileHandle &

other

)

Copies a FileHandle from another.

operator=() [2/2]

FileHandle & CeresEngine::FileHandle::operator= ( FileHandle &&  fileHandle )

noexcept

Moves a FileHandle from another.

operator==()

bool CeresEngine::FileHandle::operator== ( const FileHandle &  other ) const

noexcept

readFile()

Optional< String > CeresEngine::FileHandle::readFile

(

)

const

Reads the file contents to a string.

Returns

The file contents, or an empty optional if reading failed.

remove()

bool CeresEngine::FileHandle::remove

(

)

const

Removes a file.

Returns

true if successful, else false.

Note

Only works if the handle points to a valid file, not a directory.

removeDirectory()

bool CeresEngine::FileHandle::removeDirectory

(

const RemoveDirectoryFlags &

flags = RemoveDirectoryFlag::Default

)

const

Removes a directory.

Returns

true if successful, else false.

Note

If RemoveDirectoryFlag::Recursive is not set, the call will only succeed if the directory exists and is empty.

rename()

bool CeresEngine::FileHandle::rename

(

StringView

filename

)

const

Renames a file or directory.

Parameters

filename

The new file name to rename the file to.

Returns

true if successful, else false.

traverse() [1/3]

void CeresEngine::FileHandle::traverse

(

FileVisitor &

visitor

)

const

Traverse directory tree with a visitor.

Parameters

visitor

Visitor that is invoked for each entry in the directory tree.

traverse() [2/3]

void CeresEngine::FileHandle::traverse	(	VisitFunc	funcFile,
		VisitFunc	funcDirectory
	)		const

Traverse directory tree with callback functions.

Parameters

funcFile	Function that is call on each file.
funcDirectory	Function that is call on each directory.

traverse() [3/3]

void CeresEngine::FileHandle::traverse

(

VisitFunc

funcFileEntry

)

const

Traverse directory tree with callback functions.

Parameters

funcFileEntry

Function that is call on each file entry (files and directories).

updateFileInfo()

void CeresEngine::FileHandle::updateFileInfo

(

)

const

Update file information.

Must reload and update the file information. It will for example be called after a file has been created, copied, or removed to ensure that the file information returned by the handle is correct.

watch()

FileWatcher CeresEngine::FileHandle::watch	(	ExecutionContext &	executionContext,
		const FileEvents &	events = FileEvent::Default,
		bool	recursive = true
	)		const

Creates new file system watcher for this file handle.

Note

This is a shortcut for creating a FileWatcher and adding file handles to watch. Will only work if the file handle points to a valid directory. To watch more than one directory at a time, construct a FileWatcher and add directories to it.. Avoid creating more than one FileWatcher, as OS limits can be reached.

Parameters

events	The events that are watched (a combination of FileEvent values).
recursive	Determines if a directory is watched recursively.

Returns

A new file watcher.

writeFile()

bool CeresEngine::FileHandle::writeFile

(

StringView

content

)

const

Write the contents of a string to the file.

Parameters

content

The contents to write to the file.

Returns

true on success, else false.

Member Data Documentation

mImplementation

ImplementationType CeresEngine::FileHandle::mImplementation = nullptr

mutableprivate

The file handle implementation.

---

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

• /Users/Rogiel/Developer/CeresEngine/Engine/Sources/CeresEngine/Foundation/IO/FileHandle.hpp