hxfile Class Reference

#include <hxfile.hpp>

Public Types
enum	open_mode : uint8_t { open_mode_none = 0u , open_mode_in = 1u , open_mode_out = 2u , open_mode_asserts = 4u }

Public Member Functions
	hxfile (void)
	hxfile (uint8_t mode_, const char *filename_,...)
	hxfile (uint8_t mode_, intptr_t file_)
	hxfile (const char *file_, uint8_t mode_=0)=delete
	hxfile (hxfile &&file_) noexcept
	~hxfile ()
void	operator= (hxfile &&file_) noexcept
	operator bool (void) const
bool	open (uint8_t mode_, const char *filename_,...)
void	close (void)
bool	is_open (void) const
bool	fail (void) const
void	set_fail (void)
bool	eof (void) const
void	clear (void)
uint8_t	mode (void) const
size_t	get_pos (void) const
bool	set_pos (size_t position_)
size_t	read (void *bytes_, size_t buffer_size_, size_t count_)
size_t	write (const void *bytes_, size_t count_)
bool	flush (void)
template<size_t buffer_size_>
bool	getline (char(&buffer_)[buffer_size_])
bool	getline (char *buffer_, int buffer_size_)
bool	print (const char *format_,...)
int	scan (const char *format_,...)
template<typename T>
bool	read1 (T &t_)
template<typename T>
bool	write1 (const T &t_)
template<typename T>
hxfile &	operator>> (T &t_)
template<typename T>
hxfile &	operator<< (const T &t_)
template<size_t string_length_>
hxfile &	operator<< (const char(&str_)[string_length_])

Detailed Description

hxfile - Single-ownership C++ RAII abstraction for file I/O.

Provides a mixture of unformatted binary stream operations and formatted printf/scanf style I/O, along with optional error handling. gcc is useful for validating printf/scanf style arguments. However, memory-imaged data structures are still recommended. hxfile uses binary I/O only for portability. It implements the equivalent of the standard eofbit and failbit but not the badbit. The failbit should always be set when the eofbit is set.

Here is the syntax to make a block of code conditional on opening a file. The filename is also formatted printf style. This is equivalent to Python's with open(filename, mode) as f:.

if(hxfile f=hxfile(hxfile::open_mode_in, "pkg%d.bin", i)) {
  f >> manifest; // binary read.
  // ...
}

To switch to a different implementation, use an alternate .cpp file for your target. Allows hxerr to be a serial port while file I/O uses a DMA controller.

WARNING: get_position/set_position over 4 GiB is not supported on Windows. As well, size_t is limited to 4 GiB on all 32-bit platforms.

Member Enumeration Documentation

open_mode

enum hxfile::open_mode : uint8_t

open_mode - Flags indicating how the file is to be used.

Modifying or appending to an existing file is not implemented.

Enumerator
open_mode_none	No flags.
open_mode_in	Open for binary reading. e.g., "rb".
open_mode_out	Open for binary writing. Replaces any existing file with an empty one even if open_mode_in is used at the same time. e.g., "wb".
open_mode_asserts	By default, any unexpected failure is reported only through the failure flag. To assert on reasonably unforeseen failures, set open_mode_asserts. Bad parameters (e.g., providing a null buffer) will still result in assertions regardless of this flag.

Constructor & Destructor Documentation

hxfile() [1/5]

hxfile::hxfile

(

void

)

Default-constructs as a closed file.

hxfile() [2/5]

hxfile::hxfile	(	uint8_t	mode_,
		const char *	filename_,
			... )

Constructs and opens a file with a formatted filename.

Uses a non-standard argument order.

• mode : Combination of open_mode flags describing how to open the file.
• filename : Non-null printf-style format string naming the file.
• ... : Additional arguments matching the filename format specifiers.

hxfile() [3/5]

hxfile::hxfile	(	uint8_t	mode_,
		intptr_t	file_ )

Constructs the file object with an unowned implementation-specific handle and a specific mode.

Performs no checks. Use hxin, hxout, hxerr, and hxdev_null instead.

• mode : Combination of open_mode flags describing the handle.
• file : Implementation-specific handle.

hxfile() [4/5]

hxfile::hxfile ( const char * file_, uint8_t mode_ = 0 )

delete

Disallow usage where the filename comes first, like with fopen.

This is done because hxfile::hxfile() uses variadic arguments.

hxfile() [5/5]

hxfile::hxfile ( hxfile && file_ )

noexcept

Move constructor. No copy constructor is provided.

~hxfile()

hxfile::~hxfile

(

)

Destroys the file and ensures it is closed when the object goes out of scope.

Member Function Documentation

clear()

void hxfile::clear

(

void

)

Resets the failure and EOF flags.

This is required to clear EOF after EOF is encountered.

close()

void hxfile::close

(

void

)

Closes the currently open file.

eof()

bool hxfile::eof ( void ) const

inline

Checks if EOF has been reached.

fail()

bool hxfile::fail ( void ) const

inline

Checks if an error has been encountered, EOF set or set_fail called.

