xtd - Reference Guide  0.1.0 Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
xtd::io::path Class Reference

#include <path.h>

Definition

Performs operations on std::basic_string instances that contain file or directory path information. These operations are performed in a cross-platform manner.

Namespace
xtd::io
Library
xtd.core

Static Public Member Functions

template<typename char_t >
static char_t alt_directory_separator_char () noexcept
Provides a platform-specific alternate character used to separate directory levels in a path string that reflects a hierarchical file system organization. More...

static char alt_directory_separator_char () noexcept
Provides a platform-specific alternate character used to separate directory levels in a path string that reflects a hierarchical file system organization. More...

static xtd::ustring change_extension (const xtd::ustring &path, const xtd::ustring &extension)
Changes the extension of a path string. More...

static xtd::ustring combine (const xtd::ustring &path1, const xtd::ustring &path2)
Combines two path strings. More...

template<typename type1_t , typename type2_t , typename type3_t >
static auto combine (type1_t path1, type2_t path2, type3_t path3) noexcept
Combines three path strings. More...

template<typename type1_t , typename type2_t , typename type3_t , typename type4_t >
static auto combine (type1_t path1, type2_t path2, type3_t path3, type4_t path4) noexcept
Combines four path strings. More...

template<typename path_t >
static xtd::ustring combine (path_t paths) noexcept
Combines path strings array. More...

static xtd::ustring combine (const std::initializer_list< xtd::ustring > &paths) noexcept
Combines path strings array. More...

template<typename char_t >
static char_t directory_separator_char () noexcept
Provides a platform-specific character used to separate directory levels in a path string that reflects a hierarchical file system organization. More...

static char directory_separator_char () noexcept
Provides a platform-specific character used to separate directory levels in a path string that reflects a hierarchical file system organization. More...

static xtd::ustring get_directory_name (const xtd::ustring &path)
Returns the directory information for the specified path string. More...

static xtd::ustring get_extension (const xtd::ustring &path)
Returns the extension of the specified path string. More...

static xtd::ustring get_file_name (const xtd::ustring &path)
Returns the file name and extension of the specified path string. More...

static xtd::ustring get_file_name_without_extension (const xtd::ustring &path)

static xtd::ustring get_full_path (const xtd::ustring &path)
Returns the absolute path for the specified path string. More...

template<typename char_t >
static std::vector< char_t > get_invalid_path_chars () noexcept
Gets an array containing the characters that are not allowed in path names. More...

static std::vector< char > get_invalid_path_chars () noexcept
Gets an array containing the characters that are not allowed in path names. More...

static xtd::ustring get_path_root (const xtd::ustring &path)
Gets the root directory information of the specified path. More...

static xtd::ustring get_random_file_name ()
Returns a random folder name or file name. More...

static xtd::ustring get_temp_file_name ()
Creates a uniquely named, zero-byte temporary file on disk and returns the full path of that file. More...

static xtd::ustring get_temp_path () noexcept
Returns the path of the current user's temporary folder. More...

static bool has_extension (const xtd::ustring &path)
Determines whether a path includes a file name extension. More...

static bool is_path_rooted (const xtd::ustring &path)
Gets a value indicating whether the specified path string contains absolute or relative path information. More...

template<typename char_t >
static char_t path_separator () noexcept
A platform-specific separator character used to separate path strings in environment variables. More...

static char path_separator () noexcept
A platform-specific separator character used to separate path strings in environment variables. More...

template<typename char_t >
static char_t volume_separator_char () noexcept
Provides a platform-specific volume separator character. More...

static char volume_separator_char () noexcept
Provides a platform-specific volume separator character. More...

◆ alt_directory_separator_char() [1/2]

template<typename char_t >
 static char_t xtd::io::path::alt_directory_separator_char ( )
inlinestaticnoexcept

Provides a platform-specific alternate character used to separate directory levels in a path string that reflects a hierarchical file system organization.

