File based I/O methods including whole file and partial files. More...

#include <file.h>

Classes
class	file_read_only
	A read_only file object, the memory was probably allocated with mmap() and needs deallocating accordingly. More...

Public Member Functions
	file ()=delete
	Constructor.

	file (FILE *fp)
	Constructor with a C FILE * object. More...

	file (const char filename, const char mode)
	Constructor used for opening files. More...

	file (const std::string &filename, const std::string &mode)
	Constructor used for opening files. More...

	~file ()
	Destructor.

size_t	setvbuf (size_t size)
	change the size of the internal buffer (does not flush() first) More...

void	flush (void)
	Flush the internal buffers to disk (called automatically on close).

size_t	read (void *data, size_t size)
	Read bytes number of bytes from the give file into the buffer. More...

void	read (std::vector< uint8_t > &buffer)
	Read buffer.size() bytes from the give file into the buffer. If at end of file then this method will resize buffer to the number of bytes read from the file. More...

size_t	write (const void *data, size_t size)
	Write bytes number of bytes to the give file at the current cursor position. More...

size_t	write (const std::string &buffer)
	Write bytes number of bytes to the give file at the current cursor position. More...

size_t	size (void) const
	Return the length of the file as it currently stands. More...

size_t	tell (void)
	Return the byte offset of the file pointer in the current file. More...

void	seek (size_t offset)
	Seek to the given offset in the file. More...

Static Public Member Functions
static size_t	read_entire_file (const std::string &filename, std::string &into)
	Read the contents of file filename into the std::string into. More...

static size_t	read_entire_file (const std::string &filename, file_read_only &into)
	Read the contents of file filename into the std::string into. More...

static bool	write_entire_file (const std::string &filename, const std::string &buffer)
	Write the contents of buffer to the file specified in filenane. More...

static void	buffer_to_list (std::vector< uint8_t *> &line_list, std::string &buffer)
	Turn a single std::string into a vector of uint8_t * (i.e. "C" strings). More...

static bool	is_directory (const std::string &filename)
	Determines whether the given file system object is a directoy or not. More...

static std::string	mkstemp (std::string prefix)
	Generate a temporary filename containing the given prefix. More...

static void	unittest (void)
	Unit test this class.

Protected Attributes
FILE *	fp
	The underlying representation is a FILE * from C (as they appear to be fast).

size_t	file_position
	The ftell() position in the file.

size_t	buffer_size
	Size of the internal file buffering.

size_t	buffer_used
	How much of the internal file buffer is being used.

std::unique_ptr< uint8_t []>	buffer
	Internal file buffer.

size_t	bytes_written
	Number of bytes written to this file.

size_t	bytes_read
	Number of bytes read from this file.

Detailed Description

File based I/O methods including whole file and partial files.

This class exists in order to abstract file I/O which has, in the past, been different on different platforms. For example, 64-bit file I/O under Windows (using Win32) is awkward because the Win32 functions do not take 64-bit parameters.

This file class is based on Resource Allocation Is Initialisation (RAII). That is, the file is opened when the object is constructed and closed when the object is destroyed.

Constructor & Destructor Documentation

◆ file() [1/3]

JASS::file::file ( FILE * fp )

inline

Constructor with a C FILE * object.

Parameters

fp	[in] The FILE * object this object should use. This class takes ownership and closes the file on destruction.

◆ file() [2/3]

JASS::file::file	(	const char *	filename,
		const char *	mode
	)

inline

Constructor used for opening files.

Parameters

filename	[in] the name of the file.
mode	[in] The file open mode. See C's fopen() for details on possible modes.

◆ file() [3/3]

JASS::file::file	(	const std::string &	filename,
		const std::string &	mode
	)

inline

Constructor used for opening files.

Parameters

filename	[in] the name of the file.
mode	[in] The file open mode. See C's fopen() for details on possible modes.

Member Function Documentation

◆ buffer_to_list()

void JASS::file::buffer_to_list	(	std::vector< uint8_t *> &	line_list,
		std::string &	buffer
	)

static

Turn a single std::string into a vector of uint8_t * (i.e. "C" strings).

Note that these pointers are in-place. That is, they point into buffer so any change to the uint8_t or to buffer effect each other. This method removes blank lines from buffer and changes buffer by inserting '\0' characters at the end of each line.

Parameters

line_list	[out] The vector to write into
buffer	[in, out] the string to decompose

◆ is_directory()

bool JASS::file::is_directory ( const std::string & filename )

static

Determines whether the given file system object is a directoy or not.

