Thea
Classes | Public Member Functions | Protected Member Functions | List of all members
BinaryOutputStream Class Reference

Sequential or random access output to binary files/memory. More...

#include <BinaryOutputStream.hpp>

Inheritance diagram for BinaryOutputStream:
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 ()
 Begin writing individual bits. More...
 
 BinaryOutputStream (Endianness endian=Endianness::LITTLE)
 Construct a stream that writes to an (expanding, contiguous) memory buffer. More...
 
 BinaryOutputStream (std::string const &path, Endianness file_endian)
 Construct a stream that writes to a file. More...
 
bool commit (bool flush=true)
 Write the buffered data to disk. More...
 
void commit (uint8 *dst) const
 Copy data in a memory stream to a memory buffer (which must be preallocated to at least size() bytes). More...
 
void endBits ()
 End writing individual bits. More...
 
Endianness getEndianness () const
 Get the endianness of current multi-byte write operations. More...
 
char const * getName () const
 Get the name of the object. More...
 
std::string getPath () const
 Get the path to the current file being written ("<memory>" for memory streams). More...
 
int64 getPosition () const
 Returns the current byte position in the file, where 0 is the beginning and size() - 1 is the end. More...
 
bool ok () const
 True if no errors have been encountered. More...
 
void printf (char const *fmt,...)
 Print a formatted string to the stream using C-style printf syntax, without null-termination or a preceding length field. More...
 
void reset ()
 A memory stream may be reset so that it can be written to again without allocating new memory. More...
 
void setEndianness (Endianness endian)
 Set the endianness of subsequent multi-byte write operations. 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)
 Sets the position. More...
 
void setSize (int64 n)
 Sets the length of the stream to n. More...
 
int64 size () const
 Get the total number of bytes written. More...
 
void skip (int64 n)
 Skips ahead n bytes (can skip past end-of-file, in which case the newly added bytes have undefined values). More...
 
void vprintf (char const *fmt, va_list arg_list)
 Print a formatted string to the stream using C-style vprintf syntax, without null-termination or a preceding length field. More...
 
void writeAlignedString (std::string const &s, int alignment=4)
 Write an aligned string. More...
 
void writeBits (int num_bits, uint32 bit_string)
 Write num_bits bits from bit_string. More...
 
void writeBool8 (bool b)
 Write an 8-bit boolean value (0 for false, non-zero for true). More...
 
void writeBytes (int64 n, void const *b)
 Write a sequence of bytes. More...
 
void writeColorL (ColorL const &c)
 Write a color with 1 floating-point channel. More...
 
void writeColorL8 (ColorL8 const &c)
 Write a color with 1 8-bit channel. More...
 
void writeColorRgb (ColorRgb const &c)
 Write a color with 3 floating-point channels. More...
 
void writeColorRgb8 (ColorRgb8 const &c)
 Write a color with 3 8-bit channels. More...
 
void writeColorRgba (ColorRgba const &c)
 Write a color with 3 floating-point channels. More...
 
void writeColorRgba8 (ColorRgba8 const &c)
 Write a color with 4 8-bit channels. More...
 
void writeCoordinateFrame3 (CoordinateFrame3 const &c)
 Write a coordinate frame. More...
 
void writeFloat32 (float32 f)
 Write a 32-bit floating point number. More...
 
void writeFloat64 (float64 f)
 Write a 64-bit floating point number. More...
 
void writeInt16 (int16 i)
 Write a signed 16-bit integer. More...
 
void writeInt32 (int32 i)
 Write a signed 32-bit integer. More...
 
void writeInt64 (int64 i)
 Write a signed 64-bit integer. More...
 
void writeInt8 (int8 i)
 Write a signed 8-bit integer. More...
 
template<typename MatrixT >
void writeMatrix (MatrixT const &m, Codec const &codec, bool write_block_header=false)
 Write an arbitrary dense or sparse 2D matrix, using a codec such as CSV or HDF5. More...
 
