Open 3D Engine AzCore API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AZ::IO::PathView Class Reference

#include <Path.h>

Classes

struct  PathIterable
 

Public Types

using string_view_type = AZStd::string_view
 
using value_type = char
 
using const_iterator = PathIterator< const PathView >
 
using iterator = const_iterator
 

Public Member Functions

constexpr PathView (const PathView &other)=default
 
constexpr PathView (AZStd::string_view pathView) noexcept
 
constexpr PathView (AZStd::string_view pathView, const char preferredSeparator) noexcept
 
constexpr PathView (const value_type *pathString) noexcept
 
constexpr PathView (const value_type *pathString, const char preferredSeparator) noexcept
 
constexpr PathView (const char preferredSeparator) noexcept
 
constexpr PathViewoperator= (const PathView &other)=default
 
constexpr PathViewoperator= (AZStd::string_view pathView) noexcept
 
constexpr PathViewoperator= (const value_type *pathView) noexcept
 
constexpr void swap (PathView &rhs) noexcept
 
constexpr const AZStd::string_viewNative () const noexcept
 Returns string_view stored within the PathView.
 
constexpr AZStd::string_viewNative () noexcept
 
constexpr operator AZStd::string_view () const noexcept
 Conversion operator to retrieve string_view stored within the PathView.
 
constexpr int Compare (const PathView &other) const noexcept
 
constexpr int Compare (AZStd::string_view pathString) const noexcept
 
constexpr int Compare (const value_type *pathString) const noexcept
 
AZStd::string String () const
 
constexpr AZStd::fixed_string< MaxPathLengthFixedMaxPathString () const noexcept
 
constexpr AZStd::fixed_string< MaxPathLengthFixedMaxPathStringAsPosix () const noexcept
 
AZStd::string StringAsPosix () const
 
AZStd::fixed_string< MaxPathLengthAsUri () const noexcept
 
AZStd::string StringAsUri () const
 
AZStd::fixed_string< MaxPathLengthFixedMaxPathStringAsUri () const noexcept
 
constexpr PathView RootName () const
 
constexpr PathView RootDirectory () const
 
constexpr PathView RootPath () const
 
constexpr PathView RelativePath () const
 
constexpr PathView ParentPath () const
 
constexpr PathView Filename () const
 
constexpr PathView Stem () const
 
constexpr PathView Extension () const
 
constexpr bool empty () const noexcept
 Checks if the contained string type element is empty.
 
constexpr bool HasRootName () const
 
constexpr bool HasRootDirectory () const
 Checks if the path has a root directory.
 
constexpr bool HasRootPath () const
 
constexpr bool HasRelativePath () const
 
constexpr bool HasParentPath () const
 checks whether the path has a parent path that is empty
 
constexpr bool HasFilename () const
 Checks whether the filename is empty.
 
constexpr bool HasStem () const
 Checks whether the stem of the filename is empty <stem>[.<ext>].
 
constexpr bool HasExtension () const
 Checks whether the extension of the filename is empty <stem>[.<ext>].
 
constexpr bool IsAbsolute () const
 
constexpr bool IsRelative () const
 Check whether the path is not absolute.
 
constexpr bool IsRelativeTo (const PathView &base) const
 Check whether the path is relative to the base path.
 
constexpr const char PreferredSeparator () const noexcept
 Returns the preferred separator for this instance.
 
constexpr FixedMaxPath LexicallyNormal () const
 
constexpr FixedMaxPath LexicallyRelative (const PathView &base) const
 
constexpr FixedMaxPath LexicallyProximate (const PathView &base) const
 Returns the lexically relative path if it is not an empty path, otherwise it returns the current *this path.
 
constexpr bool Match (AZStd::string_view pathPattern) const
 
constexpr const_iterator begin () const
 
constexpr const_iterator end () const
 

Public Attributes

friend const_iterator
 

Friends

template<typename StringType >
class BasicPath
 
struct AZStd::hash< PathView >
 

Detailed Description

Implementation of a Path class for providing an abstraction of paths on the file system This class represents paths provides an abstraction for paths on a filesystem Only the syntactic parts of a path are handled. The actual paths stored may represent non-existing paths or paths that are not possible on the current OS/filesystem A path name is made up of the following segments

root-name - identifies the root of a filesystem(such as C: or "//myserver")

This is normally only set for paths on Windows OS

root-directory - A directory separator, which if present marks the path as absolute

if missing and the first-element other than the root-name is a filename, then this represents a relative path

  • zero or more of the following:

filename - sequence of characters that aren't directory separators or preferred directory

separators. Filenames may identify a file, hard link, symbolic link, or directory

directory-separators - the forward slash character '/' or the preferred separator character

On windows the preferred separator is '\' If this character is repeated it is treated as a single directory separator i.e /usr///////lib is the same as /usr/lib

Paths can be traversed elmeent wise using the begin()/end() functions This views the path in the generic format and iterators over the path in order of root-name -> root-directory -> file name(0 or more times) directory separators are skipped except for the one that represents the root directory A iterated path element is never empty

