xtd - Reference Guide  0.2.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Classes | Static Public Attributes | Public Member Functions | List of all members
xtd::io::directory_info Class Referencefinal

#include <directory_info.h>

Definition

Exposes instance methods for creating, moving, and enumerating through directories and subdirectories. This class cannot be inherited.

Namespace
xtd::io
Library
xtd.core
Example
The following example demonstrates some of the main members of the xtd::io::directory_info class.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Specify the directories you want to manipulate.
directory_info di("c:\\MyDir");
try {
// Determine whether the directory exists.
if (di.exists()) {
// Indicate that the directory already exists.
console::write_line("That path exists already.");
return;
}
// Try to create the directory.
di.create();
console::write_line("The directory was created successfully.");
// Delete the directory.
di.remove();
console::write_line("The directory was deleted successfully.");
}
catch (const system_exception& e) {
console::write_line("The process failed: {0}", e.to_string());
}
}
};
startup_(program);
Example
The following example demonstrates how to copy a directory and its contents.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class copy_dir {
public:
static void copy_all(const directory_info& source, const directory_info& target) {
if (source.full_name().to_lower() == target.full_name().to_lower()) {
return;
}
// Check if the target directory exists, if not, create it.
if (directory::exists(target.full_name()) == false) {
}
// Copy each file into it's new directory.
for (file_info fi : source.get_files()) {
console::write_line("Copying {0}\\{1}", target.full_name(), fi.name());
fi.copy_to(path::combine(target.to_string(), fi.name()), true);
}
// Copy each subdirectory using recursion.
for (directory_info di_source_sub_dir : source.get_directories()) {
directory_info next_target_sub_dir = target.create_subdirectory(di_source_sub_dir.name());
copy_all(di_source_sub_dir, next_target_sub_dir);
}
}
static void main() {
ustring source_directory = "c:\\source_directory";
ustring target_directory = "c:\\target_directory";
directory_info di_source(source_directory);
directory_info di_target(target_directory);
copy_all(di_source, di_target);
}
};
startup_(copy_dir);
// Output will vary based on the contents of the source directory.
Remarks
Use the xtd::io::directory_info class for typical operations such as copying, moving, renaming, creating, and deleting directories.
If you are going to reuse an object several times, consider using the instance method of xtd::io::directory_info instead of the corresponding static methods of the xtd::io::directory class, because a security check will not always be necessary.
Note
In members that accept a path as an input string, that path must be well-formed or an exception is raised. For example, if a path is fully qualified but begins with a space, the path is not trimmed in methods of the class. Therefore, the path is malformed and an exception is raised. Similarly, a path or a combination of paths cannot be fully qualified twice. For example, "c:\temp c:\windows" also raises an exception in most cases. Ensure that your paths are well-formed when using methods that accept a path string.
Remarks
In members that accept a path, the path can refer to a file or just a directory. The specified path can also refer to a relative path or a Universal Naming Convention (UNC) path for a server and share name. For example, all the following are acceptable paths:
  • "c:\\MyDir\\MyFile.txt".
  • "c:\\MyDir".
  • "MyDir\\MySubdir".
  • "\\\\MyServer\\MyShare".
By default, full read/write access to new directories is granted to all users.
For a list of common I/O tasks, see Common I/O Tasks.

Classes

class  directory_iterator
 Represent directory iterator used by xtd::io::directory_info. More...
 
class  file_iterator
 Represent file iterator used by xtd::io::directory_info. More...
 
class  file_system_info_iterator
 Represent file system iterator used by xtd::io::directory_info. More...
 

Static Public Attributes

static const directory_info empty
 Represents the uninitialized xtd::io::directory_info object. This field is constant. More...
 

Public Member Functions

 directory_info (const xtd::ustring &path)
 Initializes a new instance of the xtd::io::directory_info class on the specified path. More...
 
void create ()
 Creates a directory. More...
 
xtd::io::directory_info create_subdirectory (const xtd::ustring &path) const
 Creates a subdirectory or subdirectories on the specified path. The specified path can be relative to this instance of the xtd::io::directory_info class. More...
 
xtd::io::directory_info::directory_iterator enumerate_directories () const
 Returns an enumerable collection of directory information in the current directory. More...
 
xtd::io::directory_info::directory_iterator enumerate_directories (const xtd::ustring &search_pattern) const
 Returns an enumerable collection of directory information that matches a specified search pattern. More...
 
xtd::io::directory_info::file_system_info_iterator enumerate_file_system_infos () const
 Returns an enumerable collection of file system information in the current directory. More...
 
xtd::io::directory_info::file_system_info_iterator enumerate_file_system_infos (const xtd::ustring &search_pattern) const
 Returns an enumerable collection of file system information that matches a specified search pattern. More...
 
