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.
Public Member Functions | Protected Attributes | Protected Member Functions | List of all members
xtd::io::file_system_info Class Referenceabstract

#include <file_system_info.h>

Definition

Provides the base class for both xtd::io::file_info and xtd::io::directory_info objects.

Namespace
xtd::io
Library
xtd.core
Remarks
The xtd::io::file_system_info class contains methods that are common to file and directory manipulation. A xtd::io::file_system_info object can represent either a file or a directory, thus serving as the basis for xtd::io::file_info or xtd::io::directory_info objects. Use this base class when parsing a lot of files and directories.
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"
For a list of common I/O tasks, see Common I/O Tasks.
Example
The following example shows how to loop through all the files and directories, querying some information about each entry.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class program {
public:
static void main() {
// Loop through all the immediate subdirectories of C.
for (ustring entry : directory::get_directories("C:\\")) {
display_file_system_info_attributes(directory_info(entry));
}
// Loop through all the files in C.
for (ustring entry : directory::get_files("C:\\")) {
display_file_system_info_attributes(file_info(entry));
}
}
static void display_file_system_info_attributes(const file_system_info& fsi) {
// Assume that this entry is a file.
ustring entry_type = "File";
// Determine if entry is really a directory
entry_type = "Directory";
}
// Show this entry's type, name, and creation date.
console::write_line("{0} entry {1} was created on {2:D}", entry_type, fsi.full_name(), fsi.creation_time());
}
};
startup_(program);
// Output will vary based on contents of drive C.
// Directory entry C:\Documents and Settings was created on Tuesday, November 25, 2003
// Directory entry C:\Inetpub was created on Monday, January 12, 2004
// Directory entry C:\Program Files was created on Tuesday, November 25, 2003
// Directory entry C:\RECYCLER was created on Tuesday, November 25, 2003
// Directory entry C:\System Volume Information was created on Tuesday, November 2, 2003
// Directory entry C:\WINDOWS was created on Tuesday, November 25, 2003
// File entry C:\IO.SYS was created on Tuesday, November 25, 2003
// File entry C:\MSDOS.SYS was created on Tuesday, November 25, 2003
// File entry C:\pagefile.sys was created on Saturday, December 27, 2003

Public Member Functions

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 bool exists () const =0
 Gets a value indicating whether the file or directory exists. 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...
 
virtual xtd::ustring name () const =0
 
void refresh ()
 Refreshes the state of the object. More...
 
virtual void remove () const =0
 Deletes a file or directory. 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...
 

Protected Attributes

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

 file_system_info ()=default
 Initializes a new instance of the xtd::io::file_system_info class. More...
 

Constructor & Destructor Documentation

◆ file_system_info()

xtd::io::file_system_info::file_system_info ( )
protecteddefault

Initializes a new instance of the xtd::io::file_system_info class.

Member Function Documentation

◆ attributes() [1/2]

xtd::io::file_attributes xtd::io::file_system_info::attributes ( ) const

Gets the attributes for the current file or directory.

