tt::file Class Reference

#include <ttauri/file.hpp>

Public Member Functions
	file (URL const &location, access_mode accessMode)
	Open a file at location.
	file (file const &other)=delete
	file (file &&other)=delete
file &	operator= (file const &other)=delete
file &	operator= (file &&other)=delete
void	close ()
	Close the file.
void	flush ()
	Flush and block until all data is physically written to disk.
void	rename (URL const &destination, bool overwrite_existing=true)
	Rename an open file.
size_t	size () const
	Return the size of the file.
ssize_t	seek (ssize_t offset, seek_whence whence=seek_whence::begin)
	Set the seek location.
ssize_t	get_seek ()
	Get the current seek location.
ssize_t	write (std::byte const *data, ssize_t size, ssize_t offset=-1)
	Write data to a file.
ssize_t	write (void const *data, ssize_t size, ssize_t offset=-1)
	Write data to a file.
ssize_t	write (char const *data, ssize_t size, ssize_t offset=-1)
	Write data to a file.
ssize_t	write (std::span< std::byte const > bytes, ssize_t offset=-1)
	Write data to a file.
ssize_t	write (bstring_view text, ssize_t offset=-1)
	Write data to a file.
ssize_t	write (bstring const &text, ssize_t offset=-1)
	Write data to a file.
ssize_t	write (std::string_view text)
	Write data to a file.
ssize_t	read (std::byte *data, ssize_t size, ssize_t offset=-1)
	Read data from a file.
ssize_t	read (void *data, ssize_t size, ssize_t offset=-1)
bstring	read_bstring (ssize_t size=10 '000 '000, ssize_t offset=-1)
	Read bytes from the file.
std::string	read_string (ssize_t max_size=10 '000 '000)
	Read the whole file as a UTF-8 string.
std::u8string	read_u8string (ssize_t max_size=10 '000 '000)
	Read the whole file as a UTF-8 string.

Static Public Member Functions
static size_t	file_size (URL const &url)
	Get the size of a file on the file system.
static void	create_directory (URL const &url, bool hierarchy=false)
static void	create_directory_hierarchy (URL const &url)

Friends
class	file_mapping
class	file_view

Detailed Description

A File object.

Constructor & Destructor Documentation

file()

tt::file::file	(	URL const &	location,
		access_mode	accessMode )

Open a file at location.

Parameters

location	The file: URL locating the file.
accessMode	access-mode to open the file.

Member Function Documentation

close()

void tt::file::close

(

)

Close the file.

file_size()

static size_t tt::file::file_size ( URL const & url )

static

Get the size of a file on the file system.

Returns

The size of the file in bytes.

flush()

void tt::file::flush

(

)

Flush and block until all data is physically written to disk.

Flushing is required before renaming a file, to prevent data corruption when the computer crashes during the rename.

get_seek()

ssize_t tt::file::get_seek ( )

inline

Get the current seek location.

read()

ssize_t tt::file::read	(	std::byte *	data,
		ssize_t	size,
		ssize_t	offset = -1 )

Read data from a file.

Parameters

data	Pointer to a buffer to read into.
size	The number of bytes to read.
offset	The offset in the file to read, or -1 when reading from the current seek location.

Returns

The number of bytes read.

Exceptions

io_error

read_bstring()

bstring tt::file::read_bstring	(	ssize_t	size = 10 '000 '000,
		ssize_t	offset = -1 )

Read bytes from the file.

Parameters

size	The maximum number of bytes to read.
offset	The offset into the file to read, or -1 when reading from the current seek location.

Returns

Data as a byte string, may return less then the requested size.

Exceptions

io_error

On IO error.

read_string()

std::string tt::file::read_string

(

ssize_t

max_size = 10 '000 '000

)

Read the whole file as a UTF-8 string.

This will ignore the value from seek(), and read the whole file due to UTF-8 character sequences to be complete.

If there is more data in the file than the maximum amount to read this function throws an io_error.

Parameters

max_size

The maximum size to read.

Returns

Data as a UTF-8 string.

Exceptions

io_error	On IO error.
parse_error	On invalid UTF-8 string.

read_u8string()

std::u8string tt::file::read_u8string

(

ssize_t

max_size = 10 '000 '000

)

Read the whole file as a UTF-8 string.

This will ignore the value from seek(), and read the whole file due to UTF-8 character sequences to be complete.

If there is more data in the file than the maximum amount to read this function throws an io_error.

Parameters

max_size

The maximum size to read.

Returns

Data as a UTF-8 string.

Exceptions

io_error	On IO error
parse_error	On invalid UTF-8 string.

rename()

void tt::file::rename	(	URL const &	destination,
		bool	overwrite_existing = true )

Rename an open file.

This function will rename an open file atomically.

Parameters

destination	The destination file name.
overwrite_existing	Overwrite an existing file.

Exceptions

io_error

When failing to rename.

seek()

ssize_t tt::file::seek	(	ssize_t	offset,
		seek_whence	whence = seek_whence::begin )

Set the seek location.

Parameters

offset	To move the file pointer.
whence	Where to seek from: begin, current or end

Returns

The new seek position relative to the beginning of the file.

size()

size_t tt::file::size

(

)

const

Return the size of the file.

write() [1/7]

ssize_t tt::file::write ( bstring const & text, ssize_t offset = -1 )

inline

Write data to a file.

Parameters

text	The byte string to write
offset	The offset in the file to write, or -1 when writing in the current seek location.

Returns

The number of bytes written.

Exceptions

io_error

write() [2/7]

ssize_t tt::file::write ( bstring_view text, ssize_t offset = -1 )

inline

Write data to a file.

Parameters

text	The byte string to write
offset	The offset in the file to write, or -1 when writing in the current seek location.

Returns

The number of bytes written.

Exceptions

io_error

write() [3/7]

ssize_t tt::file::write ( char const * data, ssize_t size, ssize_t offset = -1 )

inline

Write data to a file.

Parameters

data	Pointer to data to be written.
size	The number of bytes to write.
offset	The offset in the file to write, or -1 when writing in the current seek location.

Returns

The number of bytes written.

Exceptions

io_error

write() [4/7]

ssize_t tt::file::write	(	std::byte const *	data,
		ssize_t	size,
		ssize_t	offset = -1 )

Write data to a file.

Parameters

data	Pointer to data to be written.
size	The number of bytes to write.
offset	The offset in the file to write, or -1 when writing in the current seek location.

Returns

The number of bytes written.

Exceptions

io_error

write() [5/7]

ssize_t tt::file::write ( std::span< std::byte const > bytes, ssize_t offset = -1 )

inline

Write data to a file.

Parameters

bytes	The byte string to write
offset	The offset in the file to write, or -1 when writing in the current seek location.

Returns

The number of bytes written.

Exceptions

io_error

write() [6/7]

ssize_t tt::file::write ( std::string_view text )

inline

Write data to a file.

Parameters

text	The UTF-8 string to write

Returns

The number of bytes written.

Exceptions

io_error

write() [7/7]

ssize_t tt::file::write ( void const * data, ssize_t size, ssize_t offset = -1 )

inline

Write data to a file.

Parameters

data	Pointer to data to be written.
size	The number of bytes to write.
offset	The offset in the file to write, or -1 when writing in the current seek location.

Returns

The number of bytes written.

Exceptions

io_error

---

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

• hikogui/src/ttauri/file.hpp