Constructor & Destructor Documentation

◆ PathView() [1/4]

constexpr AZ::IO::PathView::PathView ( AZStd::string_view  pathView)
constexprnoexcept

Constructs a PathView by the storing the supplied string_view The preferred separator is to the OS default path separator

◆ PathView() [2/4]

constexpr AZ::IO::PathView::PathView ( AZStd::string_view  pathView,
const char  preferredSeparator 
)
constexprnoexcept

Constructs a PathView by the storing the supplied string_view The preferred separator it set to the parameter

◆ PathView() [3/4]

constexpr AZ::IO::PathView::PathView ( const value_type *  pathString)
constexprnoexcept

Constructs a PathView by storing the value_type* into a string_view The preferred separator is to the OS default path separator

◆ PathView() [4/4]

constexpr AZ::IO::PathView::PathView ( const value_type *  pathString,
const char  preferredSeparator 
)
constexprnoexcept

Constructs a PathView by storing the value_type* into a string_view The preferred separator it set to the parameter

Member Function Documentation

◆ AsUri()

AZStd::fixed_string< MaxPathLength > AZ::IO::PathView::AsUri ( ) const
noexcept

Models the Python pathlib as_uri method Percent encodes the path and appends file: to the front

◆ begin()

constexpr auto AZ::IO::PathView::begin ( ) const
constexpr

Returns an iterator to the beginning of the path that can be used to traverse the path according to the following

  1. Root name - (0 or 1)
  2. Root directory - (0 or 1)
  3. Filename - (0 or more)
  4. Trailing separator - (0 or 1)

◆ Compare()

constexpr int AZ::IO::PathView::Compare ( const PathView other) const
constexprnoexcept

Performs a compare of each of the path parts for equivalence Each part of the path is compare using string comparison Ex: Comparing "test/foo" against "test/fop" returns -1; Path separators of the contained path string aren't compared Ex. Comparing "C:/test\foo" against C:

◆ end()

constexpr auto AZ::IO::PathView::end ( ) const
constexpr

Returns an iterator to the end of the path element This iterator can be safely decremented to point to the last valid path element if it is not equal to the begin iterator

◆ Extension()

constexpr auto AZ::IO::PathView::Extension ( ) const
constexpr

Returns the extension of the filename (or equivalently, the filename of the path with the stem stripped) windows = ".txt", posix = ".txt" NOTE: If the filename is the special "." or ".." path then their is no extension in that case

◆ Filename()

constexpr auto AZ::IO::PathView::Filename ( ) const
constexpr

Returns the filename of the path windows = "name.txt", posix = "name.txt"

◆ FixedMaxPathString()

constexpr AZStd::fixed_string< MaxPathLength > AZ::IO::PathView::FixedMaxPathString ( ) const
constexprnoexcept

extension: fixed string types with MaxPathLength capacity Returns a new instance of an AZStd::fixed_string with capacity of MaxPathLength made from the internal string

◆ FixedMaxPathStringAsPosix()

constexpr AZStd::fixed_string< MaxPathLength > AZ::IO::PathView::FixedMaxPathStringAsPosix ( ) const
constexprnoexcept

Replicates the behavior of the Python pathlib as_posix method by replacing the Windows Path Separator with the Posix Path Seperator

◆ HasRelativePath()

constexpr bool AZ::IO::PathView::HasRelativePath ( ) const
constexpr

checks whether the relative part of path is empty (C:\ O3DE\dev) ^ ^ root part relative part

◆ HasRootName()

constexpr bool AZ::IO::PathView::HasRootName ( ) const
constexpr

Checks if the path has a root name For posix paths this is always empty For windows paths this is the part of the path before the either the root directory or relative path part

◆ HasRootPath()

constexpr bool AZ::IO::PathView::HasRootPath ( ) const
constexpr

Checks whether the entire root path portion of the path is empty The root portion of the path is made up of root_name() / root_directory()

◆ IsAbsolute()

constexpr bool AZ::IO::PathView::IsAbsolute ( ) const
constexpr

Checks whether the contained path represents an absolute path If a path starts with a '/', "<drive letter>:\", "\<network_name>", "\\?\", "\??" or "\\.\"

◆ LexicallyNormal()

constexpr auto AZ::IO::PathView::LexicallyNormal ( ) const
constexpr

Normalizes a path in a purely lexical manner.

Path separators are converted to their preferred path separator

Path parts of "." are collapsed to nothing empty

Paths parts of ".." are removed if there is a preceding directory

The preceding directory is also removed

Runs of Two or more path separators are collapsed into one path separator

unless the path begins with two path separators

Finally any trailing path separators are removed

◆ LexicallyRelative()

constexpr auto AZ::IO::PathView::LexicallyRelative ( const PathView base) const
constexpr

Make the path relative to the supplied base PathView, by using the following rules.

If root_name() != base.root_name() is true, return a default constructed path

