Binary::StandardFileStream Class Reference

Provides a standard file stream for manipulating binary files. More...

#include <StandardFileStream.h>

Inheritance diagram for Binary::StandardFileStream:

Public Member Functions
	StandardFileStream (std::string filePath)
	Constructor; creates a new instance of StandardFileStream.
virtual std::string	FileName () const override
	Gets the name of the file.
virtual std::string	FilePath () const override
	Gets the full path to the file on disk.
virtual bool	IsOpen () const override
	Determines whether or not the file is open.
virtual bool	FileExists () const override
	Determines whether or not the file exists on disk.
virtual size_t	FileSize () const override
	Gets the size of the file associated with the stream.
virtual FileMode	Mode () const override
	Determines the mode the file is set to open in.
virtual void	Open (FileMode mode) override
	Opens the file in the specified mode.
virtual void	Close () override
	Closes the file.
virtual void	Read (DataField *field) const override
	Reads data from the stream into the specified field.
virtual void	Read (DataStructure *structure) const override
	Reads data from stream into the specified data structure.
virtual std::shared_ptr< ChunkHeader >	FindNextChunk (std::string id) const override
	Finds the next chunk header with the specified ID.
virtual void	Write (const DataField *field) override
	Writes data to the stream from the specified field.
virtual void	Write (const DataStructure *structure) override
	Writes the specified structure to the stream.
virtual size_t	Position () const override
	Gets the current position in the stream.
virtual void	SetPosition (size_t position) const override
	Sets the current position in the stream.
virtual size_t	Beginning () const override
	Gets the beginning position of the file.
virtual size_t	End () const override
	Gets the end position of the file.
Public Member Functions inherited from Binary::Stream
virtual	~Stream ()=default
	Default destructor; properly destroys the instance.

Detailed Description

Provides a standard file stream for manipulating binary files.

This class provides the standard implementation for reading from and writing to binary data files. It accepts pointers to instances of DataField and other types composed of data fields for reading from and writing to the file. This class can be used directly for manipulating binary data in any binary file type, but more specialized file stream classes can inherit from this class to add onto the base functionality.

Invariant

The file path is not empty.

Position must be between 0 and Size, inclusive.

Reading advances the position by field or structure size.

Reading does not modify the file's contents.

Writing advances the position and modifies file contents.

Constructor & Destructor Documentation

StandardFileStream()

Binary::StandardFileStream::StandardFileStream ( std::string filePath )

inline

Constructor; creates a new instance of StandardFileStream.

Parameters

filePath

The path to the file on disk.

Precondition

File path must not be empty.

Member Function Documentation

Beginning()

virtual size_t Binary::StandardFileStream::Beginning ( ) const

inlineoverridevirtual

Gets the beginning position of the file.

Returns

A size_t value representing the beginning position.

Implements Binary::Stream.

Close()

virtual void Binary::StandardFileStream::Close ( )

inlineoverridevirtual

Closes the file.

Postcondition

The stream is closed.

Exceptions

std::runtime_error

or implementation-specific exceptions if the file cannot be closed.

Implements Binary::FileStream.

End()

virtual size_t Binary::StandardFileStream::End ( ) const

inlineoverridevirtual

Gets the end position of the file.

Returns

A size_t value representing the end position.

Implements Binary::Stream.

FileExists()

virtual bool Binary::StandardFileStream::FileExists ( ) const

inlineoverridevirtual

Determines whether or not the file exists on disk.

Returns

True if it exists, otherwise false.

Implements Binary::FileStream.

FileName()

virtual std::string Binary::StandardFileStream::FileName ( ) const

overridevirtual

Gets the name of the file.

Returns

A string representing the name of the file.

Implements Binary::FileStream.

FilePath()

virtual std::string Binary::StandardFileStream::FilePath ( ) const

inlineoverridevirtual

Gets the full path to the file on disk.

Returns

A string representing the full path to the file.

Implements Binary::FileStream.

FileSize()

virtual size_t Binary::StandardFileStream::FileSize ( ) const

overridevirtual

Gets the size of the file associated with the stream.

Returns

The size of the file, in bytes.

Exceptions

