Used for manipulating Paths. Paths will always exist either as a file or directory. Paths are '/' delimited when forming though may not be while retrieving. File names ".." will ascend a directory and '.' represents a no-op. More...

#include <Path.hpp>

Inheritance diagram for CYB::API::Path:

[legend]

Collaboration diagram for CYB::API::Path:

[legend]

Classes
class	DirectoryEntry
	Iterator for paths in a directory. More...

Public Types
enum	: int { MAX_PATH_BYTES = 256 }

enum	SystemPath { SystemPath::EXECUTABLE_IMAGE, SystemPath::EXECUTABLE, SystemPath::RESOURCE, SystemPath::TEMPORARY, SystemPath::USER, SystemPath::WORKING }
	Starting points for creating paths. More...

using	Constructor = Interop::Constructor< SystemPath >
	See Interop Construction. Get the Path of a given SystemPath. More...

using	CopyConstructor = API::Interop::Constructor< const Path & >
	See Interop Construction.

Public Types inherited from CYB::API::Interop::Allocatable
enum	ID { ID::NULL_ID, ID::File, ID::Mutex, ID::Path, ID::Semaphore }
	Defines the IDs of allocatable engine objects. More...

using	Constructor = NullConstructor
	Override in descendants.

using	CopyConstructor = NullConstructor
	Override in descendants.

Public Member Functions
virtual void	Append (const String::UTF8 &AAppendage, const bool ACreateIfNonExistant, const bool ACreateRecursive)=0
	Append a directory/file to the path. More...

virtual void	NavigateToParentDirectory (void)=0
	Navigate the path to the parent directory. Does NOT work on invalidated paths. More...

virtual void	Delete (bool ARecursive)=0
	Ensures the current Path doesn't exist. This will invalidate the path. More...

virtual bool	IsDirectory (void) const =0
	Check if the current path is a directory. More...

virtual bool	IsFile (void) const =0
	Check if the current path is a file. More...

virtual String::UTF8	FullName (void) const =0
	Get the name of the file without any prefixes. Equivalent to FileName and Extension if the name does not contain a period. Path can point to a file or directory. More...

virtual String::UTF8	Name (void) const =0
	Get the name of the file without any directory prefixes or extensions. Equivalent to FullFileName and Extension if the name does not contain a period. Path can point to a file or directory. More...

virtual String::UTF8	Extension (void) const =0
	Get the extension of the file without the leading period. Equivalent to FullFileName and FileName if the name does not contain a period. Path can point to a file or directory. More...

virtual int	ByteLength (void) const noexcept=0
	Get the length in bytes of the Path's underlying string. More...

virtual Interop::Object < DirectoryEntry >	Contents (void) const =0
	Get the first directory entry iterator in the path. Always valid. More...

virtual const String::UTF8 &	operator() (void) const noexcept=0
	Public access to the underlying string. More...

Public Member Functions inherited from CYB::API::Interop::Allocatable
virtual	~Allocatable ()=default
	See Default Constructors and Destructor.

Static Public Member Functions
static const String::Static	DirectorySeparatorChar (void) noexcept
	Get the standardized UTF-8 directory separator string. More...

Static Public Member Functions inherited from CYB::API::Interop::Allocatable
template<class AParent >
static constexpr ID	GetID (void)
	Returns the ID of an allocatable object. More...

Detailed Description

Used for manipulating Paths. Paths will always exist either as a file or directory. Paths are '/' delimited when forming though may not be while retrieving. File names ".." will ascend a directory and '.' represents a no-op.

Attention: Only UTF-8 encodedable paths are supported, paths lengths may not exceed MAX_PATH_BYTES, and directory names may not exceed 248 characters. Symlinks are always resolved on posix systems, but never on Windows systems. This is a user problem and should cause no errors so long as they do not reorganize the installation files. Note that the recursive folder creation and deletion options attempt to fully adhere to the strong guarantee. But, due to the nature of filesystem race conditions, this is impossible.

Definition at line 9 of file Path.hpp.

Member Typedef Documentation

using CYB::API::Path::Constructor = Interop::Constructor<SystemPath>

See Interop Construction. Get the Path of a given SystemPath.

SystemPath: The SystemPath to begin the path with

Thread Safety: Construction requires no thread safety

Throws: CYB::Exception::Violation Error code: CYB::Exception::Violation::INVALID_ENUM. If an invalid value for ADirectory is given
CYB::Exception::SystemData Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory
CYB::Exception::SystemData Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate
CYB::Exception::SystemData Error code: CYB::Exception::SystemData::SYSTEM_PATH_RETRIEVAL_FAILURE if the specified path could not be retrieved

Definition at line 35 of file Path.hpp.

Member Enumeration Documentation

enum CYB::API::Path::SystemPath

strong

Starting points for creating paths.

Enumerator
EXECUTABLE_IMAGE	The path from which the engine was launched, file, read-only.
EXECUTABLE	The directory from which the engine was launched, read-only.
RESOURCE	The directory where program resources are stored, read-only.
TEMPORARY	The directory for storing data relevant only to this execution.
USER	The directory for storing permanent data associated with the current OS/Steam user, read write.
WORKING	The current application working directory, permissions indeterminate.