Returns
char_t character used to separate directory levels.
Remarks
This method can have the same value as directory_separator_char. alt_directory_separator_char and directory_separator_char are both valid for separating directory levels in a path string.
The value of this field is a slash ('/') on both Windows and Unix-based operating systems.
Examples
The following code example demonstrates the use of the alt_directory_separator_char() property.

◆ alt_directory_separator_char() [2/2]

 static char xtd::io::path::alt_directory_separator_char ( )
staticnoexcept

Provides a platform-specific alternate character used to separate directory levels in a path string that reflects a hierarchical file system organization.

Returns
char character used to separate directory levels.
Remarks
This method can have the same value as directory_separator_char. alt_directory_separator_char and directory_separator_char are both valid for separating directory levels in a path string.
The value of this field is a slash ('/') on both Windows and Unix-based operating systems.
Examples
The following code example demonstrates the use of the alt_directory_separator_char() property.

◆ change_extension()

 static xtd::ustring xtd::io::path::change_extension ( const xtd::ustring & path, const xtd::ustring & extension )
static

Changes the extension of a path string.

Parameters
 path The path information to modify. The path cannot contain any of the characters defined in GetInvalidPathchar_ts. extension The new extension (with or without a leading period). Specify null to remove an existing extension from path.
Returns
string The modified path information.
Note
On Windows-based desktop platforms, if path is an empty string (""), the path information is returned unmodified. If extension is empty string (""), the returned string contains the specified path with its extension removed. If path has no extension, and extension is not empty, the returned path string contains extension appended to the end of path.
Remarks
If neither path nor extension contains a period (.), change_extension adds the period.
The extension parameter can contain multiple periods and any valid path characters, and can be any length. If extension is empty (""), the returned string contains the contents of path with the last period and all characters following it removed.
If extension is an empty string, the returned path string contains the contents of path with any characters following the last period removed.
If extension does not contain a leading period, the period is added.
If path contains a multiple extension separated by multiple periods, the returned string contains the contents of path with the last period and all characters following it replaced by extension. For example, if path is "\Dir1\examples\pathtests.csx.txt" and extension is "cs", the modified path is "\Dir1\examples\pathtests.csx.cs".
It is not possible to verify that the returned results are valid in all scenarios. For example, if path is empty, extension is appended.

◆ combine() [1/5]

 static xtd::ustring xtd::io::path::combine ( const xtd::ustring & path1, const xtd::ustring & path2 )
static

Combines two path strings.

Parameters
 path1 The first path. path2 The second path.
Returns
A string containing the combined paths. If one of the specified paths is a zero-length string, this method returns the other path. If path2 contains an absolute path, this method returns path2.
Remarks
an empty string if path contains one or more of the invalid characters.

◆ combine() [2/5]

template<typename type1_t , typename type2_t , typename type3_t >
 static auto xtd::io::path::combine ( type1_t path1, type2_t path2, type3_t path3 )
inlinestaticnoexcept

Combines three path strings.

Parameters
 path1 The first path. path2 The second path. path3 The third path.
Returns
A string containing the combined paths. If one of the specified paths is a zero-length string, this method returns the other path. If path2 contains an absolute path, this method returns path2.
Remarks
an empty string if path contains one or more of the invalid characters.

◆ combine() [3/5]

template<typename type1_t , typename type2_t , typename type3_t , typename type4_t >
 static auto xtd::io::path::combine ( type1_t path1, type2_t path2, type3_t path3, type4_t path4 )
inlinestaticnoexcept

Combines four path strings.

Parameters
 path1 The first path. path2 The second path. path3 The third path. path4 The fourth path.
Returns
A string containing the combined paths. If one of the specified paths is a zero-length string, this method returns the other path. If path2 contains an absolute path, this method returns path2.
Remarks
an empty string if path contains one or more of the invalid characters.

◆ combine() [4/5]

template<typename path_t >
 static xtd::ustring xtd::io::path::combine ( path_t paths )
inlinestaticnoexcept

Combines path strings array.

Parameters
 paths The path array.