Returns
xtd::io::file_attributes of the current xtd::io::file_system_info.
Exceptions
xtd::io::file_not_found_exceptionThe specified file doesn't exist. Only thrown when setting the property value.
xtd::io::directory_not_found_exceptionThe specified path is invalid. For example, it's on an unmapped drive. Only thrown when setting the property value.
xtd::io::path_too_long_exceptionThe specified path, file name, or both exceed the system-defined maximum length.
xtd::argument_exceptionThe specified path, file name, or both exceed the system-defined maximum length.
xtd::io::io_exceptionxtd::io::file_system_info::refresh() cannot initialize the data.
Remarks
The value of the xtd::io::file_system_info::attributes property is pre-cached if the current instance of the xtd::io::file_system_info object was returned from any of the following xtd::io::directory_info methods:
The value may be cached when either the value itself or other xtd::io::file_system_info properties are accessed. To get the latest value, call the xtd::io::file_system_info::refresh method.
If the path doesn't exist as of the last cached state, the return value is static_cast<xtd::io::file_attributes>(-1). xtd::io::file_not_found_exception or xtd::io::directory_not_found_exception can only be thrown when setting the value.
The value of this property is a combination of the archive, compressed, directory, hidden, offline, read-only, system, and temporary file attribute flags.
When you set this value, use the bitwise OR operator (|) to apply more than one value. To retain any existing values in the xtd::io::file_system_info::attributes property, include the value of the xtd::io::file_system_info::attributes property in your assignment. For example:
example_file.attributes(example_file.attributes() | file_attributes::read_only; 
Example
The following example demonstrates the xtd::io::file_system_info::attribute property. This code example is part of a larger example provided for the xtd::io::file_system_info class.
static void display_file_system_info_attributes(const file_system_info& fsi) {
// Assume that this entry is a file.
ustring entry_type = "File";
// Determine if entry is really a directory
entry_type = "Directory";
}
// Show this entry's type, name, and creation date.
console::write_line("{0} entry {1} was created on {2:D}", entry_type, fsi.full_name(), fsi.creation_time());
}

◆ attributes() [2/2]

xtd::io::file_system_info& xtd::io::file_system_info::attributes ( xtd::io::file_attributes  value)

Sets the attributes for the current file or directory.

Parameters
valuextd::io::file_attributes of the current xtd::io::file_system_info.
Exceptions
xtd::io::file_not_found_exceptionThe specified file doesn't exist. Only thrown when setting the property value.
xtd::io::directory_not_found_exceptionThe specified path is invalid. For example, it's on an unmapped drive. Only thrown when setting the property value.
xtd::io::path_too_long_exceptionThe specified path, file name, or both exceed the system-defined maximum length.
xtd::argument_exceptionThe specified path, file name, or both exceed the system-defined maximum length.
xtd::io::io_exceptionxtd::io::file_system_info::refresh() cannot initialize the data.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Remarks
The value of the xtd::io::file_system_info::attributes property is pre-cached if the current instance of the xtd::io::file_system_info object was returned from any of the following xtd::io::directory_info methods:
The value may be cached when either the value itself or other xtd::io::file_system_info properties are accessed. To get the latest value, call the xtd::io::file_system_info::refresh method.
If the path doesn't exist as of the last cached state, the return value is static_cast<xtd::io::file_attributes>(-1). xtd::io::file_not_found_exception or xtd::io::directory_not_found_exception can only be thrown when setting the value.
The value of this property is a combination of the archive, compressed, directory, hidden, offline, read-only, system, and temporary file attribute flags.
When you set this value, use the bitwise OR operator (|) to apply more than one value. To retain any existing values in the xtd::io::file_system_info::attributes property, include the value of the xtd::io::file_system_info::attributes property in your assignment. For example:
example_file.attributes(example_file.attributes() | file_attributes::read_only; 
Example
The following example demonstrates the xtd::io::file_system_info::attribute property. This code example is part of a larger example provided for the xtd::io::file_system_info class.
static void display_file_system_info_attributes(const file_system_info& fsi) {
// Assume that this entry is a file.
ustring entry_type = "File";
// Determine if entry is really a directory
entry_type = "Directory";
}
// Show this entry's type, name, and creation date.
console::write_line("{0} entry {1} was created on {2:D}", entry_type, fsi.full_name(), fsi.creation_time());
}

◆ creation_time() [1/2]

std::chrono::system_clock::time_point xtd::io::file_system_info::creation_time ( ) const

Gets the creation time of the current file or directory.

Returns
The creation date and time of the current xtd::io::file_system_info object.
Exceptions
xtd::io::io_exceptionsystem error when retrieving the file information.
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Example
The following example demonstrates the xtd::io::file_system_info::creation_time property. This code example is part of a larger example provided for the xtd::io::file_system_info class.
static void display_file_system_info_attributes(const file_system_info& fsi) {
// Assume that this entry is a file.
ustring entry_type = "File";
// Determine if entry is really a directory
entry_type = "Directory";
}
// Show this entry's type, name, and creation date.
console::write_line("{0} entry {1} was created on {2:D}", entry_type, fsi.full_name(), fsi.creation_time());
}