xtd::io::directory_info::file_iterator enumerate_files () const
 Returns an enumerable collection of file information in the current directory. More...
 
xtd::io::directory_info::file_iterator enumerate_files (const xtd::ustring &search_pattern) const
 Returns an enumerable collection of file information that matches a search pattern. More...
 
bool exists () const override
 Gets a value indicating whether the directory exists. More...
 
std::vector< xtd::io::directory_infoget_directories () const
 Returns the subdirectories of the current directory. More...
 
std::vector< xtd::io::directory_infoget_directories (const xtd::ustring &search_pattern) const
 Returns an array of directories in the current DirectoryInfo matching the given search criteria. More...
 
std::vector< std::shared_ptr< xtd::io::file_system_info > > get_file_system_infos () const
 Returns an array of strongly typed xtd::io::file_system_info entries representing all the files and subdirectories in a directory. More...
 
std::vector< std::shared_ptr< xtd::io::file_system_info > > get_file_system_infos (const xtd::ustring &search_pattern) const
 Retrieves an array of strongly typed FileSystemInfo objects representing the files and subdirectories that match the specified search criteria. More...
 
std::vector< xtd::io::file_infoget_files () const
 Returns a file list from the current directory. More...
 
std::vector< xtd::io::file_infoget_files (const xtd::ustring &search_pattern) const
 Returns a file list from the current directory matching the given search pattern. More...
 
void move_to (const xtd::ustring &dest_dir_name)
 Moves a DirectoryInfo instance and its contents to a new path. More...
 
xtd::ustring name () const override
 Gets the name of this xtd::io::directory_info instance. More...
 
xtd::io::directory_info parent () const
 Gets the parent directory of a specified subdirectory. More...
 
void remove () const override
 Deletes this xtd::io::directory_info if it is empty. More...
 
void remove (bool recursive) const
 Deletes this instance of a DirectoryInfo, specifying whether to delete subdirectories and files. More...
 
xtd::io::directory_info root () const
 Gets the root portion of the directory. More...
 
- Public Member Functions inherited from xtd::io::file_system_info
xtd::io::file_attributes attributes () const
 Gets the attributes for the current file or directory. More...
 
xtd::io::file_system_infoattributes (xtd::io::file_attributes value)
 Sets the attributes for the current file or directory. More...
 
std::chrono::system_clock::time_point creation_time () const
 Gets the creation time of the current file or directory. More...
 
xtd::io::file_system_infocreation_time (std::chrono::system_clock::time_point value)
 Gets the creation time of the current file or directory. More...
 
virtual xtd::ustring extension () const
 Gets the extension part of the file name, including the leading dot . even if it is the entire file name, or an empty string if no extension is present. More...
 
xtd::ustring full_name () const
 Gets the full path of the directory or file. More...
 
std::chrono::system_clock::time_point last_access_time () const
 Gets the time the current file or directory was last accessed. More...
 
xtd::io::file_system_infolast_access_time (std::chrono::system_clock::time_point value)
 Sets the time the current file or directory was last accessed. More...
 
std::chrono::system_clock::time_point last_write_time () const
 Gets the time when the current file or directory was last written to. More...
 
xtd::io::file_system_infolast_write_time (std::chrono::system_clock::time_point value)
 Sets the time when the current file or directory was last written to. More...
 
void refresh ()
 Refreshes the state of the object. More...
 
xtd::ustring to_string () const noexcept override
 Returns the original path. Use the xtd::io::file_system_info::full_name or xtd::io::file_system_info::name properties for the full path or file/directory name. More...
 

Additional Inherited Members

- Protected Attributes inherited from xtd::io::file_system_info
xtd::ustring full_path_
 Represents the fully qualified path of the directory or file. More...
 
xtd::ustring original_path_
 The path originally specified by the user, whether relative or absolute. More...
 
- Protected Member Functions inherited from xtd::io::file_system_info
 file_system_info ()=default
 Initializes a new instance of the xtd::io::file_system_info class. More...
 

Constructor & Destructor Documentation

◆ directory_info()

xtd::io::directory_info::directory_info ( const xtd::ustring path)

Initializes a new instance of the xtd::io::directory_info class on the specified path.

Parameters
pathA string specifying the path on which to create the xtd::io::directory_info.
Exceptions
xtd::security::security_exceptionThe caller does not have the required permission.
xtd::argument_exceptionpath contains invalid characters such as ", <, >, or |.
xtd::io::path_too_long_exceptionThe specified path, file name, or both exceed the system-defined maximum length.
Example
The following example uses this constructor to create the specified directory and subdirectory, and demonstrates that a directory that contains subdirectories cannot be deleted.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Specify the directories you want to manipulate.
directory_info di1(R"(c:\MyDir)");
directory_info di2(R"(c:\MyDir\temp)");
try {
// Create the directories.
di1.create();
di2.create();
// This operation will not be allowed because there are subdirectories.
console::write_line("I am about to attempt to delete {0}.", di1.name());
di1.remove();
console::write_line("The delete operation was successful, which was unexpected.");
} catch (const system_exception&) {
console::write_line("The delete operation failed as expected.");
}
}
};
startup_(program);
Remarks
This constructor does not check if a directory exists. This constructor is a placeholder for a string that is used to access the disk in subsequent operations.
For a list of common I/O tasks, see Common I/O Tasks.

