An add-on to AString with functions for working with the path. More...

#include <AUI/IO/APath.h>

Public Types#
enum	DefaultPath { APPDATA , TEMP , HOME }

Public Types inherited from AString
using	iterator = super::iterator

using	value_type = super::value_type

using	const_iterator = super::const_iterator

using	reverse_iterator = super::reverse_iterator

using	const_reverse_iterator = super::const_reverse_iterator

Public Member Functions#
	APath (AString &&other) noexcept

	APath (const AString &other) noexcept

	APath (const char *utf8) noexcept

	APath (const char *utf8, std::size_t length) noexcept

	APath (const char16_t *str) noexcept

	APath (const char16_t *str, std::size_t length) noexcept

const APath &	touch () const

AString	systemSlashDirection () const
	Transforms this path to string with platform's native slashes.

APath	absolute () const
	Get the absolute (full) path to the file.

ADeque< APath >	listDir (AFileListFlags f=AFileListFlags::DEFAULT_FLAGS) const
	Get list of (by default) direct children of this folder. This function outputs paths including the path listDir was called on.

APath	parent () const

APath	file (const AString &fileName) const
	Path of the child element. Relevant only for folders.

APath	filename () const
	File name.

APath	filenameWithoutExtension () const
	File name without extension.

AString	extension () const
	File extension.

APath	withoutUppermostFolder () const
	Remove the uppermost folder from this path.

bool	exists () const

bool	isRegularFileExists () const

bool	isDirectoryExists () const

const APath &	removeFile () const
	Delete file. Relevant for empty folders and regular files.

const APath &	removeFileRecursive () const
	Delete files recursively, including itself.

const APath &	removeDirContentsRecursive () const
	Delete directory contents (recursively).

const APath &	makeDir () const
	Create folder.

const APath &	makeDirs () const
	Create all nonexistent folders on the path.

AString	relativelyTo (const APath &dir) const
	Returns same path but without `dir`

APath	extensionChanged (const AString &newExtension) const
	Returns same path but with extension changed.

bool	isAbsolute () const
	Checks whether path absolute or not.

bool	isRelative () const
	Checks whether path absolute or not.

time_t	fileModifyTime () const

size_t	fileSize () const

const APath &	chmod (int newMode) const
	Changes mode (permissions) on file.

APath	operator/ (const AString &filename) const
	Path of the child element. Relevant only for folders.

bool	isEffectivelyAccessible (AFileAccess flags) const noexcept
	Return true if the current process has specified access flags to path.

Public Member Functions inherited from AString
	AString (AString &&other) noexcept

	AString (const basic_string &other) noexcept

	AString (const std::string &utf8) noexcept

	AString (const AString &other) noexcept

	AString (const basic_string &rhs, const std::allocator< char16_t > &allocator) noexcept

template<class Iterator>
	AString (Iterator first, Iterator last) noexcept

	AString (char16_t c) noexcept

	AString (const char *utf8) noexcept

	AString (std::string_view utf8) noexcept

	AString (const std::allocator< char16_t > &allocator) noexcept

	AString (const basic_string &rhs, size_type offset, const std::allocator< char16_t > &allocator) noexcept

	AString (const basic_string &rhs, size_type offset, size_type count, const std::allocator< char16_t > &allocator) noexcept

	AString (const char16_t *cStyleString, size_type count) noexcept

	AString (const char16_t *cStyleString, size_type count, const std::allocator< char16_t > &allocator) noexcept

	AString (const char16_t *cStyleString) noexcept

	AString (const char16_t *cStyleString, const std::allocator< char16_t > &allocator) noexcept

	AString (size_type count, char16_t _Ch) noexcept

	AString (size_type count, char16_t _Ch, const std::allocator< char16_t > &allocator) noexcept

	AString (basic_string &&rhs) noexcept

	AString (basic_string &&rhs, const std::allocator< char16_t > &allocator) noexcept

	AString (std::initializer_list< char16_t > _Ilist) noexcept

void	push_back (char16_t c) noexcept

void	pop_back () noexcept

AString	uppercase () const

AString	lowercase () const

bool	startsWith (const AString &other) const noexcept

