Get Involved

OutStream

OutStream performs buffered output to an arbitrary output destination.

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.

In general, the format function and << operator are meant for writing text in an 8-bit format compatible with ASCII, such as UTF-8, ISO 8859-1 or Windows-1252. Arithmetic arguments like int and float are converted to text when passed to these functions.

Some OutStream objects contain adapters that perform further conversions. For example, the OutStream returned by FileSystem::openTextForWrite can normalize line endings and convert UTF-8 to other formats such as UTF-16. For more information, see Unicode Support.

To create an OutStream that writes to memory, use MemOutStream.

Header File

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

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

Data Members

 char* 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.

 char* 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(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::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::~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 OutStream::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 OutStream::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 OutStream::numBytesAvailable() const [code]

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

 MutableStringView OutStream::viewAvailable() [code]

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

 bool OutStream::anyBytesAvailable() const [code]

Returns true if curByte < endByte.

 u64 OutStream::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 OutStream::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 OutStream::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 OutStream::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 OutStream::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 OutStream::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 OutStream::write(StringView 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().

 template <typename Args>
void OutStream::format(StringView fmt, const Args& args) [code]

Template function that expands the format string fmt using the given arguments and writes the result to the output stream.

MemOutStream mout;
mout.format("The answer is {}.\n", 42);
return mout.moveToString();

For more information, see Converting Values to Text.

template <typename T>
OutStream& OutStream::operator<<(const T& value) [code]

Template function that writes the the default text representation of value to the output stream.

MemOutStream mout;
mout << "The answer is " << 42 << ".\n";
return mout.moveToString();

For more information, see Converting Values to Text.