Member Function Documentation

◆ create()

void xtd::io::directory_info::create ( )

Creates a directory.

Exceptions
xtd::io::io_exceptionThe directory cannot be created.
Example
The following example checks whether a specified directory exists, creates the directory if it does not exist, and deletes the directory.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Specify the directories you want to manipulate.
directory_info di("c:\\MyDir");
try {
// Determine whether the directory exists.
if (di.exists()) {
// Indicate that the directory already exists.
console::write_line("That path exists already.");
return;
}
// Try to create the directory.
di.create();
console::write_line("The directory was created successfully.");
// Delete the directory.
di.remove();
console::write_line("The directory was deleted successfully.");
}
catch (const system_exception& e) {
console::write_line("The process failed: {0}", e.to_string());
}
}
};
startup_(program);
Remarks
If the directory already exists, this method does nothing.
If the directory did not exist before calling this method, then any cached attribute information about the directory will be flushed if the creation is successful.
For a list of common I/O tasks, see Common I/O Tasks.

◆ create_subdirectory()

xtd::io::directory_info xtd::io::directory_info::create_subdirectory ( const xtd::ustring path) const

Creates a subdirectory or subdirectories on the specified path. The specified path can be relative to this instance of the xtd::io::directory_info class.

Parameters
pathThe specified path. This cannot be a different disk volume or Universal Naming Convention (UNC) name.
Returns
The last directory specified in path.
Exceptions
xtd::argument_exceptionpath does not specify a valid file path or contains invalid xtd::io::directory_info characters.
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::io::io_exceptionThe subdirectory cannot be created. -or- A file or directory already has the name specified by path.
xtd::io::path_too_long_exceptionThe specified path, file name, or both exceed the system-defined maximum length.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
xtd::not_supported_exceptionpath contains a colon character (:) that is not part of a drive label ("C:\").
Example
The following example demonstrates creating a subdirectory. In this example, the created directories are removed once created. Therefore, to test this sample, comment out the delete lines in the code.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Create a reference to a directory.
directory_info di("TempDir");
// Create the directory only if it does not already exist.
if (di.exists() == false)
di.create();
// Create a subdirectory in the directory just created.
directory_info dis = di.create_subdirectory("SubDir");
// Process that directory as required.
// ...
// Delete the subdirectory.
dis.remove(true);
// Delete the directory.
di.remove(true);
}
};
startup_(program);
Remarks
Any and all directories specified in path are created, unless some part of path is invalid. The path parameter specifies a directory path, not a file path. If the subdirectory already exists, this method does nothing.
For a list of common I/O tasks, see Common I/O Tasks.

◆ enumerate_directories() [1/2]

xtd::io::directory_info::directory_iterator xtd::io::directory_info::enumerate_directories ( ) const

Returns an enumerable collection of directory information in the current directory.

Returns
An xtd::io::directory_info::directory_iterator of directories in the current directory.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
The following example enumerates the subdirectories under the "My Documents" directory.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Set a variable to the Documents path.
directory_info dirs(doc_path);
for (auto di : dirs.enumerate_directories()) {
console::write_line("{}", di.name());
}
}
};
startup_(program);
Remarks
The xtd::io::directory_info::enumerate_directories and xtd::io::directory_info::get_directories methods differ as follows:
* When you use xtd::io::directory_info::enumerate_directories, you can start enumerating the collection of xtd::io::directory_info objects before the whole collection is returned.
* When you use xtd::io::directory_info::get_directories, you must wait for the whole array of xtd::io::directory_info objects to be returned before you can access the array.
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_directories can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ enumerate_directories() [2/2]

xtd::io::directory_info::directory_iterator xtd::io::directory_info::enumerate_directories ( const xtd::ustring search_pattern) const

Returns an enumerable collection of directory information that matches a specified search pattern.