void writeMatrix2 (Matrix2 const &m)
 Write a 2x2 matrix. More...
 
void writeMatrix3 (Matrix3 const &m)
 Write a 3x3 matrix. More...
 
void writeMatrix4 (Matrix4 const &m)
 Write a 4x4 matrix. More...
 
void writePlane3 (Plane3 const &plane)
 Write a 3D plane. More...
 
void writeString (std::string const &s)
 Write a string. More...
 
void writeUInt16 (uint16 u)
 Write an unsigned 16-bit integer. More...
 
void writeUInt32 (uint32 u)
 Write an unsigned 32-bit integer. More...
 
void writeUInt64 (uint64 u)
 Write an unsigned 64-bit integer. More...
 
void writeUInt8 (uint8 i)
 Write an unsigned 8-bit integer. More...
 
void writeVector2 (Vector2 const &v)
 Write a 2-vector. More...
 
void writeVector3 (Vector3 const &v)
 Write a 3-vector. More...
 
void writeVector4 (Vector4 const &v)
 Write a 4-vector. More...
 
 ~BinaryOutputStream ()
 Destructor. More...
 

Protected Member Functions

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

Detailed Description

Sequential or random access output to binary files/memory.

For every writeX method there are also versions that operate on a whole Array or C-array.

Any method call can trigger an out-of-memory error when writing to a memory buffer if it can't be expanded any more.

This class does not use overloading to distinguish between writing, say, a float and a double. Instead, the write functions are explicitly named writeFloat32(), writeFloat64() etc. This is because it would be very hard to debug the error sequence: bo.write(1.0); ... float f = bi.readFloat32(); in which a double is written and then read as a float.

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

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

Definition at line 67 of file BinaryOutputStream.hpp.

Constructor & Destructor Documentation

BinaryOutputStream ( Endianness  endian = Endianness::LITTLE)
explicit

Construct a stream that writes to an (expanding, contiguous) memory buffer.

Definition at line 229 of file BinaryOutputStream.cpp.

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

Construct a stream that writes to a file.

Use "<memory>" as the path if you're going to commit to memory – this has the same effect as the default constructor. The file and its parent directories will be created if they do not exist, and the file initialized to be blank. If the file cannot be constructed, ok() will return false.

Definition at line 245 of file BinaryOutputStream.cpp.

Destructor.

Automatically calls commit().

Definition at line 279 of file BinaryOutputStream.cpp.

Member Function Documentation

void beginBits ( )

Begin writing individual bits.

Call before a series of writeBits() calls. Only writeBits() can be called between beginBits and endBits without corrupting the stream.

Definition at line 495 of file BinaryOutputStream.cpp.

bool commit ( bool  flush = true)

Write the buffered data to disk.

Parent directories are created as needed if they do not exist. Calling commit() multiple times without intermediate writes is safe – the second and subsequent calls are no-ops.

Note
You cannot seek backwards in the file beyond the commit point, after calling commit().
Parameters
flushIf true (default) the file is ready for reading when the method returns, otherwise the method returns immediately and writes the file in the background.
Returns
True if the commit succeeded, else false.

Definition at line 301 of file BinaryOutputStream.cpp.

void commit ( uint8 *  dst) const

Copy data in a memory stream to a memory buffer (which must be preallocated to at least size() bytes).

The stream buffer remains unchanged.

Triggers an error if this is a file stream.

Definition at line 368 of file BinaryOutputStream.cpp.

void endBits ( )

End writing individual bits.

Call after a series of writeBits() calls. This will finish out with zeros the last byte into which bits were written.

Definition at line 528 of file BinaryOutputStream.cpp.

Endianness getEndianness ( ) const

Get the endianness of current multi-byte write operations.

Definition at line 186 of file BinaryOutputStream.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 written ("<memory>" for memory streams).

Definition at line 192 of file BinaryOutputStream.hpp.

