xtd::io::file Class Reference

#include <file.h>

Definition

Provides static methods for the creation, copying, deletion, moving, and opening of files, and aids in the creation of std::fstream objects.

Namespace

xtd::io

Library

xtd.core

Inherits xtd::static_object.

Static Public Member Functions
template<typename type_t >
static void	append_all_lines (const xtd::ustring &path, const std::initializer_list< type_t > &contents)
	Appends lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.
template<typename type_t >
static void	append_all_lines (const xtd::ustring &path, type_t contents)
	Appends lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.
template<typename type_t >
static void	append_all_text (const xtd::ustring &path, type_t text)
	Appends text to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.
static std::ofstream	append_text (const xtd::ustring &path)
	Creates a std::ofstream that appends text to an existing file.
static void	copy (const xtd::ustring &src, const xtd::ustring &dest)
	Copies an existing file to a new file. Overwriting a file of the same name is not allowed.
static void	copy (const xtd::ustring &src, const xtd::ustring &dest, bool overwrite)
	Copies an existing file to a new file. Overwriting a file of the same name is allowed.
static std::ofstream	create (const xtd::ustring &path)
	Creates or overwrites a file in the specified path.
static std::ofstream	create_text (const xtd::ustring &path)
	Creates or opens a file for writing text.
static bool	exists (const xtd::ustring &path) noexcept
	Determines whether the specified file exists.
static xtd::io::file_attributes	get_attributes (const xtd::ustring &src)
	Gets the xtd::io::file_attributes of the file on the path.
static void	move (const xtd::ustring &src, const xtd::ustring &dest)
	Moves a specified file to a new location, providing the option to specify a new file name.
static std::fstream	open (const xtd::ustring &path, std::ios::openmode mode)
	Opens a FileStream on the specified path.
static std::ifstream	open_read (const xtd::ustring &path)
	Opens an existing file for reading.
static std::ifstream	open_text (const xtd::ustring &path)
	Opens an existing file for reading.
static std::ofstream	open_write (const xtd::ustring &path)
	Opens an existing file for writing.
template<typename char_t >
static std::vector< uint8_t >	read_all_bytes (const char_t *path)
	Opens a binary file, reads the contents of the file into a byte array, and then closes the file.
static std::vector< uint8_t >	read_all_bytes (const xtd::ustring &path)
	Opens a binary file, reads the contents of the file into a byte array, and then closes the file.
static std::vector< xtd::ustring >	read_all_lines (const xtd::ustring &path)
	Opens a text file, reads all lines of the file, and then closes the file.
static xtd::ustring	read_all_text (const xtd::ustring &path)
	Opens a text file, reads all text of the file, and then closes the file.
static void	remove (const xtd::ustring &path)
	Deletes the specified file.
static void	replace (const xtd::ustring &source_file_name, const xtd::ustring &destination_file_name, const xtd::ustring &destination_backup_file_name)
	Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file and optionally ignores merge errors.
template<typename type_t >
static void	write_all_lines (const xtd::ustring &path, const std::initializer_list< type_t > &contents)
	Writes lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.
template<typename type_t >
static void	write_all_lines (const xtd::ustring &path, type_t contents)
	Writes lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.
template<typename type_t >
static void	write_all_text (const xtd::ustring &path, type_t text)
	Writes text to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.
static std::ofstream	write_text (const xtd::ustring &path)
	Creates a std::ofstream that appends text to an existing file.

Member Function Documentation

append_all_lines() [1/2]

template<typename type_t >

static void xtd::io::file::append_all_lines ( const xtd::ustring &  path, const std::initializer_list< type_t > &  contents  )

inlinestatic

Appends lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.

Parameters

path	The file to write to.
contents	The lines to append to the file.

Returns

true if the text appended; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

Remarks

If the target file already exists, it is overwritten.

append_all_lines() [2/2]

template<typename type_t >

static void xtd::io::file::append_all_lines ( const xtd::ustring &  path, type_t  contents  )

inlinestatic

Appends lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.

Parameters

path	The file to write to.
contents	The lines to append to the file.

Returns

true if the text appended; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

Remarks

If the target file already exists, it is overwritten.

append_all_text()

template<typename type_t >

