Thea
Classes | Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
BinaryInputStream Class Reference

Sequential or random access input from binary files/memory. More...

#include <BinaryInputStream.hpp>

Inheritance diagram for BinaryInputStream:
NamedObject Noncopyable INamedObject

Classes

class  EndiannessScope
 An object that saves the current endianness state of a stream upon construction, and restores the previous state upon destruction, using the RAII idiom. More...
 

Public Member Functions

void beginBits ()
 Prepare for reading individual bits via readBits(). More...
 
 BinaryInputStream (std::string const &path, Endianness file_endian)
 Open a file as a binary input stream. More...
 
 BinaryInputStream (uint8 const *data, int64 data_len, Endianness data_endian, bool copy_memory=true)
 Wrap a block of in-memory data as an input stream. More...
 
 BinaryInputStream (BinaryInputStream &src, int64 block_len)
 Wrap the next block_len bytes of another input stream as a new, temporary input stream with the same endianness. More...
 
void endBits ()
 End bit-reading. More...
 
Endianness getEndianness () const
 Get the current endianness setting for reading multi-byte data. More...
 
char const * getName () const
 Get the name of the object. More...
 
std::string getPath () const
 Get the path to the current file being read ("<memory>" for memory streams). More...
 
int64 getPosition () const
 Get the current byte position in the stream, where 0 is the beginning and size() - 1 is the end. More...
 
bool hasMore () const
 Check if there are more bytes to be read. More...
 
std::string readAlignedString (int alignment=4)
 Read an aligned string. More...
 
uint32 readBits (int num_bits)
 Read a sequence of up to 32 bits. More...
 
bool readBool8 ()
 Read an 8-bit boolean (0 is false, non-zero is true). More...
 
void readBytes (int64 n, void *bytes)
 Read a sequence of n bytes. More...
 
ColorL readColorL ()
 Read a color with 1 floating-point channel. More...
 
ColorL8 readColorL8 ()
 Read a color with 1 8-bit channel. More...
 
ColorRgb readColorRgb ()
 Read a color with 3 floating-point channels. More...
 
ColorRgb8 readColorRgb8 ()
 Read a color with 3 8-bit channels. More...
 
ColorRgba readColorRgba ()
 Read a color with 4 floating-point channels. More...
 
ColorRgba8 readColorRgba8 ()
 Read a color with 4 8-bit channels. More...
 
CoordinateFrame3 readCoordinateFrame3 ()
 Read a coordinate frame. More...
 
float32 readFloat32 ()
 Read a 32-bit floating point number. More...
 
float64 readFloat64 ()
 Read a 64-bit floating point number. More...
 
int16 readInt16 ()
 Read a 16-bit signed integer. More...
 
int32 readInt32 ()
 Read a 32-bit signed integer. More...
 
int64 readInt64 ()
 Read a 64-bit signed integer. More...
 
int8 readInt8 ()
 Read an 8-bit signed integer (a signed byte). More...
 
std::string readLine ()
 Reads until any newline character (\r, \r\n, \n\r, \n) or the end of the file is encountered. More...
 
template<typename MatrixT >
intx readMatrix (bool read_block_header, MatrixT &m, Codec const &codec=CodecAuto())
 Read an arbitrary dense or sparse 2D matrix, using a codec such as CSV or HDF5 (some of which can be autodetected). More...
 
template<typename CandidateMatrixType0 , typename CandidateMatrixType1 , typename... MoreMatrixTypes, typename std::enable_if< !std::is_base_of< Codec, CandidateMatrixType1 >::value, int >::type * = nullptr>
intx readMatrix (bool read_block_header, CandidateMatrixType0 &m0, CandidateMatrixType1 &m1, MoreMatrixTypes &...rest)
 Given a set of candidate matrices of different types, read that one whose format best matches the input data. More...
 
Matrix2 readMatrix2 ()
 Read a 2x2 matrix. More...
 
Matrix3 readMatrix3 ()
 Read a 3x3 matrix. More...
 
Matrix4 readMatrix4 ()
 Read a 4x4 matrix. More...
 
std::string readNullTerminatedString ()
 Read a null-terminated string. More...
 
Plane3 readPlane3 ()
 Read a 3D plane. More...
 
std::string readString ()
 Read a string. More...
 
std::string readString (int64 n)
 Read an n character string. More...
 
uint16 readUInt16 ()
 Read a 16-bit unsigned integer. More...
 
uint32 readUInt32 ()
 Read a 32-bit unsigned integer. More...
 
uint64 readUInt64 ()
 Read a 64-bit unsigned integer. More...
 
uint8 readUInt8 ()
 Read an 8-bit unsigned integer (an unsigned byte). More...
 
Vector2 readVector2 ()
 Read a 2-vector. More...
 
Vector3 readVector3 ()
 Read a 3-vector. More...
 
Vector4 readVector4 ()
 Read a 4-vector. More...
 
void reset ()
 Set the read position at the beginning of the file. More...
 
void setEndianness (Endianness endian)
 Change the endianness for interpreting the file contents. More...
 
int8 setName (char const *s)
 Set the name of the object from a C-style string. More...
 
virtual int8 setName (std::string const &s)
 Set the name of the object from a std::string. More...
 
void setPosition (int64 p)
 Set the current byte position in the stream. More...
 
int64 size () const
 Get the number of bytes in the stream. More...
 
void skip (int64 n)
 Skips ahead n bytes. More...
 
 ~BinaryInputStream ()
 Destructor. More...
 

Static Public Attributes

static bool const NO_COPY = false
 Constant to use with the copy_memory option (evaluates to false). More...
 

Protected Member Functions

std::string const & getNameStr () const
 Access the name string directly, for efficiency. More...
 

Detailed Description

Sequential or random access input from binary files/memory.

For every readX method there are also versions that operate on a whole Array or C-array. The first method resizes the Array to the appropriate size before reading. For a C-array, they require the pointer to reference a memory block large enough to hold n elements.

Derived from the G3D library: http://g3d.sourceforge.net

Todo:
Reimplement using %<iostream%> for arbitrary seeking and safer performance?

Definition at line 59 of file BinaryInputStream.hpp.

Constructor & Destructor Documentation

BinaryInputStream ( std::string const &  path,
Endianness  file_endian 
)

Open a file as a binary input stream.

If the file cannot be opened, an error is thrown.

Definition at line 286 of file BinaryInputStream.cpp.

BinaryInputStream ( uint8 const *  data,
int64  data_len,
Endianness  data_endian,
bool  copy_memory = true 
)

Wrap a block of in-memory data as an input stream.

Unless you specify copy_memory = false, the data is copied from the pointer, so you may deallocate it as soon as the object is constructed. It is an error to specify copy_memory = false.

Definition at line 249 of file BinaryInputStream.cpp.

BinaryInputStream ( BinaryInputStream src,
int64  block_len 
)

Wrap the next block_len bytes of another input stream as a new, temporary input stream with the same endianness.

The source stream must exist as long as this object does, since the implementation does not guarantee that the block will be fully copied to a new buffer. The block is marked as read in the source stream, and the next read position in that stream is set to just after the block.

Definition at line 349 of file BinaryInputStream.cpp.

Destructor.

Definition at line 380 of file BinaryInputStream.cpp.

Member Function Documentation

void beginBits ( )

Prepare for reading individual bits via readBits().

Only readBits() can be called between beginBits() and endBits() without corrupting the data stream.

Definition at line 532 of file BinaryInputStream.cpp.

void endBits ( )

End bit-reading.

Definition at line 577 of file BinaryInputStream.cpp.

Endianness getEndianness ( ) const

Get the current endianness setting for reading multi-byte data.

Definition at line 181 of file BinaryInputStream.hpp.

char const* getName ( ) const
virtualinherited

Get the name of the object.

Implements INamedObject.

Definition at line 78 of file NamedObject.hpp.

std::string const& getNameStr ( ) const
protectedinherited

Access the name string directly, for efficiency.

Definition at line 98 of file NamedObject.hpp.

std::string getPath ( ) const

Get the path to the current file being read ("<memory>" for memory streams).

Definition at line 187 of file BinaryInputStream.hpp.

int64 getPosition ( ) const

Get the current byte position in the stream, where 0 is the beginning and size() - 1 is the end.

Definition at line 205 of file BinaryInputStream.hpp.

bool hasMore ( ) const

Check if there are more bytes to be read.

Returns true if the current read position is not at the end of the file.

Definition at line 199 of file BinaryInputStream.hpp.

std::string readAlignedString ( int  alignment = 4)

Read an aligned string.

The format is:

  • Length of string (32-bit integer)
  • Characters of string ('length' bytes, no null termination)
  • Arbitrary padding bytes to align to alignment bytes boundary
See also
BinaryOutputStream::writeAlignedString()

Definition at line 519 of file BinaryInputStream.cpp.

uint32 readBits ( int  num_bits)

Read a sequence of up to 32 bits.

Can only be called between beginBits() and endBits()

Definition at line 546 of file BinaryInputStream.cpp.

bool readBool8 ( )

Read an 8-bit boolean (0 is false, non-zero is true).

Definition at line 252 of file BinaryInputStream.hpp.

void readBytes ( int64  n,
void *  bytes 
)

Read a sequence of n bytes.

Definition at line 387 of file BinaryInputStream.cpp.

ColorL readColorL ( )

Read a color with 1 floating-point channel.

Definition at line 453 of file BinaryInputStream.hpp.

ColorL8 readColorL8 ( )

Read a color with 1 8-bit channel.

Definition at line 447 of file BinaryInputStream.hpp.

ColorRgb readColorRgb ( )

Read a color with 3 floating-point channels.

Definition at line 469 of file BinaryInputStream.hpp.

ColorRgb8 readColorRgb8 ( )

Read a color with 3 8-bit channels.

Definition at line 459 of file BinaryInputStream.hpp.

ColorRgba readColorRgba ( )

Read a color with 4 floating-point channels.

Definition at line 490 of file BinaryInputStream.hpp.

ColorRgba8 readColorRgba8 ( )

Read a color with 4 8-bit channels.

Definition at line 479 of file BinaryInputStream.hpp.

CoordinateFrame3 readCoordinateFrame3 ( )

Read a coordinate frame.

Definition at line 534 of file BinaryInputStream.hpp.

float32 readFloat32 ( )

Read a 32-bit floating point number.

Definition at line 338 of file BinaryInputStream.hpp.

float64 readFloat64 ( )

Read a 64-bit floating point number.

Definition at line 351 of file BinaryInputStream.hpp.

int16 readInt16 ( )

Read a 16-bit signed integer.

Definition at line 284 of file BinaryInputStream.hpp.

int32 readInt32 ( )

Read a 32-bit signed integer.

Definition at line 321 of file BinaryInputStream.hpp.

int64 readInt64 ( )

Read a 64-bit signed integer.

Definition at line 331 of file BinaryInputStream.hpp.

int8 readInt8 ( )

Read an 8-bit signed integer (a signed byte).

Definition at line 245 of file BinaryInputStream.hpp.

std::string readLine ( )

Reads until any newline character (\r, \r\n, \n\r, \n) or the end of the file is encountered.

Consumes the newline.

Definition at line 485 of file BinaryInputStream.cpp.

intx readMatrix ( bool  read_block_header,
MatrixT &  m,
Codec const &  codec = CodecAuto() 
)

Read an arbitrary dense or sparse 2D matrix, using a codec such as CSV or HDF5 (some of which can be autodetected).

Parameters
read_block_headerIf true, first read a header section which stores the size and codec of the serialized matrix
mThe matrix in which to store the deserialized input.
codecThe codec to use (pass CodecAuto() to autodetect it from the input). data. Else, the matrix block is assumed to continue until the end of the input stream unless its end can be detected through some other means (e.g. end marker or embedded size field), and the codec will be autodetected if possible.
Returns
Always returns 0 (except on error when it throws an exception), for consistency with the other version of this function which chooses between a variable number of matrix types depending on the input.
Note
Unlike most other deserialization functions that optionally read a block header, the read_block_header parameter is the first parameter instead of the last one for consistency with the other version of this function which chooses between a variable number of matrix types depending on the input.

Definition at line 380 of file MatrixIO.hpp.

intx readMatrix ( bool  read_block_header,
CandidateMatrixType0 &  m0,
CandidateMatrixType1 &  m1,
MoreMatrixTypes &...  rest 
)

Given a set of candidate matrices of different types, read that one whose format best matches the input data.

The codec will be auto-detected. The most common use is when either a dense matrix or a sparse matrix must be read, but it is not known ahead of time which is present in the input. Sample use in such a situation could be something like:

MatrixXd dense;
SparseMatrix<double> sparse;
auto which = input.readMatrix(true, dense, sparse);
THEA_CONSOLE << "Read " << (which == 0 ? "dense" : "sparse") << " matrix";
Parameters
read_block_headerIf true, first read a header section which stores the size and codec of the serialized matrix.
m0A matrix of the first candidate type.
m1A matrix of the second candidate type.
restOptional matrices of more candidate types.
Returns
The index of the matrix which was read. The first matrix (of type CandidateMatrixType0) has index 0, the second (of type CandidateMatrixType1) has index 1, and so on.

Definition at line 592 of file BinaryInputStream.hpp.

Matrix2 readMatrix2 ( )

Read a 2x2 matrix.

Definition at line 501 of file BinaryInputStream.hpp.

Matrix3 readMatrix3 ( )

Read a 3x3 matrix.

Definition at line 512 of file BinaryInputStream.hpp.

Matrix4 readMatrix4 ( )

Read a 4x4 matrix.

Definition at line 523 of file BinaryInputStream.hpp.

std::string readNullTerminatedString ( )

Read a null-terminated string.

This is an INHERENTLY UNSAFE method and should be used with GREAT CAUTION!

Definition at line 468 of file BinaryInputStream.cpp.

Plane3 readPlane3 ( )

Read a 3D plane.

Definition at line 542 of file BinaryInputStream.hpp.

std::string readString ( )

Read a string.

The format is:

  • Length of string (32-bit integer)
  • Characters of string ('length' bytes, no null termination)
See also
BinaryOutputStream::writeString()

Definition at line 378 of file BinaryInputStream.hpp.

std::string readString ( int64  n)

Read an n character string.

The string is not required to end in nullptr in the file but will always be a proper std::string when returned.

Definition at line 440 of file BinaryInputStream.cpp.

uint16 readUInt16 ( )

Read a 16-bit unsigned integer.

Definition at line 258 of file BinaryInputStream.hpp.

uint32 readUInt32 ( )

Read a 32-bit unsigned integer.

Definition at line 291 of file BinaryInputStream.hpp.

uint64 readUInt64 ( )

Read a 64-bit unsigned integer.

Definition at line 400 of file BinaryInputStream.cpp.

uint8 readUInt8 ( )

Read an 8-bit unsigned integer (an unsigned byte).

Definition at line 238 of file BinaryInputStream.hpp.

Vector2 readVector2 ( )

Read a 2-vector.

Definition at line 417 of file BinaryInputStream.hpp.

Vector3 readVector3 ( )

Read a 3-vector.

Definition at line 426 of file BinaryInputStream.hpp.

Vector4 readVector4 ( )

Read a 4-vector.

Definition at line 436 of file BinaryInputStream.hpp.

void reset ( )

Set the read position at the beginning of the file.

Definition at line 226 of file BinaryInputStream.hpp.

void setEndianness ( Endianness  endian)

Change the endianness for interpreting the file contents.

This only changes the interpretation of the file for future read calls; the underlying data is unmodified. To temporarily set the endianness within a scope using the RAII idiom, and restore the original setting at the end of the scope, create an EndiannessScope object.

Definition at line 243 of file BinaryInputStream.cpp.

int8 setName ( char const *  s)
virtualinherited

Set the name of the object from a C-style string.

Returns
True if the name was successfully set, else false (e.g. if the name is read-only). In the default implementation, the function always returns true.

Implements INamedObject.

Definition at line 86 of file NamedObject.hpp.

virtual int8 setName ( std::string const &  s)
virtualinherited

Set the name of the object from a std::string.

Returns
True if the name was successfully set, else false (e.g. if the name is read-only). In the default implementation, the function always returns true.

Definition at line 94 of file NamedObject.hpp.

void setPosition ( int64  p)

Set the current byte position in the stream.

May throw an assertion failure when seeking backwards more than 10MB on a huge file.

Definition at line 214 of file BinaryInputStream.hpp.

int64 size ( ) const

Get the number of bytes in the stream.

Definition at line 193 of file BinaryInputStream.hpp.

void skip ( int64  n)

Skips ahead n bytes.

Definition at line 232 of file BinaryInputStream.hpp.

Member Data Documentation

bool const NO_COPY = false
static

Constant to use with the copy_memory option (evaluates to false).

Definition at line 123 of file BinaryInputStream.hpp.


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