int64 getPosition ( ) const

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

Definition at line 255 of file BinaryOutputStream.hpp.

bool ok ( ) const

True if no errors have been encountered.

Definition at line 295 of file BinaryOutputStream.cpp.

void printf ( char const *  fmt,
  ... 
)

Print a formatted string to the stream using C-style printf syntax, without null-termination or a preceding length field.

This is equivalent to:

std::string s = format(fmt, ...);
output.writeBytes((int64)s.length(), s.data());
See also
vprintf(), writeString()

Definition at line 464 of file BinaryOutputStream.cpp.

void reset ( )

A memory stream may be reset so that it can be written to again without allocating new memory.

The underlying array will not be deallocated, but the reset structure will act like a newly intialized one.

Definition at line 265 of file BinaryOutputStream.cpp.

void setEndianness ( Endianness  endian)

Set the endianness of subsequent multi-byte write operations.

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 288 of file BinaryOutputStream.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)

Sets the position.

Can set past length, in which case the file is padded with undefined data up to one byte before the next to be written.

May throw an exception when seeking backwards in a huge file.

Note
Currently, the increase in size cannot be more than the buffer capacity.

Definition at line 268 of file BinaryOutputStream.hpp.

void setSize ( int64  n)

Sets the length of the stream to n.

If the new size is greater than the old one, the content of the newly allocated section is undefined. Does not change the position of the next byte to be written unless n < size(), in which case it is set to the new stream end.

Throws an error when resetting a huge file to be shorter than its current length.

Note
Currently, the increase in size cannot be more than the buffer capacity.

Definition at line 239 of file BinaryOutputStream.hpp.

int64 size ( ) const

Get the total number of bytes written.

Definition at line 225 of file BinaryOutputStream.hpp.

void skip ( int64  n)

Skips ahead n bytes (can skip past end-of-file, in which case the newly added bytes have undefined values).

If n is negative, seeks backwards from the current position

Definition at line 285 of file BinaryOutputStream.hpp.

void vprintf ( char const *  fmt,
va_list  arg_list 
)

Print a formatted string to the stream using C-style vprintf syntax, without null-termination or a preceding length field.

This is equivalent to:

std::string s = vformat(fmt, arg_list);
output.writeBytes((int64)s.length(), s.data());
See also
printf(), writeString()

Definition at line 473 of file BinaryOutputStream.cpp.

void writeAlignedString ( std::string const &  s,
int  alignment = 4 
)

Write 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
BinaryInputStream::readAlignedString()

Definition at line 480 of file BinaryOutputStream.cpp.

void writeBits ( int  num_bits,
uint32  bit_string 
)

Write num_bits bits from bit_string.

Bits are numbered from low to high.

Can only be called between beginBits() and endBits(). Bits written are semantically little-endian, regardless of the actual endianness of the system. That is, writeBits(0xABCD, 16) writes 0xCD to the first byte and 0xAB to the second byte. However, if used with BinaryInput::readBits(), the ordering is transparent to the caller.

Definition at line 505 of file BinaryOutputStream.cpp.

void writeBool8 ( bool  b)

Write an 8-bit boolean value (0 for false, non-zero for true).

Definition at line 319 of file BinaryOutputStream.hpp.

void writeBytes ( int64  n,
void const *  b 
)

Write a sequence of bytes.

Definition at line 291 of file BinaryOutputStream.hpp.

void writeColorL ( ColorL const &  c)

Write a color with 1 floating-point channel.

Definition at line 481 of file BinaryOutputStream.hpp.

void writeColorL8 ( ColorL8 const &  c)

Write a color with 1 8-bit channel.

Definition at line 475 of file BinaryOutputStream.hpp.

void writeColorRgb ( ColorRgb const &  c)

Write a color with 3 floating-point channels.

Definition at line 495 of file BinaryOutputStream.hpp.