static void xtd::io::file::append_all_text ( const xtd::ustring &  path, type_t  text  )

inlinestatic

Appends text to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.

Parameters

path	The file to write to.
contents	The text to append to the file.

Returns

true if the text appended; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

append_text()

static std::ofstream xtd::io::file::append_text ( const xtd::ustring &  path )

static

Creates a std::ofstream that appends text to an existing file.

Parameters

path	The path to the file to append to.

Returns

A std::ofstream that appends text to an existing file.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

copy() [1/2]

static void xtd::io::file::copy ( const xtd::ustring &  src, const xtd::ustring &  dest  )

static

Copies an existing file to a new file. Overwriting a file of the same name is not allowed.

Parameters

src	The file to be opened for reading.
dest	The name of the destination file. This cannot be a directory or an existing file.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::file_not_found_exception	if file src does not exists.
xtd::io::io_exception	the handle of the specified file cannot be opened.

copy() [2/2]

static void xtd::io::file::copy ( const xtd::ustring &  src, const xtd::ustring &  dest, bool  overwrite  )

static

Copies an existing file to a new file. Overwriting a file of the same name is allowed.

Parameters

src	The file to be opened for reading.
dest	The name of the destination file. This cannot be a directory.
overwrite	true if the destination file can be overwritten; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path -or- file dest exists.
xtd::io::io_exception	the handle of the specified file cannot be opened.

create()

static std::ofstream xtd::io::file::create ( const xtd::ustring &  path )

static

Creates or overwrites a file in the specified path.

Parameters

The	path and name of the file to create.

Returns

A std::ofstream that provides read/write access to the file specified in path.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path -or- file dest exists.
xtd::io::io_exception	the handle of the specified file cannot be created.

create_text()

static std::ofstream xtd::io::file::create_text ( const xtd::ustring &  path )

static

Creates or opens a file for writing text.

Creates or overwrites a file in the specified path.

Parameters

The	path and name of the file to create.

Returns

A std::ofstream that provides read/write access to the file specified in path.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path -or- file dest exists.
xtd::io::io_exception	the handle of the specified file cannot be created.

exists()

static bool xtd::io::file::exists ( const xtd::ustring &  path )

staticnoexcept

Determines whether the specified file exists.

Parameters

path	The file to check.

Returns

true if the caller has the required permissions and path contains the name of an existing file; 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.

get_attributes()

static xtd::io::file_attributes xtd::io::file::get_attributes ( const xtd::ustring &  src )

static

Gets the xtd::io::file_attributes of the file on the path.

Parameters

src	The path to the file.

Returns

The xtd::io::file_attributes of the file on the path.

Exceptions

xtd::io::file_not_found_exception

if file src does not exists.

move()

static void xtd::io::file::move ( const xtd::ustring &  src, const xtd::ustring &  dest  )

static

Moves a specified file to a new location, providing the option to specify a new file name.

Parameters

src	The name of the file to move.
dest	The new path for the file.

Returns

true if the file moved; otherwise, false.

Exceptions

xtd::argument_exception	if dest already exist.
xtd::io::io_exception	if path is empty or an invalid path.
xtd::io::io_exception	if the caller has not the required permissions.

open()

static std::fstream xtd::io::file::open ( const xtd::ustring &  path, std::ios::openmode  mode  )

static

Opens a FileStream on the specified path.

Parameters

path	The file to open.
mode	A std::ios::openmode value that specifies whether a file is created if one does not exist, and determines whether the contents of existing files are retained or overwritten.

Returns

A std::fstream on the specified path.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

open_read()

static std::ifstream xtd::io::file::open_read ( const xtd::ustring &  path )

static

Opens an existing file for reading.

Parameters

path	The file to be opened for reading.

Returns

A std::ifstream on the specified path.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

open_text()

static std::ifstream xtd::io::file::open_text ( const xtd::ustring &  path )

static

Opens an existing file for reading.

Parameters

path	The file to be opened for reading.

Returns

A std::ifstream on the specified path.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

open_write()

static std::ofstream xtd::io::file::open_write ( const xtd::ustring &  path )

static

Opens an existing file for writing.

Parameters

path	The file to be opened for writing.

Returns

A std::ofstream on the specified path.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