◆ creation_time() [2/2]

xtd::io::file_system_info& xtd::io::file_system_info::creation_time ( std::chrono::system_clock::time_point  value)

Gets the creation time of the current file or directory.

Parameters
valueThe creation date and time of the current xtd::io::file_system_info object.
Exceptions
xtd::io::io_exceptionsystem error when retrieving the file information.
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Example
The following example demonstrates the xtd::io::file_system_info::creation_time property. This code example is part of a larger example provided for the xtd::io::file_system_info class.
static void display_file_system_info_attributes(const file_system_info& fsi) {
// Assume that this entry is a file.
ustring entry_type = "File";
// Determine if entry is really a directory
entry_type = "Directory";
}
// Show this entry's type, name, and creation date.
console::write_line("{0} entry {1} was created on {2:D}", entry_type, fsi.full_name(), fsi.creation_time());
}

◆ exists()

virtual bool xtd::io::file_system_info::exists ( ) const
pure virtual

Gets a value indicating whether the file or directory exists.

Returns
true if the file or directory exists; otherwise, false.
Remarks
For a list of common I/O tasks, see Common I/O Tasks.

Implemented in xtd::io::directory_info, and xtd::io::file_info.

◆ extension()

virtual xtd::ustring xtd::io::file_system_info::extension ( ) const
virtual

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.

Returns
A string containing the xtd::io::file_system_info extension.
Remarks
The Extension property returns the FileSystemInfo extension, which starts at, and includes, the last dot (.) in the file's full name. For example:
  • For a file c:.txt, this property returns ".txt".
  • For a file c:.gitignore, this property returns ".gitignore".
  • For a file c:, this property returns an empty string "".
  • For a file c:.b.c, this property returns ".c".
  • When the xtd::io::file_system_info is constructed from a file path with a trailing dot, then that trailing dot is trimmed, so new xtd::io::file_system_info("foo.bar.").extension returns ".bar".
To do this... See the example in this topic...
 Create a text file. How to: Write Text to a File
 Write to a text file. How to: Write Text to a File
 Read from a text file. How to: Read Text to a File
Retrieve the fully qualified path of a file. xtd::io::path::get_full_path
Retrieve only the file name a path. xtd::io::path::get_file_name_without_extension
Retrieve only the directory name from a path. xtd::io::path::get_directory_name
 Change the extension of a file. xtd::io::path::change_extrnsion

◆ full_name()

xtd::ustring xtd::io::file_system_info::full_name ( ) const

Gets the full path of the directory or file.

Returns
A string containing the full path.
Example
The following example demonstrates the xtd::io::file_system_info::full_name property. This code example is part of a larger example provided for the xtd::io::file_system_info class.
static void display_file_system_info_attributes(const file_system_info& fsi) {
// Assume that this entry is a file.
ustring entry_type = "File";
// Determine if entry is really a directory
entry_type = "Directory";
}
// Show this entry's type, name, and creation date.
console::write_line("{0} entry {1} was created on {2:D}", entry_type, fsi.full_name(), fsi.creation_time());
}
Remarks
For example, for a file c:.txt, this property returns "c:\new_file.txt".
For a list of common I/O tasks, see Common I/O Tasks.

◆ last_access_time() [1/2]

std::chrono::system_clock::time_point xtd::io::file_system_info::last_access_time ( ) const

Gets the time the current file or directory was last accessed.

