Jazz2::Scripting::Legacy::jjSTREAM class

A buffer of bytes for storing data and exchanging it with files.

Data is appended at the end and read from the front, which removes it. push() and pop() store and restore values of primitive types, strings and other streams in binary form; write(), get() and getLine() work with raw bytes. A stream can be saved to a file and created from one.

Public static functions

static auto Create() -> jjSTREAM*
Creates an empty stream.
static auto CreateFromFile(const String& filename) -> jjSTREAM*
Creates a stream with the contents of a file.
static auto ZlibCompress(const jjSTREAM& input, jjSTREAM& output) -> bool
Compresses the contents of a stream with zlib.
static auto ZlibUncompress(const jjSTREAM& input, jjSTREAM& output, std::uint32_t size) -> bool
Decompresses zlib data from a stream.
static auto CRC32(const jjSTREAM& input, std::uint32_t crc) -> std::uint32_t
Returns the CRC-32 checksum of the contents of a stream.

Constructors, destructors, conversion operators

jjSTREAM()
Creates a new instance.
~jjSTREAM()

Public functions

auto GetUnreadData() const -> ArrayView<const std::uint8_t>
Returns the bytes not read yet.
void AppendData(ArrayView<const std::uint8_t> data)
Appends bytes at the end.
void AddRef()
Increments the reference count.
void Release()
Decrements the reference count.
auto operator=(const jjSTREAM& o) -> jjSTREAM&
Replaces the contents of this stream with the unread contents of another one.
auto getSize() const -> std::uint32_t
Returns the number of bytes left in the stream.
auto isEmpty() const -> bool
Returns whether no bytes are left in the stream.
auto save(const String& tilename) const -> bool
Saves the contents of the stream to a file and returns whether it succeeded.
void clear()
Removes all contents of the stream.
auto discard(std::uint32_t count) -> bool
Removes count bytes from the front of the stream.
auto write(const String& value) -> bool
Appends the bytes of a string to the stream.
auto write(const jjSTREAM& value) -> bool
Appends the unread bytes of another stream, without storing their length; always returns true.
auto get(String& value, std::uint32_t count) -> bool
Reads count bytes from the front of the stream into a string.
auto get(jjSTREAM& value, std::uint32_t count) -> bool
Reads count bytes from the front of the stream and appends them to another stream.
auto getLine(String& value, const String& delim) -> bool
Reads text from the front of the stream up to a delimiter.
auto push(bool value) -> bool
Appends a boolean value to the stream.
auto push(std::uint8_t value) -> bool
Appends an unsigned 8-bit value to the stream.
auto push(std::int8_t value) -> bool
Appends a signed 8-bit value to the stream.
auto push(std::uint16_t value) -> bool
Appends an unsigned 16-bit value to the stream.
auto push(std::int16_t value) -> bool
Appends a signed 16-bit value to the stream.
auto push(std::uint32_t value) -> bool
Appends an unsigned 32-bit value to the stream.
auto push(std::int32_t value) -> bool
Appends a signed 32-bit value to the stream.
auto push(std::uint64_t value) -> bool
Appends an unsigned 64-bit value to the stream.
auto push(std::int64_t value) -> bool
Appends a signed 64-bit value to the stream.
auto push(float value) -> bool
Appends a single-precision float to the stream.
auto push(double value) -> bool
Appends a double-precision float to the stream.
auto push(const String& value) -> bool
Appends a string to the stream, preceded by its length.
auto push(const jjSTREAM& value) -> bool
Appends the unread contents of another stream, preceded by their length.
auto pop(bool& value) -> bool
Reads a boolean value from the front of the stream.
auto pop(std::uint8_t& value) -> bool
Reads an unsigned 8-bit value from the front of the stream.
auto pop(std::int8_t& value) -> bool
Reads a signed 8-bit value from the front of the stream.
auto pop(std::uint16_t& value) -> bool
Reads an unsigned 16-bit value from the front of the stream.
auto pop(std::int16_t& value) -> bool
Reads a signed 16-bit value from the front of the stream.
auto pop(std::uint32_t& value) -> bool
Reads an unsigned 32-bit value from the front of the stream.
auto pop(std::int32_t& value) -> bool
Reads a signed 32-bit value from the front of the stream.
auto pop(std::uint64_t& value) -> bool
Reads an unsigned 64-bit value from the front of the stream.
auto pop(std::int64_t& value) -> bool
Reads a signed 64-bit value from the front of the stream.
auto pop(float& value) -> bool
Reads a single-precision float from the front of the stream.
auto pop(double& value) -> bool
Reads a double-precision float from the front of the stream.
auto pop(String& value) -> bool
Reads a string stored by push() from the front of the stream.
auto pop(jjSTREAM& value) -> bool
Reads a stream stored by push() from the front of the stream and appends it to another stream.