bool	startsWith (char16_t c) const noexcept

bool	endsWith (const AString &other) const noexcept

bool	endsWith (char16_t c) const noexcept

AStringVector	split (char16_t c) const noexcept

size_type	find (char c, size_type offset=0) const noexcept

size_type	find (char16_t c, size_type offset=0) const noexcept

size_type	find (const AString &str, size_type offset=0) const noexcept

size_type	rfind (char c, size_type offset=NPOS) const noexcept

size_type	rfind (char16_t c, size_type offset=NPOS) const noexcept

size_type	rfind (const AString &str, size_type offset=NPOS) const noexcept

size_type	length () const noexcept

AString	trimLeft (char16_t symbol=' ') const noexcept

AString	trimRight (char16_t symbol=' ') const noexcept

AString	trim (char16_t symbol=' ') const noexcept

void	reserve (size_t s)

void	resize (size_t s)

AString	restrictLength (size_t s, const AString &stringAtEnd="...") const

char16_t *	data () noexcept

const char16_t *	data () const noexcept

AString &	replaceAll (const AString &from, const AString &to)

AString	replacedAll (const AString &from, const AString &to) const

AString	replacedAll (char16_t from, char16_t to) const noexcept

AString	replacedAll (const ASet< char16_t > &from, char16_t to) const noexcept

AString &	replaceAll (char16_t from, char16_t to) noexcept

template<typename OtherContainer>
void	insertAll (const OtherContainer &c) noexcept
	Inserts all values of the specified container to the end.

AOptional< float >	toFloat () const noexcept
	Converts the string to a float number.

AOptional< double >	toDouble () const noexcept
	Converts the string to a double number.

double	toDoubleOrException () const noexcept
	Converts the string to a double number.

AOptional< int >	toInt () const noexcept
	Converts the string to int value.

int	toIntOrException () const
	Converts the string to int value.

AOptional< int64_t >	toLongInt () const noexcept
	Converts the string to int value.

int64_t	toLongIntOrException () const
	Converts the string to int value.

AOptional< unsigned >	toUInt () const noexcept
	Converts the string to int value.

unsigned	toUIntOrException () const
	Converts the string to int value.

bool	toBool () const noexcept
	Converts the string to boolean value.

bool	contains (char16_t c) const noexcept

bool	contains (const AString &other) const noexcept

AOptional< int >	toNumber (aui::ranged_number< int, 2, 36 > base=TO_NUMBER_BASE_DEC) const noexcept
	Returns the string converted to an int using base. Returns std::nullopt if the conversion fails.

int	toNumberOrException (aui::ranged_number< int, 2, 36 > base=TO_NUMBER_BASE_DEC) const
	Returns the string converted to an int using base. Throws an exception if the conversion fails.

std::string	toStdString () const noexcept

void	resizeToNullTerminator ()

iterator	erase (const_iterator begin, const_iterator end) noexcept

iterator	erase (const_iterator begin) noexcept

AString &	erase (size_type offset) noexcept

AString &	erase (size_type offset, size_type count) noexcept

AByteBuffer	toUtf8 () const noexcept

void	removeAt (unsigned at) noexcept

AString	excessSpacesRemoved () const noexcept

iterator	insert (size_type at, char16_t c) noexcept

iterator	insert (size_type at, const AString &c) noexcept

template<typename Iterator>
iterator	insert (const_iterator at, Iterator begin, Iterator end) noexcept

AString &	operator<< (char c) noexcept

AString &	operator<< (char16_t c) noexcept

inline ::AString &	operator+= (const AString &str) noexcept

inline ::AString &	operator+= (const char *str) noexcept

bool	empty () const noexcept

size_type	size () const noexcept

char16_t	operator[] (size_type index) const

char16_t &	operator[] (size_type index)

bool	operator< (const AString &other) const noexcept

void	clear () noexcept

char16_t &	front () noexcept

char16_t &	back () noexcept

const char16_t &	front () const noexcept

const char16_t &	back () const noexcept

char16_t &	first () noexcept

char16_t &	last () noexcept

const char16_t &	first () const noexcept

const char16_t &	last () const noexcept

AOptional< char16_t >	firstOpt () const noexcept