Returns
The time that the current file or directory was last accessed.
Exceptions
xtd::io::io_exceptionsystem error when retrieving the file information.
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Example
The following code example demonstrates the updating of the xtd::io::file_system_info::last_access_time property through a "touch" operation. In this example, the file is "touched", updating the xtd::io::file_system_info::creation_time, xtd::io::file_system_info::last_access_time and xtd::io::file_system_info::last_write_time properties to the current date and time.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class touch {
public:
static void main(const std::vector<ustring>& args) {
// Make sure a filename was provided.
if (args.size() > 0) {
// Verify that the provided filename exists.
if (file::exists(args[0])) {
file_info fi(args[0]);
touch_file(fi);
} else {
console::write_line("Could not find the file: {0}.", args[0]);
}
} else {
console::write_line("No file was specified.");
}
}
static void touch_file(file_system_info& fsi) {
console::write_line("Touching: {0}", fsi.full_name());
// Update the CreationTime, LastWriteTime and LastAccessTime.
try {
auto now = std::chrono::system_clock::now();
fsi.creation_time(now).last_write_time(now).last_access_time(now);
} catch (const system_exception& e) {
console::write_line("Error: {0}", e.message());
}
}
};
startup_(touch);
Note
This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system.
Remarks
The value of the xtd::io::file_system_info::last_access_time property is pre-cached if the current instance of the xtd::io::file_system_info object was returned from any of the following xtd::io::directory_info methods:

◆ last_access_time() [2/2]

xtd::io::file_system_info& xtd::io::file_system_info::last_access_time ( std::chrono::system_clock::time_point  value)

Sets the time the current file or directory was last accessed.

Parameters
valueThe time that the current file or directory was last accessed.
Exceptions
xtd::io::io_exceptionsystem error when retrieving the file information.
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Example
The following code example demonstrates the updating of the xtd::io::file_system_info::last_access_time property through a "touch" operation. In this example, the file is "touched", updating the xtd::io::file_system_info::creation_time, xtd::io::file_system_info::last_access_time and xtd::io::file_system_info::last_write_time properties to the current date and time.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class touch {
public:
static void main(const std::vector<ustring>& args) {
// Make sure a filename was provided.
if (args.size() > 0) {
// Verify that the provided filename exists.
if (file::exists(args[0])) {
file_info fi(args[0]);
touch_file(fi);
} else {
console::write_line("Could not find the file: {0}.", args[0]);
}
} else {
console::write_line("No file was specified.");
}
}
static void touch_file(file_system_info& fsi) {
console::write_line("Touching: {0}", fsi.full_name());
// Update the CreationTime, LastWriteTime and LastAccessTime.
try {
auto now = std::chrono::system_clock::now();
fsi.creation_time(now).last_write_time(now).last_access_time(now);
} catch (const system_exception& e) {
console::write_line("Error: {0}", e.message());
}
}
};
startup_(touch);
Note
This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system.
Remarks
The value of the xtd::io::file_system_info::last_access_time property is pre-cached if the current instance of the xtd::io::file_system_info object was returned from any of the following xtd::io::directory_info methods:

◆ last_write_time() [1/2]

std::chrono::system_clock::time_point xtd::io::file_system_info::last_write_time ( ) const

Gets the time when the current file or directory was last written to.

Returns
The time the current file was last written.
Exceptions
xtd::io::io_exceptionsystem error when retrieving the file information.
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Example
The following code example demonstrates the updating of the xtd::io::file_system_info::last_write_time property through a "touch" operation. In this example, the file is "touched", updating the xtd::io::file_system_info::creation_time, xtd::io::file_system_info::last_access_time and xtd::io::file_system_info::last_write_time properties to the current date and time.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class touch {
public:
static void main(const std::vector<ustring>& args) {
// Make sure a filename was provided.
if (args.size() > 0) {
// Verify that the provided filename exists.
if (file::exists(args[0])) {
file_info fi(args[0]);
touch_file(fi);
} else {
console::write_line("Could not find the file: {0}.", args[0]);
}
} else {
console::write_line("No file was specified.");
}
}
static void touch_file(file_system_info& fsi) {
console::write_line("Touching: {0}", fsi.full_name());
// Update the CreationTime, LastWriteTime and LastAccessTime.
try {
auto now = std::chrono::system_clock::now();
fsi.creation_time(now).last_write_time(now).last_access_time(now);
} catch (const system_exception& e) {
console::write_line("Error: {0}", e.message());
}
}
};
startup_(touch);
Note
This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system.
Remarks
The value of the xtd::io::file_system_info::last_write_time property is pre-cached if the current instance of the xtd::io::file_system_info object was returned from any of the following xtd::io::directory_info methods:

◆ last_write_time() [2/2]

xtd::io::file_system_info& xtd::io::file_system_info::last_write_time ( std::chrono::system_clock::time_point  value)

Sets the time when the current file or directory was last written to.

Parameters
valueThe time the current file was last written.
Exceptions
xtd::io::io_exceptionsystem error when retrieving the file information.
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::platform_not_supported_exceptionThe opration is not supported on the current operating system.
Example
The following code example demonstrates the updating of the xtd::io::file_system_info::last_write_time property through a "touch" operation. In this example, the file is "touched", updating the xtd::io::file_system_info::creation_time, xtd::io::file_system_info::last_access_time and xtd::io::file_system_info::last_write_time properties to the current date and time.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
class touch {
public:
static void main(const std::vector<ustring>& args) {
// Make sure a filename was provided.
if (args.size() > 0) {
// Verify that the provided filename exists.
if (file::exists(args[0])) {
file_info fi(args[0]);
touch_file(fi);
} else {
console::write_line("Could not find the file: {0}.", args[0]);
}
} else {
console::write_line("No file was specified.");
}
}
static void touch_file(file_system_info& fsi) {
console::write_line("Touching: {0}", fsi.full_name());
// Update the CreationTime, LastWriteTime and LastAccessTime.
try {
auto now = std::chrono::system_clock::now();
fsi.creation_time(now).last_write_time(now).last_access_time(now);
} catch (const system_exception& e) {
console::write_line("Error: {0}", e.message());
}
}
};
startup_(touch);
Note
This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system.
Remarks
The value of the xtd::io::file_system_info::last_write_time property is pre-cached if the current instance of the xtd::io::file_system_info object was returned from any of the following xtd::io::directory_info methods:

◆ refresh()

void xtd::io::file_system_info::refresh ( )

Refreshes the state of the object.

Exceptions
xtd::io::io_exceptionA device such as a disk drive is not ready.
Remarks
xtd::io::file_system_info::refresh takes a snapshot of the file from the current file system.
Call xtd::io::file_system_info::refresh before attempting to get the attribute information, or the information will be outdated.

◆ remove()

virtual void xtd::io::file_system_info::remove ( ) const
pure virtual

Deletes a file or directory.

Exceptions
xtd::io::directory_not_found_exceptionThe specified path is invalid; for example, it is on an unmapped drive.
xtd::io::io_exceptionThere is an open handle on the file or directory, and the operating system is Windows XP or earlier. This open handle can result from enumerating directories and files. For more information, see How to: Enumerate Directories and Files.

Implemented in xtd::io::directory_info, and xtd::io::file_info.

◆ to_string()

xtd::ustring xtd::io::file_system_info::to_string ( ) const
overridenoexcept

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.

Returns
A string with the original path.
Note
The string returned by the xtd::io::file_system_info::tto_string method represents the path that was passed to the constructor of the class implementing xtd::io::file_system_info. Instead of calling the xtd::io::file_system_info::to_string method, you should retrieve the value of either of the following properties, depending on your intent:
  • xtd::io::file_system_info::name, to get the name of the file or directory, without any parent path information.
  • xtd::io::file_system_info::full_name, to get the fully qualified path of the file or directory.

Member Data Documentation

◆ full_path_

xtd::ustring xtd::io::file_system_info::full_path_
protected

Represents the fully qualified path of the directory or file.

◆ original_path_

xtd::ustring xtd::io::file_system_info::original_path_
protected

The path originally specified by the user, whether relative or absolute.


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