Function documentation

static jjSTREAM* Jazz2::Scripting::Legacy::jjSTREAM::CreateFromFile(const String& filename)

Creates a stream with the contents of a file.

The file is looked up next to the game's data. If it doesn't exist or its name points outside that directory, the stream is empty, so isEmpty() tells whether anything was saved before.

static bool Jazz2::Scripting::Legacy::jjSTREAM::ZlibCompress(const jjSTREAM& input, jjSTREAM& output)

Compresses the contents of a stream with zlib.

The compressed data replaces the contents of output; input is left unchanged. Returns whether it succeeded, which is always false in builds without zlib support.

static bool Jazz2::Scripting::Legacy::jjSTREAM::ZlibUncompress(const jjSTREAM& input, jjSTREAM& output, std::uint32_t size)

Decompresses zlib data from a stream.

The decompressed data replaces the contents of output. Fails if input isn't valid compressed data or its decompressed size exceeds size bytes, and always in builds without zlib support.

static std::uint32_t Jazz2::Scripting::Legacy::jjSTREAM::CRC32(const jjSTREAM& input, std::uint32_t crc)

Returns the CRC-32 checksum of the contents of a stream.

Uses the standard CRC-32 of zlib; pass a previous result as crc to continue a checksum. Always returns 0 in builds without zlib support.

bool Jazz2::Scripting::Legacy::jjSTREAM::save(const String& tilename) const

Saves the contents of the stream to a file and returns whether it succeeded.

The file is written next to the game's data; names that point outside that directory are rejected. The stream itself is left unchanged. Always fails while the level runs inside the level editor.

bool Jazz2::Scripting::Legacy::jjSTREAM::discard(std::uint32_t count)

Removes count bytes from the front of the stream.

Returns false and leaves the stream unchanged if fewer bytes are left.

bool Jazz2::Scripting::Legacy::jjSTREAM::write(const String& value)

Appends the bytes of a string to the stream.

Unlike push(), no length is stored, so the text can be read back only with get() and a known size, or with getLine(). Always returns true.

bool Jazz2::Scripting::Legacy::jjSTREAM::get(String& value, std::uint32_t count)

Reads count bytes from the front of the stream into a string.

The bytes are removed from the stream. Returns false and leaves the stream unchanged if fewer bytes are left.

bool Jazz2::Scripting::Legacy::jjSTREAM::get(jjSTREAM& value, std::uint32_t count)

Reads count bytes from the front of the stream and appends them to another stream.

The bytes are removed from this stream. Returns false and leaves it unchanged if fewer bytes are left.

bool Jazz2::Scripting::Legacy::jjSTREAM::getLine(String& value, const String& delim)

Reads text from the front of the stream up to a delimiter.

The text before delim is stored in value, and both are removed from the stream. If the delimiter isn't found, the rest of the stream becomes the line and the stream ends up empty. Returns false only if the stream is empty or delim is empty.

bool Jazz2::Scripting::Legacy::jjSTREAM::push(bool value)

Appends a boolean value to the stream.

Every push() overload appends its value in binary form and returns true: 1 byte for bool, int8 and uint8, 2 bytes for the 16-bit types, 4 bytes for int, uint and float, 8 bytes for the 64-bit types and double. Strings and streams take 4 bytes of length followed by their bytes. Read the values back with pop() in the same order and types.

bool Jazz2::Scripting::Legacy::jjSTREAM::pop(bool& value)

Reads a boolean value from the front of the stream.

Every pop() overload reads a value stored by the matching push() and removes its bytes. Returns false if the stream doesn't hold enough bytes for the value.

bool Jazz2::Scripting::Legacy::jjSTREAM::pop(String& value)

Reads a string stored by push() from the front of the stream.

Returns false and leaves the stream unchanged if the stored length exceeds the bytes left.

bool Jazz2::Scripting::Legacy::jjSTREAM::pop(jjSTREAM& value)

Reads a stream stored by push() from the front of the stream and appends it to another stream.

Returns false and leaves the stream unchanged if the stored length exceeds the bytes left.