Definition at line 15 of file Path.hpp.

                                       {
                     EXECUTABLE_IMAGE,   
                     EXECUTABLE, 
                     RESOURCE,   
                     TEMPORARY,  
                     USER,   
                     WORKING,    
                 };

Member Function Documentation

virtual void CYB::API::Path::Append	(	const String::UTF8 &	AAppendage,
		const bool	ACreateIfNonExistant,
		const bool	ACreateRecursive
	)

pure virtual

Append a directory/file to the path.

Parameters

AAppendage	The string to append to the path. This may contain '/'s and ".."s as required, though they should never start or end with '/'. If the last file in the path does not exist, the function will still succeed, however, further calls on the object will generate a CYB::Exception::SystemData::PATH_LOST error. This is to enable creation of new files
ACreateIfNonExistant	Create the end of path as a directory if it does not exist. If this is true then the last path token in `AAppendage` must not be ".."
ACreateRecursive	Create the path recursively. If this is true none of the path tokens in `AAppendage` should be "..", if one is it will be treated as unreadable. Ignored if `ACreateIfNonExistant` is false

Attention: This function will always fail if the current path is a file

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if a directory component of `AAppendage` could not be read
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if `ACreateIfNonExistant` is true and the new path could not be created. Filesystem state will be reverted even while doing recursive creation
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_TOO_LONG. Thrown if the new path would exceed the limitation
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if the current path failed to verify
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

virtual int CYB::API::Path::ByteLength ( void ) const

pure virtualnoexcept

Get the length in bytes of the Path's underlying string.

Returns: The length in bytes of the Path's underlying string

Thread Safety: This function requires synchronization at the object level

Implemented in CYB::Platform::System::Path.

virtual Interop::Object<DirectoryEntry> CYB::API::Path::Contents ( void ) const

pure virtual

Get the first directory entry iterator in the path. Always valid.

Returns: The first directory entry iterator in the path

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if enumeration permission was denied
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if the current path failed to verify or is not a directory
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

virtual void CYB::API::Path::Delete ( bool ARecursive )

pure virtual

Ensures the current Path doesn't exist. This will invalidate the path.

Parameters

ARecursive If true and IsDirectory() returns true, all files in the directory represented by this path will be deleted along with the directory

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::DIRECTORY_NOT_EMPTY. Thrown if the directory is not empty
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the file/directory could not be deleted
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

static const String::Static CYB::API::Path::DirectorySeparatorChar ( void )

inlinestaticnoexcept

Get the standardized UTF-8 directory separator string.

Returns: '/'

Thread Safety: This function requires no thread safety

Definition at line 74 of file Path.hpp.

74 { return String::Static(u8"/"); }

Here is the caller graph for this function:

virtual String::UTF8 CYB::API::Path::Extension ( void ) const

pure virtual

Get the extension of the file without the leading period. Equivalent to FullFileName and FileName if the name does not contain a period. Path can point to a file or directory.

Returns: The extension of the file without the leading period

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if a directory component of the path could not be read
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

virtual String::UTF8 CYB::API::Path::FullName ( void ) const

pure virtual

Get the name of the file without any prefixes. Equivalent to FileName and Extension if the name does not contain a period. Path can point to a file or directory.

Returns: The name of the file without any directory prefixes

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if a directory component of the path could not be read
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

virtual bool CYB::API::Path::IsDirectory ( void ) const

pure virtual

Check if the current path is a directory.

Returns: true if the current path is a directory, false otherwise

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if a directory component of the path could not be read
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if the current path failed to verify

Implemented in CYB::Platform::System::Path.

virtual bool CYB::API::Path::IsFile ( void ) const

pure virtual

Check if the current path is a file.

Returns: true if the current path is a directory, false otherwise

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if a directory component of the path could not be read
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if the current path failed to verify

Implemented in CYB::Platform::System::Path.

virtual String::UTF8 CYB::API::Path::Name ( void ) const

pure virtual

Get the name of the file without any directory prefixes or extensions. Equivalent to FullFileName and Extension if the name does not contain a period. Path can point to a file or directory.

Returns: The name of the file without any directory prefixes or extensions

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

virtual void CYB::API::Path::NavigateToParentDirectory ( void )

pure virtual

Navigate the path to the parent directory. Does NOT work on invalidated paths.

Attention: On POSIX systems, symlinks in path names are resolved upon path evaluation. This could lead to strange behaviour, though the onus is on the user for changing their file system

Thread Safety: This function requires synchronization at the object level

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if access to parent directory is denied or the Path is currently the root directory.
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STRING_VALIDATION_FAILURE. Thrown if the path string does not validate

Implemented in CYB::Platform::System::Path.

virtual const String::UTF8& CYB::API::Path::operator() ( void ) const

pure virtualnoexcept

Public access to the underlying string.

Returns: The UTF8 string representing the Path

Thread Safety: This function requires synchronization at the object level

Implemented in CYB::Platform::System::Path.

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

Engine/API/Allocatables/Path.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation