OutStream

OutStream performs buffered output to an arbitrary output destination. The output can be sent to an OutPipe or to memory.

OutStream is similar to FILE in C or std::ostream in C++. It maintains an internal output buffer on the heap, and provides functions to quickly write small amounts of data incrementally, making it suitable for application-level serialization of text and binary formats. OutPipe, on the other hand, is a lower-level class more akin to a Unix file descriptor.

Every OutStream is also a StringWriter, and you can cast an OutStream to a StringWriter at any time by calling strWriter(). The main reason why OutStream and StringWriter are separate classes is to help express intention in the code. OutStream is mainly intended to write binary data and StringWriter is mainly intended to write text, but the two classes are interchangeable.

Header File

#include <ply-runtime/io/OutStream.h>

Also included from <ply-runtime/Base.h>.

Data Members

u8* curByte [code]

A pointer to the next byte in the output buffer. If this pointer is equal to endByte, it is not safe to write to the pointer. Use member functions such as tryMakeBytesAvailable() to ensure that this pointer can be written to safely.

u8* endByte [code]

A pointer to the last byte in the output buffer. This pointer does not necessarily represent the end of the output stream; for example, it still might be possible to write more data to the underlying OutPipe, or to allocate a new chunk in a ChunkList, by calling tryMakeBytesAvailable().

Member Functions

OutStream(OutStream&& other) [code]

Move constructor. other is reset to a null stream. This constructor is safe to call even when other is an instance of MemOutStream or ViewOutStream.

OutStream(OptionallyOwned<OutPipe>&& outPipe, u32 chunkSizeExp = DefaultChunkSizeExp) [code]

Constructs an OutStream that writes to an OutPipe. If outPipe is an owned pointer, the OutStream takes ownership of the OutPipe and will automatically destroy it in its destructor. If outPipe is a borrowed pointer, the OutStream does not take ownership of the OutPipe. See OptionallyOwned.

~OutStream() [code]

Destructor. flushMem() is called before the OutStream is destroyed. If the OutStream owns an OutPipe, the OutPipe is also destroyed. If the OutStream borrows an OutPipe but does not own it, the OutPipe is not destroyed. If the OutStream writes to a chunk list in memory, the chunk list is destroyed.

void operator=(OutStream&& other) [code]

Move assignment operator. other is reset to a null stream. This operator is safe to call even when other is an instance of MemOutStream or ViewOutStream.

bool atEOF() const [code]

Returns true if no further data can be written to the stream, such as at the end of a fixed-size ViewOutStream. This function also returns true if there's an error in the underlying OutPipe that prevents further writing, such as when a network socket is closed prematurely.

u32 numBytesAvailable() const [code]

Returns the number of bytes between curByte and endByte. Equivalent to viewAvailable().numBytes.

BufferView viewAvailable() [code]

Returns the memory region between curByte and endByte as a BufferView.

bool anyBytesAvailable() const [code]

Returns true if curByte < endByte.

u64 getSeekPos() const [code]

Returns a number that increases each time a byte is written to the OutStream. If the underlying OutPipe is a file, this number typically corresponds to the file offset.

bool flush(bool toDevice = true) [code]

Flushes the internal memory buffer in the same manner as flushMem(), then performs an implementation-specific device flush if writing to an OutPipe and toDevice is true. For example, if toDevice is true, this will call fsync() on when writing to a POSIX file descriptor or FlushFileBuffers() when writing to a Windows file handle. Returns true unless there's an error in the implementation-specific device flush.

void flushMem() [code]

Flushes the internal memory buffer to the underlying OutPipe or chunk list. If writing to an OutPipe, also flushes any application-level memory buffers maintained by the OutPipe, such as when the OutPipe is a conversion, compression or encryption filter.

u32 tryMakeBytesAvailable(u32 numBytes = 1) [code]

Attempts to make at least numBytes available to write contiguously at curByte. Returns the number of bytes actually made available. If EOF/error is encountered, the return value will be less than numBytes; otherwise, it will be greater than or equal to numBytes.

void makeBytesAvailable(u32 numBytes = 1) [code]

Always makes at least numBytes available to write contiguously at curByte. If EOF/error is encountered, this function will still make at least numBytes available for write; they just won't be flushed to the underlying OutPipe later.

bool writeByte(u8 byte) [code]

Writes a single byte to the output buffer in memory. If the output buffer is full, this function flushes the internal memory buffer to the underlying OutPipe or chunk list first. Returns true if the write was successful. The return value of this function is equivalent to !atEOF().

bool write(ConstBufferView src) [code]

Attempts to write src to the output stream in its entirety. Returns true if the write was successful. The return value of this function is equivalent to !atEOF().

StringWriter* strWriter() [code]

Returns a StringWriter interface for the output stream.