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

#include <AUI/IO/APath.h>

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

> All members, including inherited

◆ 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

View Page Source Edit Page Source