void writeColorRgb8 ( ColorRgb8 const &  c)

Write a color with 3 8-bit channels.

Definition at line 487 of file BinaryOutputStream.hpp.

void writeColorRgba ( ColorRgba const &  c)

Write a color with 3 floating-point channels.

Definition at line 512 of file BinaryOutputStream.hpp.

void writeColorRgba8 ( ColorRgba8 const &  c)

Write a color with 4 8-bit channels.

Definition at line 503 of file BinaryOutputStream.hpp.

void writeCoordinateFrame3 ( CoordinateFrame3 const &  c)

Write a coordinate frame.

Definition at line 546 of file BinaryOutputStream.hpp.

void writeFloat32 ( float32  f)

Write a 32-bit floating point number.

Definition at line 352 of file BinaryOutputStream.hpp.

void writeFloat64 ( float64  f)

Write a 64-bit floating point number.

Definition at line 366 of file BinaryOutputStream.hpp.

void writeInt16 ( int16  i)

Write a signed 16-bit integer.

Definition at line 328 of file BinaryOutputStream.hpp.

void writeInt32 ( int32  i)

Write a signed 32-bit integer.

Definition at line 337 of file BinaryOutputStream.hpp.

void writeInt64 ( int64  i)

Write a signed 64-bit integer.

Definition at line 346 of file BinaryOutputStream.hpp.

void writeInt8 ( int8  i)

Write a signed 8-bit integer.

Definition at line 311 of file BinaryOutputStream.hpp.

void writeMatrix ( MatrixT const &  m,
Codec const &  codec,
bool  write_block_header = false 
)

Write an arbitrary dense or sparse 2D matrix, using a codec such as CSV or HDF5.

Parameters
mThe matrix to write.
codecThe codec to use.
write_block_headerIf true, first write a header section which stores the size and codec of the serialized matrix data.

Definition at line 446 of file MatrixIO.hpp.

void writeMatrix2 ( Matrix2 const &  m)

Write a 2x2 matrix.

Definition at line 521 of file BinaryOutputStream.hpp.

void writeMatrix3 ( Matrix3 const &  m)

Write a 3x3 matrix.

Definition at line 530 of file BinaryOutputStream.hpp.

void writeMatrix4 ( Matrix4 const &  m)

Write a 4x4 matrix.

Definition at line 538 of file BinaryOutputStream.hpp.

void writePlane3 ( Plane3 const &  plane)

Write a 3D plane.

Definition at line 553 of file BinaryOutputStream.hpp.

void writeString ( std::string const &  s)

Write a string.

The format is:

  • Length of string (32-bit integer)
  • Characters of string ('length' bytes, no null termination)
See also
BinaryInputStream::readString()
Note
This version explicitly writes the length of the string and does not rely on null termination, making this a safer option than the original G3D version. To write raw character sequences, use printf() or writeBytes().

Definition at line 414 of file BinaryOutputStream.hpp.

void writeUInt16 ( uint16  u)

Write an unsigned 16-bit integer.

Definition at line 375 of file BinaryOutputStream.cpp.

void writeUInt32 ( uint32  u)

Write an unsigned 32-bit integer.

Definition at line 399 of file BinaryOutputStream.cpp.

void writeUInt64 ( uint64  u)

Write an unsigned 64-bit integer.

Definition at line 428 of file BinaryOutputStream.cpp.

void writeUInt8 ( uint8  i)

Write an unsigned 8-bit integer.

Definition at line 303 of file BinaryOutputStream.hpp.

void writeVector2 ( Vector2 const &  v)

Write a 2-vector.

Definition at line 451 of file BinaryOutputStream.hpp.

void writeVector3 ( Vector3 const &  v)

Write a 3-vector.

Definition at line 458 of file BinaryOutputStream.hpp.

void writeVector4 ( Vector4 const &  v)

Write a 4-vector.

Definition at line 466 of file BinaryOutputStream.hpp.


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