class Poco::BinaryWriter

Overview

This class writes basic types (and std::vectors of these) in binary form into an output stream. More…

#include <BinaryWriter.h>

class BinaryWriter
{
public:
    // enums

    enum StreamByteOrder;

    // construction

    BinaryWriter(
        std::ostream& ostr,
        StreamByteOrder byteOrder = NATIVE_BYTE_ORDER
        );

    BinaryWriter(
        std::ostream& ostr,
        TextEncoding& encoding,
        StreamByteOrder byteOrder = NATIVE_BYTE_ORDER
        );

    // methods

    BinaryWriter&
    operator<<(bool value);

    BinaryWriter&
    operator<<(char value);

    BinaryWriter&
    operator<<(unsigned char value);

    BinaryWriter&
    operator<<(signed char value);

    BinaryWriter&
    operator<<(short value);

    BinaryWriter&
    operator<<(unsigned short value);

    BinaryWriter&
    operator<<(int value);

    BinaryWriter&
    operator<<(unsigned int value);

    BinaryWriter&
    operator<<(long value);

    BinaryWriter&
    operator<<(unsigned long value);

    BinaryWriter&
    operator<<(float value);

    BinaryWriter&
    operator<<(double value);

    BinaryWriter&
    operator<<(const std::string& value);

    BinaryWriter&
    operator<<(const char* value);

    template <typename T>
    BinaryWriter&
    operator<<(const std::vector<T>& value);

    void
    write7BitEncoded(UInt32 value);

    void
    writeRaw(const std::string& rawData);

    void
    writeRaw(
        const char* buffer,
        std::streamsize length
        );

    void
    writeBOM();

    void
    flush();

    bool
    good();

    bool
    fail();

    bool
    bad();

    std::ostream&
    stream() const;

    StreamByteOrder
    byteOrder() const;
};

// direct descendants

template <typename T>
class BasicMemoryBinaryWriter;

Detailed Documentation

This class writes basic types (and std::vectors of these) in binary form into an output stream.

It provides an inserter-based interface similar to ostream. The writer also supports automatic conversion from big-endian (network byte order) to little-endian and vice-versa. Use a BinaryReader to read from a stream created by a BinaryWriter. Be careful when exchanging data between systems with different data type sizes (e.g., 32-bit and 64-bit architectures), as the sizes of some of the basic types may be different. For example, writing a long integer on a 64-bit system and reading it on a 32-bit system may yield an incorrent result. Use fixed-size types (Int32, Int64, etc.) in such a case.

Construction

BinaryWriter(
    std::ostream& ostr,
    StreamByteOrder byteOrder = NATIVE_BYTE_ORDER
    )

Creates the BinaryWriter.

BinaryWriter(
    std::ostream& ostr,
    TextEncoding& encoding,
    StreamByteOrder byteOrder = NATIVE_BYTE_ORDER
    )

Creates the BinaryWriter using the given TextEncoding.

Strings will be converted from the currently set global encoding (see Poco::TextEncoding::global()) to the specified encoding.

Methods

void
write7BitEncoded(UInt32 value)

Writes a 32-bit unsigned integer in a compressed format.

The value is written out seven bits at a time, starting with the seven least-significant bits. The high bit of a byte indicates whether there are more bytes to be written after this one. If value will fit in seven bits, it takes only one byte of space. If value will not fit in seven bits, the high bit is set on the first byte and written out. value is then shifted by seven bits and the next byte is written. This process is repeated until the entire integer has been written.

void
writeRaw(const std::string& rawData)

Writes the string as-is to the stream.

void
writeRaw(
    const char* buffer,
    std::streamsize length
    )

Writes length raw bytes from the given buffer to the stream.

void
writeBOM()

Writes a byte-order mark to the stream.

A byte order mark is a 16-bit integer with a value of 0xFEFF, written in host byte-order. A BinaryReader uses the byte-order mark to determine the byte-order of the stream.

void
flush()

Flushes the underlying stream.

bool
good()

Returns _ostr.good();.

bool
fail()

Returns _ostr.fail();.

bool
bad()

Returns _ostr.bad();.

std::ostream&
stream() const

Returns the underlying stream.

StreamByteOrder
byteOrder() const

Returns the byte ordering used by the writer, which is either BIG_ENDIAN_BYTE_ORDER or LITTLE_ENDIAN_BYTE_ORDER.