Parameters

filename [in] The path to the file system object to check.

Returns: True if the given path is a directory, false if it is not (or does not exist).

◆ mkstemp()

std::string JASS::file::mkstemp ( std::string prefix )

static

Generate a temporary filename containing the given prefix.

This method is a wrapper for mkstemp on Linux / MacOS and _mktemp on windows. These methods are renounds for having the problem that the filename may not be unique once it has been generated and therefore opening a file with this name may fail. However, there are times when this doesn't matter (such as unit tests).

Parameters

prefix [in] The prefix to the unique filenane,

Returns: A unique filename at the time the method is called.

◆ read() [1/2]

size_t JASS::file::read	(	void *	data,
		size_t	size
	)

inline

Read bytes number of bytes from the give file into the buffer.

Parameters

data	[out] Buffer large enough to hold bytes number of bytes of data which are written into the memory pointed to by buffer.
size	[in] The number of bytes of data to read.

Returns: The number of bytes of data that were read and written into buffer.

◆ read() [2/2]

void JASS::file::read ( std::vector< uint8_t > & buffer )

inline

Read buffer.size() bytes from the give file into the buffer. If at end of file then this method will resize buffer to the number of bytes read from the file.

Parameters

buffer [in, out] Read buffer.size() bytes into buffer, calling buffer.resize() on failure.

◆ read_entire_file() [1/2]

size_t JASS::file::read_entire_file	(	const std::string &	filename,
		std::string &	into
	)

static

Read the contents of file filename into the std::string into.

Because into is a string it is naturally '\0' terminated by the C++ std::string class.

Parameters

filename	[in] The path of the file to read.
into	[out] The std::string to write into. This string will be re-sized to the size of the file.

Returns: The size of the file in bytes

◆ read_entire_file() [2/2]

static size_t JASS::file::read_entire_file	(	const std::string &	filename,
		file_read_only &	into
	)

inlinestatic

Read the contents of file filename into the std::string into.

Because into is a string it is naturally '\0' terminated by the C++ std::string class.

Parameters

filename	[in] The path of the file to read.
into	[out] The std::string to write into. This string will be re-sized to the size of the file.

Returns: The size of the file in bytes

◆ seek()

void JASS::file::seek ( size_t offset )

inline

Seek to the given offset in the file.

Throws std::out_of_range in the unlikely event of an error.

Parameters

offset [in] The location to seek to.

◆ setvbuf()

size_t JASS::file::setvbuf ( size_t size )

inline

change the size of the internal buffer (does not flush() first)

The C standard states "This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it", and this is true of this function too.

Parameters

size	[in] The new size of the buffer.

Returns: 1 on success, 0 on failure.

◆ size()

size_t JASS::file::size ( void ) const

Return the length of the file as it currently stands.

Returns: File size in bytes. 0 is returned either on error or non-existant file (or 0-length file).

◆ tell()

size_t JASS::file::tell ( void )

inline

Return the byte offset of the file pointer in the current file.

Returns: byte offset. 0 is returned either on error or non-existant file (or actually at 0).

◆ write() [1/2]

size_t JASS::file::write	(	const void *	data,
		size_t	size
	)

inline

Write bytes number of bytes to the give file at the current cursor position.

Parameters

data	[in] the byte sequence to write.
size	[in] The number of bytes of data to write.

Returns: The number of bytes of data that were written to the file.

◆ write() [2/2]

size_t JASS::file::write ( const std::string & buffer )

inline

Write bytes number of bytes to the give file at the current cursor position.

Parameters

buffer [in] the byte sequence to write.

Returns: The number of bytes of data that were written to the file.

◆ write_entire_file()

bool JASS::file::write_entire_file	(	const std::string &	filename,
		const std::string &	buffer
	)

static

Write the contents of buffer to the file specified in filenane.

If the file does not exist it is created. If it does already exist it is overwritten.

Parameters

filename	[in] The path of the file to write to.
buffer	[in] The data to write to the file.

Returns: True if successful, false if unsuccessful

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

source/file.h
source/file.cpp

Classes

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ file() [1/3]

◆ file() [2/3]

◆ file() [3/3]

Member Function Documentation

◆ buffer_to_list()

◆ is_directory()

◆ mkstemp()

◆ read() [1/2]

◆ read() [2/2]

◆ read_entire_file() [1/2]

◆ read_entire_file() [2/2]

◆ seek()

◆ setvbuf()

◆ size()

◆ tell()

◆ write() [1/2]

◆ write() [2/2]

◆ write_entire_file()