AOptional< char16_t >	lastOpt () const noexcept

const char16_t *	c_str () const

iterator	begin () noexcept

iterator	end () noexcept

const_iterator	begin () const noexcept

const_iterator	end () const noexcept

reverse_iterator	rbegin () noexcept

reverse_iterator	rend () noexcept

const_reverse_iterator	rbegin () const noexcept

const_reverse_iterator	rend () const noexcept

AString &	append (const AString &s) noexcept

AString &	append (size_t count, char16_t ch) noexcept

AString &	operator= (const AString &value) noexcept

AString &	operator= (AString &&value) noexcept

bool	operator== (const AString &other) const noexcept

bool	operator== (const char16_t *other) const noexcept

size_t	sizeInBytes () const noexcept

bool	operator!= (const AString &other) const noexcept

bool	operator!= (const char16_t *other) const noexcept

bool	operator== (const char *other) const noexcept

bool	operator!= (const char *other) const noexcept

template<typename... Args>
AString	format (Args &&... args) const

AString	processEscapes () const

AString &	removeAll (char16_t c) noexcept

AString	substr (std::size_t offset, std::size_t count=npos) const

Static Public Member Functions#
static const APath &	processTemporaryDir ()
	Generates a unique, process-agnostic temporary directory in the system's temp directory.

static APath	nextRandomTemporary ()
	Creates a path to non-existent random file in system temp directory.

static APath	getDefaultPath (DefaultPath path)
	Get system's default folder.

static void	copy (const APath &source, const APath &destination)
	Copy regular file.

static void	move (const APath &source, const APath &destination)
	Move regular file.

static APath	workingDir ()

static AVector< APath >	find (const AString &filename, const AVector< APath > &locations, APathFinder flags=APathFinder::NONE)

Static Public Member Functions inherited from AString
static AString	fromLatin1 (const AByteBuffer &buffer)

static AString	fromUtf8 (const AByteBufferView &buffer)

static AString	fromUtf8 (const char *buffer, size_t length)

static AString	fromLatin1 (const char *buffer)

static AString	numberHex (int i) noexcept

template<typename T, std::enable_if_t< std::is_integral_v< std::decay_t< T > >\|\|std::is_floating_point_v< std::decay_t< T > >, int > = 0>
static AString	number (T i) noexcept

Additional Inherited Members#
Static Public Attributes inherited from AString
auto static constexpr	NPOS = super::npos

static constexpr auto	TO_NUMBER_BASE_BIN = 2

static constexpr auto	TO_NUMBER_BASE_OCT = 8

static constexpr auto	TO_NUMBER_BASE_DEC = 10

static constexpr auto	TO_NUMBER_BASE_HEX = 16

Detailed Description#

Note: In most file systems, both a regular file and a folder with the same name can exist on the same path.

Example usage:

APath someDir = "someDir";

APath filePath = someDir / "myfile.txt"; // "/" replaced with a system file separator

Note

Sometimes the word "file" refers to both a regular file (txt, png, jpeg, etc.) and a folder (directory, a file that contains other regular files and folders), i.e. a unit of the file system, which is often a confusion in terminology. Here and further:

file - a unit of the file system.
regular file - a file that can be read or written to. You can think of as a sequence of bytes or a stream of bytes.
folder (directory) - a file that may have child files (both regular files and folders)

Examples: /home/runner/work/aui/aui/aui.json/src/AUI/Json/Conversion.h, and examples/ui/views/src/ExampleWindow.cpp.

Member Enumeration Documentation#

◆ DefaultPath#

enum APath::DefaultPath

Enumerator

APPDATA

Folder for application data.

Windows-specific: Maps to C:/Users/ user% /.appdata/Roaming/.

Linux-specific: Maps to $HOME/.local/share/.

Android-specific: Maps to \<internal_storage_path\>/__aui_appdata.

iOS-specific: Maps to \<internal_storage_path\>/__aui_appdata.

TEMP

Folder for temporary data.

Windows-specific: Maps to user's temp folder temp%.

Linux-specific: Maps to system temp directory /tmp.

macOS-specific: Maps to system temp directory /tmp.