(Path can't relative if the root_names are different i.e C: vs F:)

If is_absolute() != base.is_absolute() is true, return a default constructed path

(A relative path can't be formed out of when one path is absolute and the other isn't)

If !has_root_directory() && base.has_root_directory() is true return a default constructed path

(Again if one path contains a root directory and the other doesn't a relative path can't be formed

if any filename in the relative_path() or the base.relative_path() can be interpreted as a root-name

return a default constructed path (This is the occasion of having a "path" such as "foo/bar/C:/foo/bar". Such a path cannot be made relative

Otherwise determine the first mismatch of path parts between *this path and the base as if using

auto [a, b] = AZStd::mismatch(begin(), end(), base.begin(), base.end())

Then if a == end() and b == base.end(), then the paths are equal, return a relative path of "."(represents the same path)

Otherwise define N as the number of non-empty filename elements that are not "." or ".." in [b, base.end()] minus

the number of ".." elements. N is less than 0 then return a default constructed path (This is the case of all the parent directories of base being consumed by the "..". Such as a path of "foo/../bar/../..")

If N == 0 and a == end() or a->empty(), then the paths are equal and retruns a path of "."

(This is the case of a making "a/b/c" relative to a path such as "a/b/c/d/.."

Finally if all the above conditions fail then a path is composed of a default constructed path followed by

N applications of the Path append operator on "..", followed by an application of the path append operator for each element in the range of a[a, end()] (Example of this case is making "/a/d" relative to "/a/b/c". The mismatch happens on "d" for *this and b for base the number of path elements remaining from "b" to "base.end" is 2("b", "c"). Therefore two applications of ".." is formed So the path at this point is "../..", then the remaining elements in the mismatched range for *this is then append There is only 1 element in the range of [a, end()] and that is "d", so the final path becomes "../../d"

◆ Match()

constexpr bool AZ::IO::PathView::Match ( AZStd::string_view  pathPattern) const
constexpr

Returns true if given pattern matches against the path using glob-style pattern expansion The Match algorithm works as follows

If pattern when converted to a PathView results in an empty, return false

If the pattern is relative, then the path can be either absolute or relative and matching is done from the end Ex. AZ::IO::PathView("a/b.ext").Match("*.ext") -> True AZ::IO::PathView("a/b/c.ext").Match("b/*.ext") -> True AZ::IO::PathView("a/b/c.ext").Match("a/*.ext") -> False

If the pattern is absolute, then the path must be absolute and the whole path must match

is done from the end Ex. AZ::IO::PathView("/a.ext").Match("/*.ext") -> True AZ::IO::PathView("a/b.ext").Match("/*.ext") -> False

a glob containing '*' will match a single component of a path

Ex. AZ::IO::PathView("a/b/c.ext").Match("a/*&zwj;/c.ext") -> True Ex. AZ::IO::PathView("a/d/e.ext").Match("a/*&zwj;/*.ext") -> True Ex. AZ::IO::PathView("a/g/h.ext").Match("a/*&zwj;/f.ext") -> False

◆ ParentPath()

constexpr auto AZ::IO::PathView::ParentPath ( ) const
constexpr

Returns the parent directory of filename contained within the path windows = "C:\O3DE\foo\bar", posix = "/O3DE/foo/bar" NOTE: If the path ends with a trailing separator "test/foo/" it is treated as being a path of "test/foo" as if the filename of the path is "foo" and the parent directory is "test"

◆ RelativePath()

constexpr auto AZ::IO::PathView::RelativePath ( ) const
constexpr

Returns the relative path portion of the path. This contains the path parts after the root path windows = "O3DE\foo\bar\name.txt", posix = "O3DE/foo/bar/name.txt"

◆ RootDirectory()

constexpr auto AZ::IO::PathView::RootDirectory ( ) const
constexpr

Returns the root directory part of the path if it has one. This is the root directory separator windows = "\", posix = "/"

◆ RootName()

constexpr auto AZ::IO::PathView::RootName ( ) const
constexpr

Given a windows path of "C:\O3DE\foo\bar\name.txt" and a posix path of "/O3DE/foo/bar/name.txt" The following functions return the following Returns the root name part of the path. if it has one. This is the part of the path before the '/' root directory part windows = "C:", posix = ""

◆ RootPath()

constexpr auto AZ::IO::PathView::RootPath ( ) const
constexpr

Returns the full root path portion of the path made as if it joined the root_name() and root_directory() windows = "C:\", posix = "/"

◆ Stem()

constexpr auto AZ::IO::PathView::Stem ( ) const
constexpr

Returns the filename of the path stripped of it's extension windows = "name", posix = "name" NOTE: If the filename starts with a "." it is treated as part of the stem i.e "home/user/.vimrc"; The stem porttion is ".vimrc" in this case

◆ String()

AZStd::string AZ::IO::PathView::String ( ) const

The string and wstring functions cannot be constexpr until AZStd::basic_string is made constexpr. This cannot occur until C++20 as operator new/delete cannot be used within constexpr functions Returns a new instance of an AZStd::string made from the internal string


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