Parameters
search_patternThe search string to match against the names of directories. This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions.
Returns
An xtd::io::directory_info::directory_iterator of directories that matches search_pattern.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Remarks
searchPattern can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in searchPattern.
Wildcard specifier Matches
* (asterisk) Zero or more characters in that position.
? (question mark) Zero or one character in that position.
Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The searchPattern string "s*" searches for all names in path beginning with the letter "s".
The xtd::io::directory_info::enumerate_directories and xtd::io::directory_info::get_directories methods differ as follows:
* When you use xtd::io::directory_info::enumerate_directories, you can start enumerating the collection of xtd::io::directory_info objects before the whole collection is returned.
* When you use xtd::io::directory_info::get_directories, you must wait for the whole array of xtd::io::directory_info objects to be returned before you can access the array.
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_directories can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ enumerate_file_system_infos() [1/2]

xtd::io::directory_info::file_system_info_iterator xtd::io::directory_info::enumerate_file_system_infos ( ) const

Returns an enumerable collection of file system information in the current directory.

Returns
An xtd::io::directory_info::file_system_info_iterator of file system information in the current directory.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Remarks
The xtd::io::directory_info::enumerate_file_system_infos and xtd::io::directory_info::get_file_system_infos methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_file_system_infos can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ enumerate_file_system_infos() [2/2]

xtd::io::directory_info::file_system_info_iterator xtd::io::directory_info::enumerate_file_system_infos ( const xtd::ustring search_pattern) const

Returns an enumerable collection of file system information that matches a specified search pattern.

Parameters
search_patternThe search string to match against the names of directories. This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions.
Returns
An xtd::io::directory_info::file_system_info_iterator of file system information objects that matches search_pattern.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Remarks
search_pattern can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in search_pattern.
Wildcard specifier Matches
* (asterisk) Zero or more characters in that position.
 ? (question mark) Zero or one character in that position.
Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The search_pattern string "s*" searches for all names in path beginning with the letter "s".
The xtd::io::directory_info::enumerate_file_system_infos and xtd::io::directory_info::get_file_system_infos methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_file_system_infos can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ enumerate_files() [1/2]

xtd::io::directory_info::file_iterator xtd::io::directory_info::enumerate_files ( ) const

Returns an enumerable collection of file information in the current directory.

Returns
An xtd::io::directory_info::file_iterator of the files in the current directory.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
The following example enumerates the files under a specified directory.

If you only need the names of the files, use the static xtd::io::directory class for better performance. For an example, see the xtd::io::directory::enumerate_files method.

#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Create a directory_info of the directory of the files to enumerate.
directory_info dir_info(R"(\\archives1\library\)");
// Get the files iteror.
auto files = dir_info.enumerate_files();
// Show results.
for (auto f : files) {
console::write_line("{0}", f.name());
}
}
};
startup_(program);
Example
The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
directory_info di(R"(C:\ExampleDir)");
console::write_line("No search pattern returns:");
for (auto fi : di.enumerate_files()) {
console::write_line(fi.name());
}
console::write_line("Search pattern *2* returns:");
for (auto fi : di.enumerate_files("*2*")) {
console::write_line(fi.name());
}
console::write_line("Search pattern test?.txt returns:");
for (auto fi : di.enumerate_files("test?.txt")) {
console::write_line(fi.name());
}
}
};
startup_(program);
/*
* This code produces output similar to the following:
* No search pattern returns:
* log1.txt
* log2.txt
* test1.txt
* test2.txt
* test3.txt
* Search pattern *2* returns:
* log2.txt
* test2.txt
* Search pattern test?.txt returns:
* test1.txt
* test2.txt
* test3.txt
*/
Remarks
The xtd::io::directory_info::enumerate_files and xtd::io::directory_info::get_files methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_files can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ enumerate_files() [2/2]

xtd::io::directory_info::file_iterator xtd::io::directory_info::enumerate_files ( const xtd::ustring search_pattern) const

Returns an enumerable collection of file information that matches a search pattern.

Parameters
search_patternThe search string to match against the names of files. This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions.
Returns
An xtd::io::directory_info::file_iterator of files that matches search_pattern.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
The following example shows how to enumerate files in a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.txt.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
directory_info di(R"(C:\ExampleDir)");
console::write_line("No search pattern returns:");
for (auto fi : di.enumerate_files()) {
console::write_line(fi.name());
}
console::write_line("Search pattern *2* returns:");
for (auto fi : di.enumerate_files("*2*")) {
console::write_line(fi.name());
}
console::write_line("Search pattern test?.txt returns:");
for (auto fi : di.enumerate_files("test?.txt")) {
console::write_line(fi.name());
}
}
};
startup_(program);
/*
* This code produces output similar to the following:
* No search pattern returns:
* log1.txt
* log2.txt
* test1.txt
* test2.txt
* test3.txt
* Search pattern *2* returns:
* log2.txt
* test2.txt
* Search pattern test?.txt returns:
* test1.txt
* test2.txt
* test3.txt
*/
Remarks
search_pattern can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in search_pattern.
Wildcard specifier Matches
* (asterisk) Zero or more characters in that position.
 ? (question mark) Zero or one character in that position.
Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The search_pattern string "s*" searches for all names in path beginning with the letter "s".
The xtd::io::directory_info::enumerate_files and xtd::io::directory_info::get_files methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_files can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ exists()