Android-specific: Maps to AUI-managed temporary directory: \<internal_storage_path\>/__aui_tmp.

iOS-specific: Maps to AUI-managed temporary directory: \<internal_storage_path\>/__aui_tmp.

HOME

User home directory.

Windows-specific: Maps to user's home folder C:\\Users\\ user%.

Linux-specific: Maps to user's home folder /home/$USER.

Member Function Documentation#

◆ absolute()#

APath APath::absolute ( ) const

Returns: the absolute (full) path to the file

◆ chmod()#

const APath & APath::chmod ( int newMode ) const

Parameters

newMode new mode.

It's convenient to use octet literal on newMode:

APath p("file.txt");

p.chmod(0755); // -rwxr-xr-x

◆ copy()#

static void APath::copy	(	const APath &	source,
		const APath &	destination )

static

Parameters

source	source file
destination	destination file

◆ exists()#

bool APath::exists ( ) const

Returns: true if whether regular file or a folder exists on this path

Note: A file can exist as a regular file or(and) as a folder. This function will return false only if neither the folder nor the file does not exists on this path.

Checkout the isRegularFileExists or isDirectoryExists function to check which type of the file exists on this path.

◆ extension()#

AString APath::extension ( ) const

nodiscard

`/home/user/file.cpp -> cpp

Returns: file extension

◆ file()#

APath APath::file ( const AString & fileName ) const

nodiscard

with fileName = work: /home/user -> /home/user/work

Note: It's convient to use / syntax instead:
APath("/home/user") / "work"

Parameters

fileName name of child file

Returns: path to child file relatively to this folder

◆ filename()#

APath APath::filename ( ) const

nodiscard

/home/user/file.cpp -> file.cpp

Returns: file name

◆ filenameWithoutExtension()#

APath APath::filenameWithoutExtension ( ) const

nodiscard

`/home/user/file.cpp -> file

Returns: file name without extension

◆ find()#

static AVector< APath > APath::find	(	const AString &	filename,
		const AVector< APath > &	locations,
		APathFinder	flags = APathFinder::NONE )

static

Searches for file in specified dirs.

Parameters

filename	Name of the file searching for
locations	paths to directories to search for the file in
flags	lookup flags (see APathFinder)

Returns: full path to the found file; if file not found, an empty string is returned.

◆ getDefaultPath()#

static APath APath::getDefaultPath ( DefaultPath path )

static

Note: See the APath::DefaultPath definition.

Returns: absolute path to default folder.

◆ isAbsolute()#

bool APath::isAbsolute ( ) const

Returns: true if path is absolute

◆ isDirectoryExists()#

bool APath::isDirectoryExists ( ) const

Returns: true if folder exists on this path

Note: A file can exist as a regular file or(and) as a folder. This function will return false only if folder does not exists on this path.

◆ isEffectivelyAccessible()#

bool APath::isEffectivelyAccessible ( AFileAccess flags ) const

nodiscardnoexcept

Checks permissions and existence of the file identified by this APath using the real user and group identifiers of the process, like if the file were opened by open().

Note: Using this function to check a process's permissions on a file before performing some operation based on that information leads to race conditions: the file permissions may change between the two steps. Generally, it is safer just to attempt the desired operation and handle any permission error that occurs.

◆ isRegularFileExists()#

bool APath::isRegularFileExists ( ) const

Returns: true if regular file exists on this path

Note: A file can exist as a regular file or(and) as a folder. This function will return false only if regular file does not exists on this path.

◆ isRelative()#

bool APath::isRelative ( ) const

inline

Returns: true if path is relative

◆ listDir()#

ADeque< APath > APath::listDir ( AFileListFlags f = AFileListFlags::DEFAULT_FLAGS ) const

Note: Use AFileListFlags enum flags to customize behaviour of this function.

See also: relativelyTo

Returns: list of children of this folder.

◆ makeDir()#

const APath & APath::makeDir ( ) const

Returns: this

◆ makeDirs()#

const APath & APath::makeDirs ( ) const

Returns: this

◆ move()#

static void APath::move	(	const APath &	source,
		const APath &	destination )

static

Parameters

source	source file
destination	destination file