Returns
A string containing the combined paths. If one of the specified paths is a zero-length string, this method returns the other path. If path2 contains an absolute path, this method returns path2.
Remarks
an empty string if path contains one or more of the invalid characters.

◆ combine() [5/5]

 static xtd::ustring xtd::io::path::combine ( const std::initializer_list< xtd::ustring > & paths )
staticnoexcept

Combines path strings array.

Parameters
 paths The path array.
Returns
A string containing the combined paths. If one of the specified paths is a zero-length string, this method returns the other path. If path2 contains an absolute path, this method returns path2.
Remarks
an empty string if path contains one or more of the invalid characters.

◆ directory_separator_char() [1/2]

template<typename char_t >
 static char_t xtd::io::path::directory_separator_char ( )
inlinestaticnoexcept

Provides a platform-specific character used to separate directory levels in a path string that reflects a hierarchical file system organization.

Returns
char_t Platform-specific character used to separate directory levels.
Remarks
alt_directory_separator_char and directory_separator_char are both valid for separating directory levels in a path string.
Examples
The following code example demonstrates the use of the directory_separator_char() property.

◆ directory_separator_char() [2/2]

 static char xtd::io::path::directory_separator_char ( )
staticnoexcept

Provides a platform-specific character used to separate directory levels in a path string that reflects a hierarchical file system organization.

Returns
char Platform-specific character used to separate directory levels.
Remarks
alt_directory_separator_char and directory_separator_char are both valid for separating directory levels in a path string.
Examples
The following code example demonstrates the use of the directory_separator_char() property.

◆ get_directory_name()

 static xtd::ustring xtd::io::path::get_directory_name ( const xtd::ustring & path )
static

Returns the directory information for the specified path string.

Parameters
 path the path of a file or directory.
Returns
A string containing directory information for path, or null if path denotes a root directory, is the empty string ("").
Remarks
Returns string empty if path does not contain directory information.

◆ get_extension()

 static xtd::ustring xtd::io::path::get_extension ( const xtd::ustring & path )
static

Returns the extension of the specified path string.

Parameters
 path The path string from which to get the extension.
Returns
A std::string containing the extension of the specified path (including the ".") or std::string::empty.
Remarks
If path is empty, GetExtension returns string empty. If path does not have extension information, GetExtension returns string empty ("").

◆ get_file_name()

 static xtd::ustring xtd::io::path::get_file_name ( const xtd::ustring & path )
static

Returns the file name and extension of the specified path string.

Parameters
 path The path string from which to obtain the file name and extension.
Returns
The characters after the last directory separator character in path. If the last character of path is a directory or volume separator character, this method returns string empty ("").
Remarks
The separator characters used to determine the start of the file name are directory_separator_char and alt_directory_separator_char.

◆ get_full_path()

 static xtd::ustring xtd::io::path::get_full_path ( const xtd::ustring & path )
static

Returns the absolute path for the specified path string.

Parameters
 path The file or directory for which to obtain absolute path information.
Returns
A string containing the fully qualified location of path, such as "C:\\MyFile.txt".

◆ get_invalid_path_chars() [1/2]

template<typename char_t >
 static std::vector xtd::io::path::get_invalid_path_chars ( )
inlinestaticnoexcept

Gets an array containing the characters that are not allowed in path names.