bool xtd::io::directory_info::exists ( ) const
overridevirtual

Gets a value indicating whether the directory exists.

Returns
true if the directory exists; otherwise, false.
Example
The following example demonstrates a use of the Exists property in the context of copying a source directory to a target directory.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::io;
class program {
public:
// Copy a source directory to a target directory.
static void copy_directory(const ustring& source_directory, const ustring& target_directory) {
directory_info source(source_directory);
directory_info target(target_directory);
//Determine whether the source directory exists.
if(!source.exists())
return;
if(!target.exists())
target.create();
//Copy files.
vector<file_info> source_files = source.get_files();
for(size_t i = 0; i < source_files.size(); ++i)
file::copy(source_files[i].full_name(), target.full_name() +"\\" + source_files[i].name(), true);
//Copy directories.
vector<directory_info> source_directories = source.get_directories();
for(size_t j = 0; j < source_directories.size(); ++j)
copy_directory(source_directories[j].full_name(), target.full_name() + "\\" + source_directories[j].name());
}
static void main() {
// Specify the directories you want to manipulate.
copy_directory("D:\\Tools","D:\\NewTools");
}
};
startup_(program);
Remarks
The xtd::io::directory_info::exists property returns false if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file.

Implements xtd::io::file_system_info.

◆ get_directories() [1/2]

std::vector<xtd::io::directory_info> xtd::io::directory_info::get_directories ( ) const

Returns the subdirectories of the current directory.

Returns
An array of xtd::io::directory_info objects.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
The following example retrieves all the directories in the root directory and displays the directory names.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Make a reference to a directory.
directory_info di("c:\\");
// Get a reference to each directory in that directory.
vector<directory_info> di_arr = di.get_directories();
// Display the names of the directories.
for (directory_info dri : di_arr)
console::write_line(dri.name());
}
};
startup_(program);
Remarks
If there are no subdirectories, this method returns an empty array. This method is not recursive.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ get_directories() [2/2]

std::vector<xtd::io::directory_info> xtd::io::directory_info::get_directories ( const xtd::ustring search_pattern) const

Returns an array of directories in the current DirectoryInfo matching the given search criteria.

Parameters
search_patternThe search string to match against the names of directories. This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions.
Returns
An array of type xtd::io::directory_info matching search_pattern.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
TThe following example counts the directories in a path that contain the specified letter.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
try {
directory_info di(R"(c:\)");
// Get only subdirectories that contain the letter "p."
vector<directory_info> dirs = di.get_directories("*p*");
console::write_line("The number of directories containing the letter p is {0}.", dirs.size());
for (directory_info di_next : dirs) {
console::write_line("The number of files in {0} is {1}", di_next, di_next.get_files().size());
}
} catch (const system_exception& e) {
console::write_line("The process failed: {0}", e.to_string());
}
}
};
startup_(program);
Remarks
search_pattern can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in search_pattern.
Wildcard specifier Matches
* (asterisk) Zero or more characters in that position.
 ? (question mark) Zero or one character in that position.
Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The search_pattern string "s*" searches for all names in path beginning with the letter "s".
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ get_file_system_infos() [1/2]

std::vector<std::shared_ptr<xtd::io::file_system_info> > xtd::io::directory_info::get_file_system_infos ( ) const

Returns an array of strongly typed xtd::io::file_system_info entries representing all the files and subdirectories in a directory.

Returns
An array of strongly typed xtd::io::file_system_info entries.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
The following example counts the files and directories under the specified directory.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
try {
console::write_line("Enter the path to a directory:");
// Create a new directory_info object.
directory_info dir(directory);
if (!dir.exists()) {
throw directory_not_found_exception("The directory does not exist.", csf_);
}
// Call the GetFileSystemInfos method.
std::vector<std::shared_ptr<file_system_info>> infos = dir.get_file_system_infos();
console::write_line("Working...");
// Pass the result to the list_directories_and_files
// method defined below.
list_directories_and_files(infos);
// Display the results to the console.
console::write_line("Directories: {0}", directories);
console::write_line("Files: {0}", files);
} catch (const system_exception& e) {
}
}
private:
static void list_directories_and_files(std::vector<std::shared_ptr<file_system_info>> fs_info) {
// Iterate through each item.
for (std::shared_ptr<file_system_info> i : fs_info) {
// Check to see if this is a directory_info object.
if (is<directory_info>(i)) {
// Add one to the directory count.
directories++;
// Cast the object to a directory_info object.
std::shared_ptr<directory_info> d_info = as<directory_info>(i);
// Iterate through all sub-directories.
list_directories_and_files(d_info->get_file_system_infos());
}
// Check to see if this is a FileInfo object.
else if (is<file_info>(i)) {
// Add one to the file count.
files++;
}
}
}
inline static long files = 0;
inline static long directories = 0;
};
startup_(program);
Remarks
The xtd::io::directory_info::enumerate_file_system_infos and xtd::io::directory_info::get_file_system_infos methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_file_system_infos can be more efficient.
This method pre-populates the values of the following xtd::io::file_system_info properties:

◆ get_file_system_infos() [2/2]

std::vector<std::shared_ptr<xtd::io::file_system_info> > xtd::io::directory_info::get_file_system_infos ( const xtd::ustring search_pattern) const

Retrieves an array of strongly typed FileSystemInfo objects representing the files and subdirectories that match the specified search criteria.

Parameters
search_patternThe search string to match against the names of directories and files. This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions.
Returns
An array of strongly typed xtd::io::file_system_info entries.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory.
Example
The following example counts the files and directories that match the specified search pattern.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
try {
console::write_line("Enter the path to a directory:");
ustring directory = console::read_line();
console::write_line("Enter a search string (for example *p*):");
ustring search_string = console::read_line();
// Create a new directory_info object.
directory_info dir(directory);
if (!dir.exists()) {
throw directory_not_found_exception("The directory does not exist.", csf_);
}
// Call the GetFileSystemInfos method.
std::vector<std::shared_ptr<file_system_info>> infos = dir.get_file_system_infos(search_string);
console::write_line("Working...");
// Pass the result to the list_directories_and_files
// method defined below.
list_directories_and_files(infos, search_string);
// Display the results to the console.
console::write_line("Directories: {0}", directories);
console::write_line("Files: {0}", files);
} catch (const system_exception& e) {
}
}
private:
static void list_directories_and_files(std::vector<std::shared_ptr<file_system_info>> fs_info, const ustring& search_string) {
// Iterate through each item.
for (std::shared_ptr<file_system_info> i : fs_info) {
// Check to see if this is a directory_info object.
if (is<directory_info>(i)) {
// Add one to the directory count.
directories++;
// Cast the object to a directory_info object.
std::shared_ptr<directory_info> d_info = as<directory_info>(i);
// Iterate through all sub-directories.
list_directories_and_files(d_info->get_file_system_infos(search_string), search_string);
}
// Check to see if this is a FileInfo object.
else if (is<file_info>(i)) {
// Add one to the file count.
files++;
}
}
}
inline static long files = 0;
inline static long directories = 0;
};
startup_(program);
Remarks
search_pattern can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in search_pattern.
Wildcard specifier Matches
* (asterisk) Zero or more characters in that position.
 ? (question mark) Zero or one character in that position.
Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The search_pattern string "s*" searches for all names in path beginning with the letter "s".
The xtd::io::directory_info::enumerate_file_system_infos and xtd::io::directory_info::get_file_system_infos methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_file_system_infos can be more efficient.
This method pre-populates the values of the following xtd::io::file_system_info properties:

◆ get_files() [1/2]

std::vector<xtd::io::file_info> xtd::io::directory_info::get_files ( ) const

Returns a file list from the current directory.

Returns
An array of type xtd::io::file_info.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory. Example The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.tx
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
directory_info di(R"(C:\ExampleDir)");
console::write_line("No search pattern returns:");
for (auto fi : di.get_files()) {
console::write_line(fi.name());
}
console::write_line("Search pattern *2* returns:");
for (auto fi : di.get_files("*2*")) {
console::write_line(fi.name());
}
console::write_line("Search pattern test?.txt returns:");
for (auto fi : di.get_files("test?.txt")) {
console::write_line(fi.name());
}
}
};
startup_(program);
/*
* This code produces output similar to the following:
* No search pattern returns:
* log1.txt
* log2.txt
* test1.txt
* test2.txt
* test3.txt
* Search pattern *2* returns:
* log2.txt
* test2.txt
* Search pattern test?.txt returns:
* test1.txt
* test2.txt
* test3.txt
*/
Remarks
The xtd::io::directory_info::enumerate_files and xtd::io::directory_info::get_files methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_files can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ get_files() [2/2]

std::vector<xtd::io::file_info> xtd::io::directory_info::get_files ( const xtd::ustring search_pattern) const

Returns a file list from the current directory matching the given search pattern.