◆ nextRandomTemporary()#

static APath APath::nextRandomTemporary ( )

staticnodiscard

The file is guaranteed to be non-existent, however, its parent directory does. The such path can be used for general purposes. The application might create any kind of file on this location (including dirs) or don't create any file either.

See also: APathOwner; APath:processTemporaryDir:

◆ operator/()#

APath APath::operator/ ( const AString & filename ) const

inlinenodiscard

Parameters

filename

child to produce path to

AString filename = "file.txt";

APath path = "path" / "to" / "your" / filename;

APath::filename

APath filename() const

File name.

Which would supplyValue into "path/to/your/file.txt"

Returns: path to child file relatively to this folder

◆ parent()#

APath APath::parent ( ) const

nodiscard

/home/user -> /home

Returns: path to parent folder

◆ processTemporaryDir()#

static const APath & APath::processTemporaryDir ( )

staticnodiscard

Creates a safe and islocated workspace for each application instance. By generating a new directory for each process, it prevents, potential conflicts between concurrent processes.

When the application closes, a directory cleanup attempt will be performed.

See also: APath::nextRandomTemporary

Returns: Path to a process-agnostic empty pre-created directory in system temp directory.

◆ relativelyTo()#

AString APath::relativelyTo ( const APath & dir ) const

Parameters

dir	some parent, grandparent, grandgrandparent... dir

APath("C:/work/mon/test.txt").relativelyTo("C:/work") -> mon/test.txt

Returns: same path but without dir

◆ removeDirContentsRecursive()#

const APath & APath::removeDirContentsRecursive ( ) const

Returns: this

If this APath points to a regular file, the function has no effect. If this APath points to a directory, it removes all contained files (recursively) within that directory but does not remove the directory itself.

If the target does not exist, this function has no effect.

See also: APath::removeFileRecursive()

◆ removeFile()#

const APath & APath::removeFile ( ) const

Returns: this

Unlike remove*Recursive functions, this function has no checks before proceeding, thus, it might throw AIOException (including if the target does not exist).

See also: APath::removeFileRecursive(); APath::removeDirContentsRecursive()

◆ removeFileRecursive()#

const APath & APath::removeFileRecursive ( ) const

Returns: this

If this APath points to a regular file, it deletes the file directly. If this APath points to a directory, it first removes all its contents (recursively) before potentially deleting the directory itself.

If the target does not exist, this function has no effect.

See also: APath::removeDirContentsRecursive()

◆ systemSlashDirection()#

AString APath::systemSlashDirection ( ) const

Windows-specific: Returns path with backward slashes \\.

On any other platform, returns path with forward slashes /.

◆ touch()#

const APath & APath::touch ( ) const

Creates a file.

Returns: this.

◆ withoutUppermostFolder()#

APath APath::withoutUppermostFolder ( ) const

nodiscard

v1.0.0/client/azaza.zip -> client/azaza.zip

Returns: The same path except uppermost folder

◆ workingDir()#

static APath APath::workingDir ( )

static

Returns: working dir of application

Contents

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

View Page Source Edit Page Source

Public Types#

Public Member Functions#

Static Public Member Functions#

Additional Inherited Members#

Detailed Description#

Member Enumeration Documentation#

◆ DefaultPath#

Member Function Documentation#

◆ absolute()#

◆ chmod()#

◆ copy()#

◆ exists()#

◆ extension()#

◆ file()#

◆ filename()#

◆ filenameWithoutExtension()#

◆ find()#

◆ getDefaultPath()#

◆ isAbsolute()#

◆ isDirectoryExists()#

◆ isEffectivelyAccessible()#

◆ isRegularFileExists()#

◆ isRelative()#

◆ listDir()#

◆ makeDir()#

◆ makeDirs()#

◆ move()#

◆ nextRandomTemporary()#

◆ operator/()#

◆ parent()#

◆ processTemporaryDir()#

◆ relativelyTo()#

◆ removeDirContentsRecursive()#

◆ removeFile()#

◆ removeFileRecursive()#

◆ systemSlashDirection()#

◆ touch()#

◆ withoutUppermostFolder()#

◆ workingDir()#

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description