read_all_bytes() [1/2]

template<typename char_t >

static std::vector< uint8_t > xtd::io::file::read_all_bytes ( const char_t *  path )

inlinestatic

Opens a binary file, reads the contents of the file into a byte array, and then closes the file.

Parameters

path	The file to open for reading.

Returns

A byte array containing the contents of the file.

Exceptions

xtd::io::file_not_found_exception	if path does not exists.
xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

read_all_bytes() [2/2]

static std::vector< uint8_t > xtd::io::file::read_all_bytes ( const xtd::ustring &  path )

static

Opens a binary file, reads the contents of the file into a byte array, and then closes the file.

Parameters

path	The file to open for reading.

Returns

A byte array containing the contents of the file.

Exceptions

xtd::io::file_not_found_exception	if path does not exists.
xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

read_all_lines()

static std::vector< xtd::ustring > xtd::io::file::read_all_lines ( const xtd::ustring &  path )

static

Opens a text file, reads all lines of the file, and then closes the file.

Parameters

path	The file to open for reading.

Returns

A String array containing all lines of the file.

Remarks

This method also returns an empty array 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 an empty array regardless of the existence of path.

read_all_text()

static xtd::ustring xtd::io::file::read_all_text ( const xtd::ustring &  path )

static

Opens a text file, reads all text of the file, and then closes the file.

Parameters

path	The file to open for reading.

Returns

A string containing all text of the file.

Remarks

This method also returns empty string 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 empty string regardless of the existence of file.

remove()

static void xtd::io::file::remove ( const xtd::ustring &  path )

static

Deletes the specified file.

Parameters

path	The name of the file to be deleted.

Returns

std::ofstream An unshared std::ofstream that provides access to the specified file, with the specified mode and access.

true if the file is deleted; otherwise, false.

replace()

static void xtd::io::file::replace ( const xtd::ustring &  source_file_name, const xtd::ustring &  destination_file_name, const xtd::ustring &  destination_backup_file_name  )

static

Replaces the contents of a specified file with the contents of another file, deleting the original file, and creating a backup of the replaced file and optionally ignores merge errors.

Parameters

source_file_name	The name of a file that replaces the file specified by destination_file_name.
destination_file_name	The name of the file being replaced.
destination_backup_file_name	The name of the backup file.
ignore_metadata_errors	true to ignore merge errors (such as attributes and access control lists (ACLs)) from the replaced file to the replacement file; otherwise, false.

Returns

false source_file_name does not exist or bad format, or destination_file_name does not exist or bad format, or if ignore_metadata_errors equal false and destination_backup_file_name bad format or on ani io error; otherwise true.

write_all_lines() [1/2]

template<typename type_t >

static void xtd::io::file::write_all_lines ( const xtd::ustring &  path, const std::initializer_list< type_t > &  contents  )

inlinestatic

Writes lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.

Parameters

path	The file to write to.
contents	The lines to write to the file.

Returns

true if the text written; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

Remarks

If the target file already exists, it is overwritten.

write_all_lines() [2/2]

template<typename type_t >

static void xtd::io::file::write_all_lines ( const xtd::ustring &  path, type_t  contents  )

inlinestatic

Writes lines to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.

Parameters

path	The file to write to.
contents	The lines to write to the file.

Returns

true if the text written; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

Remarks

If the target file already exists, it is overwritten.

write_all_text()

template<typename type_t >

static void xtd::io::file::write_all_text ( const xtd::ustring &  path, type_t  text  )

inlinestatic

Writes text to a file, and then closes the file. If the specified file does not exist, this method creates a file, writes the specified lines to the file, and then closes the file.

Parameters

path	The file to write to.
contents	The text to write to the file.

Returns

true if the text written; otherwise, false.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

write_text()

static std::ofstream xtd::io::file::write_text ( const xtd::ustring &  path )

static

Creates a std::ofstream that appends text to an existing file.

Parameters

path	The path to the file to write to.

Returns

A std::ofstream that writes text to an existing file.

Exceptions

xtd::argument_exception	path contains one or more of the invalid characters -or- The system could not retrieve the absolute path.
xtd::io::io_exception	the handle of the specified file cannot be opened.

---

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

• xtd.core/include/xtd/io/file.h