Parameters
search_patternThe search string to match against the names of files. This parameter can contain a combination of valid literal path and wildcard (* and ?) characters, but it doesn't support regular expressions.
Returns
An array of type xtd::io::file_info.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory. Example The following example shows how to get a list of files from a directory by using different search options. The example assumes a directory that has files named log1.txt, log2.txt, test1.txt, test2.txt, test3.tx
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
directory_info di(R"(C:\ExampleDir)");
console::write_line("No search pattern returns:");
for (auto fi : di.get_files()) {
console::write_line(fi.name());
}
console::write_line("Search pattern *2* returns:");
for (auto fi : di.get_files("*2*")) {
console::write_line(fi.name());
}
console::write_line("Search pattern test?.txt returns:");
for (auto fi : di.get_files("test?.txt")) {
console::write_line(fi.name());
}
}
};
startup_(program);
/*
* This code produces output similar to the following:
* No search pattern returns:
* log1.txt
* log2.txt
* test1.txt
* test2.txt
* test3.txt
* Search pattern *2* returns:
* log2.txt
* test2.txt
* Search pattern test?.txt returns:
* test1.txt
* test2.txt
* test3.txt
*/
Remarks
search_pattern can be a combination of literal and wildcard characters, but it doesn't support regular expressions. The following wildcard specifiers are permitted in search_pattern.
Wildcard specifier Matches
* (asterisk) Zero or more characters in that position.
 ? (question mark) Zero or one character in that position.
Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The search_pattern string "s*" searches for all names in path beginning with the letter "s".
The xtd::io::directory_info::enumerate_files and xtd::io::directory_info::get_files methods differ as follows:
Therefore, when you are working with many files and directories, xtd::io::directory_info::enumerate_files can be more efficient.
This method pre-populates the values of the following xtd::io::directory_info properties:

◆ move_to()

void xtd::io::directory_info::move_to ( const xtd::ustring dest_dir_name)

Moves a DirectoryInfo instance and its contents to a new path.

Parameters
dest_dir_nameThe name and path to which to move this directory. The destination cannot be another disk volume or a directory with the identical name. It can be an existing directory to which you want to add this directory as a subdirectory.
Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid, such as being on an unmapped drive.
xtd::io::io_exceptionThe directory is not empty. -or- The directory is the application's current working directory. -or- There is an open handle on the directory.
xtd::security::security_exceptionThe caller does not have code access permission to create the directory. Example The following example demonstrates moving a directory.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Make a reference to a directory.
directory_info di("TempDir");
// Create the directory only if it does not already exist.
if (di.exists() == false)
di.create();
// Create a subdirectory in the directory just created.
directory_info dis = di.create_subdirectory("SubDir");
// Move the main directory. Note that the contents move with the directory.
if (directory::exists("NewTempDir") == false)
di.move_to("NewTempDir");
try {
// Attempt to delete the subdirectory. Note that because it has been
// moved, an exception is thrown.
dis.remove(true);
} catch (const system_exception&) {
// Handle this exception in some way, such as with the following code:
// console::write_line("That directory does not exist.");
}
// Point the directory_info reference to the new directory.
//di = directory_info("NewTempDir");
// Delete the directory.
//di.remove(true);
}
};
startup_(program);
Remarks
This method throws an IOException if, for example, you try to move c: to c:, and c:already exists. You must specify "c:\\public\\mydir" as the destDirName parameter, or specify a new directory name such as "c:\\newdir".
This method permits moving a directory to a read-only directory. The read/write attribute of neither directory is affected.
For a list of common I/O tasks, see Common I/O Tasks.

◆ name()

xtd::ustring xtd::io::directory_info::name ( ) const
overridevirtual

Gets the name of this xtd::io::directory_info instance.

Returns
The directory name.
Example
The following example displays the name of the current xtd::io::directory_info instance only.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
directory_info dir(".");
ustring dir_name = dir.name();
console::write_line("directory_info name is {0}.", dir_name);
}
};
startup_(program);
Remarks
This xtd::io::directory_info::name property returns only the name of the directory, such as "Bin". To get the full path, such as "c:\public\Bin", use the xtd::io::directory_info::full_name property.
The xtd::io::directory_info::name property of a xtd::io::directory_info requires no permission (beyond the read permission to the directory necessary to construct the Exists) but can give out the directory name. If it is necessary to hand out a xtd::io::directory_info to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use.
For a list of common I/O tasks, see Common I/O Tasks.

Implements xtd::io::file_system_info.

◆ parent()

xtd::io::directory_info xtd::io::directory_info::parent ( ) const

Gets the parent directory of a specified subdirectory.