flush()

bool hxfile::flush

(

void

)

Flushes buffered output to the underlying file.

Safe to call on hxdev_null. Does not reset the failure flag to false on success.

get_pos()

size_t hxfile::get_pos

(

void

)

const

Returns the current position in the file if open, 0 otherwise.

FILE* implementation requires a 64-bit long to support 64-bit files.

getline() [1/2]

bool hxfile::getline	(	char *	buffer_,
		int	buffer_size_ )

Reads a \n or EOF terminated character sequence.

Allowed to fail on EOF without needing hxfile::open_mode_asserts to be unset. Encountering EOF also sets the failure flag. NOTE: Not available in the POSIX version.

• buffer : Non-null pointer to a char array where the line will be stored.
• buffer_size : Size of the buffer array.

getline() [2/2]

template<size_t buffer_size_>

bool hxfile::getline ( char(&) buffer_[buffer_size_] )

inline

Reads a \n or EOF terminated character sequence.

Allowed to fail on EOF without needing hxfile::open_mode_asserts to be unset. Encountering EOF also sets the failure flag. Automatically determines the size of the provided char array. NOTE: Not available in the POSIX version.

• buffer : Reference to a char array where the line will be stored.

is_open()

bool hxfile::is_open

(

void

)

const

Checks if the file is open.

mode()

uint8_t hxfile::mode ( void ) const

inline

Returns the current open mode of the file.

open()

bool hxfile::open	(	uint8_t	mode_,
		const char *	filename_,
			... )

Opens a file with the specified mode and formatted filename.

• mode : Combination of open_mode flags describing how to open the file.
• filename : Non-null printf-style format string naming the file.
• ... : Additional arguments matching the filename format specifiers.

operator bool()

hxfile::operator bool

(

void

)

const

Checks if the file is open, EOF has not been reached, and no error has been encountered.

See usage example in the class documentation.

operator<<() [1/2]

template<size_t string_length_>

hxfile & hxfile::operator<< ( const char(&) str_[string_length_] )

inline

Writes a string literal to the file.

Supports Google Test style diagnostic messages in hxtest.

• str : Reference to a string literal to write to the file.

operator<<() [2/2]

template<typename T>

hxfile & hxfile::operator<< ( const T & t_ )

inline

Writes a single unformatted native-endian object to a stream.

• t : Reference to the object containing the data to write.

operator=()

void hxfile::operator= ( hxfile && file_ )

noexcept

Move assignment. No copy assignment operator is provided.

operator>>()

template<typename T>

hxfile & hxfile::operator>> ( T & t_ )

inline

Reads a single unformatted native-endian object from a stream.

• t : Reference to the object where the data will be stored.

print()

bool hxfile::print	(	const char *	format_,
			... )

Writes a formatted UTF-8 string to the file.

Uses printf conventions. Formatting and writing will be skipped when using hxdev_null. Does not modify the failure flag because it is not clear from vfprintf.

• format : Non-null printf-style format string.
• ... : Additional arguments that satisfy the format string.

read()

size_t hxfile::read	(	void *	bytes_,
		size_t	buffer_size_,
		size_t	count_ )

Reads a specified number of bytes from the file into the provided buffer.

Does not reset the failure flag to false on success.

• bytes : Non-null pointer to a buffer of at least buffer_size bytes.
• buffer_size : Capacity of the buffer in bytes.
• count : Number of bytes to read from the file. Must not exceed buffer_size.

read1()

template<typename T>

bool hxfile::read1 ( T & t_ )

inline

Reads a single unformatted native-endian object from the file.

• t : Reference to the object where the data will be stored.

scan()

int hxfile::scan	(	const char *	format_,
			... )

Reads a formatted UTF-8 string from the file.

Uses scanf conventions. Returns the same value as scanf. Omit hxfile::open_mode_asserts to read until EOF. Parse errors will set fail to true. Will set the failure flag and check EOF on a return value of EOF from vfscanf. Returns a negative value on EOF.

• format : Non-null scanf-style format string.
• ... : Additional arguments that satisfy the format string.

set_fail()

void hxfile::set_fail ( void )

inline

Marks the file as having encountered a failure.

Allows the user to report additional errors without having to track them. Non-standard.

set_pos()

bool hxfile::set_pos

(

size_t

position_

)

Sets the current position in the file.

Returns true on success. FILE* implementation requires a 64-bit long to support 64-bit files. Resets the failure flag to false on success.

write()

size_t hxfile::write	(	const void *	bytes_,
		size_t	count_ )

Writes a specified number of bytes from the provided buffer to the file.

Writing will be skipped when using hxdev_null. Resets the failure flag to false on success.

• bytes : Non-null pointer to a buffer that provides at least count bytes.
• count : Number of bytes to write to the file.

write1()

template<typename T>

bool hxfile::write1 ( const T & t_ )

inline

Writes a single unformatted native-endian object to the file.

• t : Reference to the object containing the data to write.

---

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

• include/hx/hxfile.hpp