APathView#

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

Header:	`#include <AUI/IO/APathView.h>`
CMake:	`aui_link(my_target PUBLIC aui::core)`

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:

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

Public Methods#

absolute#

APath APathView::absolute()

Get the absolute (full) path to the file.

Returns: the absolute (full) path to the file

chmod#

APathView APathView::chmod(int newMode)

Changes mode (permissions) on file

Arguments: newMode
new mode.

It's convenient to use octet literal on newMode:

APath p("file.txt");
p.chmod(0755); // -rwxr-xr-x

exists#

bool APathView::exists()

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

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#

AStringView APathView::extension()

File extension.

Returns: file extension

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

extensionChanged#

APath APathView::extensionChanged(AStringView newExtension)

Returns same path but with extension changed.

file#

APath APathView::file(AStringView fileName)

Path of the child element. Relevant only for folders.

Arguments: fileName
name of child file
Returns: path to child file relatively to this folder

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

It's convient to use / syntax instead:

APath("/home/user") / "work"

Examples:

examples/basic/hello_world/CMakeLists.txt

Console Hello World Example - Basic CLI Hello World application.

cmake_minimum_required(VERSION 3.16)
project(project_template)

# Use AUI.Boot
file(
    DOWNLOAD 
    https://raw.githubusercontent.com/aui-framework/aui/master/aui.boot.cmake 
    ${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
include(${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)

examples/app/game_of_life/CMakeLists.txt

Game of Life - Game of Life implementation that uses advanced large dynamic data rendering techniques such as [ITexture], [AImage] to be GPU friendly. The computation is performed in [AThreadPool].

endif ()

# Uncomment this code to pull AUI:
#
# file(
#         DOWNLOAD
#         https://raw.githubusercontent.com/aui-framework/aui/master/aui.boot.cmake
#         ${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
# include(${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
#

examples/app/notes/CMakeLists.txt

Notes App - Note taking app that demonstrates usage of AListModel, AProperty, user data saving and loading.

cmake_minimum_required(VERSION 3.16)

# Uncomment this code to pull AUI:
#
# file(
#         DOWNLOAD
#         https://raw.githubusercontent.com/aui-framework/aui/master/aui.boot.cmake
#         ${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
# include(${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
#

examples/ui/views/CMakeLists.txt

Views Example - All-in-one views building example.

cmake_minimum_required(VERSION 3.16)

# Uncomment this code to pull AUI:
#
# file(
#         DOWNLOAD
#         https://raw.githubusercontent.com/aui-framework/aui/master/aui.boot.cmake
#         ${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
# include(${CMAKE_CURRENT_BINARY_DIR}/aui.boot.cmake)
#

filename#

APathView APathView::filename()

File name.

Returns: file name

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

filenameWithoutExtension#

APathView APathView::filenameWithoutExtension()

File name without extension.

Returns: file name without extension

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

isAbsolute#

bool APathView::isAbsolute()

Checks whether path absolute or not.

Returns: true if path is absolute

isDirectoryExists#

bool APathView::isDirectoryExists()

Returns: true if folder exists on this path

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 APathView::isEffectivelyAccessible(AFileAccess flags)

Return true if the current process has specified access flags to path.

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

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 APathView::isRegularFileExists()

Returns: true if regular file exists on this path

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 APathView::isRelative()

Checks whether path absolute or not.

Returns: true if path is relative

listDir#

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

Get list of (by default) direct children of this folder. This function outputs paths including the path listDir was called on.

Returns: list of children of this folder.

Use AFileListFlags enum flags to customize behaviour of this function.

makeDir#

APathView APathView::makeDir()

Create folder.

Returns: this

makeDirs#

APathView APathView::makeDirs()

Create all nonexistent folders on the path.

Returns: this

operator#

APath APathView::operator(AStringView filename)

Path of the child element. Relevant only for folders.

Arguments

filename

child to produce path to

AString filename = "file.txt";
APath path = "path" / "to" / "your" / filename;

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

Returns

path to child file relatively to this folder

Examples:

examples/7guis/cells/src/AST.cpp

7GUIs Cells - Spreadsheet processor (Excel).

                    break;
                }

                case got<token::Plus>: {
                    handleBinaryOperator.operator()<BinaryOperatorNodeImpl<std::plus<>>>(Priority::PLUS_MINUS);
                    break;
                }

                case got<token::Minus>: {
                    handleBinaryOperator.operator()<BinaryOperatorNodeImpl<std::minus<>>>(Priority::PLUS_MINUS);

parent#

APath APathView::parent()

Returns: path to parent folder

/home/user -> /home

Examples:

examples/ui/views/tests/LayoutManagerTest.cpp

Views Example - All-in-one views building example.

 */
TEST_F(UILayoutManager, ButtonsAlignment) {
    // buttons column should be perfectly aligned
    By::name("Common button")
        .parent()
        .allChildren()
        .check(leftRightAligned(), "elements should be perfectly aligned");
}

relativelyTo#

AString APathView::relativelyTo(APathView dir)

Returns same path but without dir

Arguments: dir
some parent, grandparent, grandgrandparent... dir
Returns: same path but without dir

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

removeDirContentsRecursive#

APathView APathView::removeDirContentsRecursive()

Delete directory contents (recursively).

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.

removeFile#

APathView APathView::removeFile()

Delete file. Relevant for empty folders and regular files.

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

removeFileRecursive#

APathView APathView::removeFileRecursive()

Delete files recursively, including itself.

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.

systemSlashDirection#

AString APathView::systemSlashDirection()

Transforms this path to string with platform's native slashes.

touch#

const APathView& APathView::touch()

Returns: this.

Creates a file.

withoutUppermostFolder#

APath APathView::withoutUppermostFolder()

Remove the uppermost folder from this path

Returns: The same path except uppermost folder

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