Returns
The parent directory, or null if the path is null or if the file path denotes a root (such as \, C:\, or \server).
Exceptions
xtd::security::security_exceptionThe caller does not have the required permission.
Example
The following example refers to the parent directory of a specified directory.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Make a reference to a directory.
directory_info di("TempDir");
// Create the directory only if it does not already exist.
if (di.exists() == false)
di.create();
// Create a subdirectory in the directory just created.
directory_info dis = di.create_subdirectory("SubDir");
// Get a reference to the parent directory of the subdirectory you just made.
directory_info parent_dir = dis.parent();
console::write_line("The parent directory of '{0}' is '{1}'", dis.name(), parent_dir.name());
// Delete the parent directory.
di.remove(true);
}
};
startup_(program);
Remarks
To ensure consistent behavior across versions and to make your intent explicit, retrieve the value of one of the following properties on the xtd::io::directory_info instance returned by xtd::io::directory_info::parent.
For a list of common I/O tasks, see Common I/O Tasks.

◆ remove() [1/2]

void xtd::io::directory_info::remove ( ) const
overridevirtual

Deletes this xtd::io::directory_info if it is empty.

Exceptions
xtd::unauthorized_access_exceptionThe directory contains a read-only file.
xtd::io::directory_not_found_exceptionThe directory described by this xtd::io::directory_info object does not exist or could not be found.
xtd::io::io_exceptionThe directory is not empty. -or- The directory is the application's current working directory. -or- There is an open handle on the directory.
xtd::security::security_exceptionThe caller does not have the required permission.
Example
The following example throws an exception if you attempt to delete a directory that is not empty.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Specify the directories you want to manipulate.
directory_info di1(R"(c:\MyDir)");
try {
// Create the directories.
di1.create();
di1.create_subdirectory("temp");
//This operation will not be allowed because there are subdirectories.
console::write_line("I am about to attempt to delete {0}", di1.name());
di1.remove();
console::write_line("The Delete operation was successful, which was unexpected.");
} catch (const system_exception&) {
console::write_line("The Delete operation failed as expected.");
}
}
};
startup_(program);
Remarks
For a list of common I/O tasks, see Common I/O Tasks.

Implements xtd::io::file_system_info.

◆ remove() [2/2]

void xtd::io::directory_info::remove ( bool  recursive) const

Deletes this instance of a DirectoryInfo, specifying whether to delete subdirectories and files.

Parameters
recursivetrue to delete this directory, its subdirectories, and all files; otherwise, false.
Exceptions
xtd::unauthorized_access_exceptionThe directory contains a read-only file.
xtd::io::directory_not_found_exceptionThe directory described by this xtd::io::directory_info object does not exist or could not be found.
xtd::io::io_exceptionThe directory is not empty. -or- The directory is the application's current working directory. -or- There is an open handle on the directory.
xtd::security::security_exceptionThe caller does not have the required permission.
Example
The following example demonstrates deleting a directory. Because the directory is removed, first comment out the Delete line to test that the directory exists. Then uncomment the same line of code to test that the directory was removed successfully.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Make a reference to a directory.
directory_info di("TempDir");
// Create the directory only if it does not already exist.
if (di.exists() == false)
di.create();
// Create a subdirectory in the directory just created.
directory_info dis = di.create_subdirectory("SubDir");
// Process that directory as required.
// ...
// Delete the subdirectory. The true indicates that if subdirectories
// or files are in this directory, they are to be deleted as well.
dis.remove(true);
// Delete the directory.
di.remove(true);
}
};
startup_(program);
Remarks
If the xtd::io::directory_info has no files or subdirectories, this method deletes the xtd::io::directory_info even if recursive is false. Attempting to delete a xtd::io::directory_info that is not empty when recursive is false throws an xtd::io::io_exception.
For a list of common I/O tasks, see Common I/O Tasks.

◆ root()

xtd::io::directory_info xtd::io::directory_info::root ( ) const

Gets the root portion of the directory.

Returns
An object that represents the root of the directory.
Exceptions
xtd::security::security_exceptionThe caller does not have the required permission.
Example
The following example displays root locations for specified directories.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
directory_info di1(R"(\\tempshare\tempdir)");
directory_info di2("tempdir");
directory_info di3(R"(x:\tempdir)");
directory_info di4(R"(c:\)");
console::write_line("The root path of '{0}' is '{1}'", di1.full_name(), di1.root());
console::write_line("The root path of '{0}' is '{1}'", di2.full_name(), di2.root());
console::write_line("The root path of '{0}' is '{1}'", di3.full_name(), di3.root());
console::write_line("The root path of '{0}' is '{1}'", di4.full_name(), di4.root());
}
};
startup_(program);
/*
* This code produces output similar to the following:
* The root path of '\\tempshare\tempdir' is '\\tempshare\tempdir'
* The root path of 'c:\Projects\ConsoleApplication1\ConsoleApplication1\bin\Debug\tempdir' is 'c:\'
* The root path of 'x:\tempdir' is 'x:\'
* The root path of 'c:\' is 'c:\'
*/

Member Data Documentation

◆ empty

const directory_info xtd::io::directory_info::empty
static

Represents the uninitialized xtd::io::directory_info object. This field is constant.


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