std::overflow_error	if file size exceeds size_t limits.
std::filesystem::filesystem_error	if file size cannot be determined.

Implements Binary::FileStream.

FindNextChunk()

virtual std::shared_ptr< ChunkHeader > Binary::StandardFileStream::FindNextChunk ( std::string id ) const

overridevirtual

Finds the next chunk header with the specified ID.

Parameters

id	The ID of the chunk to find.

Returns

A pointer to the chunk header if found, otherwise nullptr.

Precondition

id must be exactly 4 characters long.

Postcondition

Position is advanced to the beginning of found chunk header.

Exceptions

std::invalid_argument

if id is not 4 characters long.

Implements Binary::Stream.

IsOpen()

virtual bool Binary::StandardFileStream::IsOpen ( ) const

inlineoverridevirtual

Determines whether or not the file is open.

Returns

True if it is open, otherwise false.

Implements Binary::FileStream.

Mode()

virtual FileMode Binary::StandardFileStream::Mode ( ) const

inlineoverridevirtual

Determines the mode the file is set to open in.

Returns

The file mode.

Implements Binary::FileStream.

Open()

virtual void Binary::StandardFileStream::Open ( FileMode mode )

overridevirtual

Opens the file in the specified mode.

Parameters

mode	The mode to open the file in.

Precondition

File path is set to a valid path for the implementation.

Postcondition

If successful, the stream is open in the specified mode.

Exceptions

std::runtime_error

or implementation-specific exceptions if the file cannot be opened.

Implements Binary::FileStream.

Position()

virtual size_t Binary::StandardFileStream::Position ( ) const

inlineoverridevirtual

Gets the current position in the stream.

Returns

A size_t representing the position.

Implements Binary::Stream.

Read() [1/2]

virtual void Binary::StandardFileStream::Read ( DataField * field ) const

overridevirtual

Reads data from the stream into the specified field.

Parameters

field

A pointer to the field to read data into.

Precondition

Field must not be null.

Field size must be <= remaining buffer size.

Postcondition

Position is advanced by field size.

Specified field is updated with the data read from the buffer.

Exceptions

std::out_of_range	if field size > remaining buffer size.
std::invalid_argument	if field is null.

Implements Binary::Stream.

Read() [2/2]

virtual void Binary::StandardFileStream::Read ( DataStructure * structure ) const

overridevirtual

Reads data from stream into the specified data structure.

Parameters

structure

A pointer to the data structure to read data into.

Precondition

Structure must not be null.

Structure size must be <= remaining buffer size.

Postcondition

Position is advanced by structure size.

Specified structure is updated with the data read from buffer.

Exceptions

std::out_of_range	if structure size > remaining buffer size.
std::invalid_argument	if structure is null.

Implements Binary::Stream.

SetPosition()

virtual void Binary::StandardFileStream::SetPosition ( size_t position ) const

inlineoverridevirtual

Sets the current position in the stream.

Parameters

position

The position value to set.

Precondition

Position must be between 0 and size, inclusive.

Postcondition

Position is updated to the specified value.

Exceptions

std::out_of_range

if position > size.

Implements Binary::Stream.

Write() [1/2]

virtual void Binary::StandardFileStream::Write ( const DataField * field )

overridevirtual

Writes data to the stream from the specified field.

Parameters

field

A pointer to the field to write to the stream.

Precondition

Field must not be null.

Field size must be <= remaining buffer size.

Postcondition

Position is advanced by field size.

Buffer is updated with the data from the specified field.

Exceptions

std::out_of_range	if field size > remaining buffer size.
std::invalid_argument	if field is null.

Implements Binary::Stream.

Write() [2/2]

virtual void Binary::StandardFileStream::Write ( const DataStructure * structure )

overridevirtual

Writes the specified structure to the stream.

Parameters

structure

A pointer to the structure to write to the stream.

Precondition

Structure must not be null.

Structure size must be <= remaining buffer size.

Postcondition

Position is advanced by structure size.

Buffer is updated with the data from the specified structure.

Exceptions

std::out_of_range	if structure size > remaining buffer size.
std::invalid_argument	if structure is null.

Implements Binary::Stream.

---

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

• include/StandardFileStream.h