Returns
An array containing the characters that are not allowed in path names.
Remarks
The array returned from this method is not guaranteed to contain the complete set of characters that are invalid in file and directory names. The full set of invalid characters can vary by file system. For example, on Windows-based desktop platforms, invalid path characters might include ASCII/Unicode characters 1 through 31, as well as quote ("), less than (<), greater than (>), pipe (|), backspace (), null (\0) and tab ().

◆ get_invalid_path_chars() [2/2]

 static std::vector xtd::io::path::get_invalid_path_chars ( )
staticnoexcept

Gets an array containing the characters that are not allowed in path names.

Returns
An array containing the characters that are not allowed in path names.
Remarks
The array returned from this method is not guaranteed to contain the complete set of characters that are invalid in file and directory names. The full set of invalid characters can vary by file system. For example, on Windows-based desktop platforms, invalid path characters might include ASCII/Unicode characters 1 through 31, as well as quote ("), less than (<), greater than (>), pipe (|), backspace (), null (\0) and tab ().

◆ get_path_root()

 static xtd::ustring xtd::io::path::get_path_root ( const xtd::ustring & path )
static

Gets the root directory information of the specified path.

Parameters
 path The path from which to obtain root directory information.
Returns
A string containing the root directory of path, such as "C:\", or null if
path is null, or an empty string if path does not contain root directory
information.

◆ get_random_file_name()

 static xtd::ustring xtd::io::path::get_random_file_name ( )
static

Returns a random folder name or file name.

Returns
A random folder name or file name.
Remarks
The get_random_file_name method returns a cryptographically strong, random string that can be used as either a folder name or a file name. Unlike GetTempFileName, get_random_file_name does not create a file. When the security of your file system is paramount, this method should be used instead of GetTempFileName.

◆ get_temp_file_name()

 static xtd::ustring xtd::io::path::get_temp_file_name ( )
static

Creates a uniquely named, zero-byte temporary file on disk and returns the full path of that file.

Returns
The full path of the temporary file.
Remarks
This method creates a temporary file with a .TMP file extension. The temporary file is created within the user’s temporary folder, which is the path returned by the GetTempPath method.
The GetTempFileName method will raise an IOException if it is used to create more than 65535 files without deleting previous temporary files.
The GetTempFileName method will raise an IOException if no unique temporary file name is available. To resolve this error, delete all unneeded temporary files.

◆ get_temp_path()

 static xtd::ustring xtd::io::path::get_temp_path ( )
staticnoexcept

Returns the path of the current user's temporary folder.

Returns
string The path to the temporary folder, ending with a backslash.
Remarks
This method checks for the existence of environment variables in the following order and uses the first path found:
• The path specified by the TMP environment variable.
• The path specified by the TEMP environment variable.
• The path specified by the USERPROFILE environment variable.
• The Windows directory.

◆ has_extension()

 static bool xtd::io::path::has_extension ( const xtd::ustring & path )
static

Determines whether a path includes a file name extension.

Parameters
 path The path to search for an extension.
Returns
true if the characters that follow the last directory separator (\ or /)
or volume separator (:) in the path include a period (.) followed by one
or more characters; otherwise, false.

◆ is_path_rooted()

 static bool xtd::io::path::is_path_rooted ( const xtd::ustring & path )
static

Gets a value indicating whether the specified path string contains absolute or relative path information.

Parameters
 path The path to test.
Returns
true if path contains an absolute path; otherwise, false.
Remarks
This method also returns false if path is empty or an invalid path.
If the caller does not have sufficient permissions to read the specified file, no exception is thrown and the method returns false regardless of the existence of path.

◆ path_separator() [1/2]

template<typename char_t >
 static char_t xtd::io::path::path_separator ( )
inlinestaticnoexcept

A platform-specific separator character used to separate path strings in environment variables.

Examples
The following code example demonstrates the use of the PathSeparator() property.

◆ path_separator() [2/2]

 static char xtd::io::path::path_separator ( )
staticnoexcept

A platform-specific separator character used to separate path strings in environment variables.

Examples
The following code example demonstrates the use of the PathSeparator() property.

◆ volume_separator_char() [1/2]

template<typename char_t >
 static char_t xtd::io::path::volume_separator_char ( )
inlinestaticnoexcept

Provides a platform-specific volume separator character.

Examples
The following code example demonstrates the use of the volume_separator_char() property.

◆ volume_separator_char() [2/2]

 static char xtd::io::path::volume_separator_char ( )
staticnoexcept

Provides a platform-specific volume separator character.

Examples
The following code example demonstrates the use of the volume_separator_char() property.

The documentation for this class was generated from the following file:
• xtd.core/include/xtd/io/path.h