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
-
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 astryMakeBytesAvailable()
to ensure that this pointer can be written to safely. -
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 aChunkList
, by callingtryMakeBytesAvailable()
.
Member Functions
-
Move constructor.
other
is reset to a null stream. This constructor is safe to call even whenother
is an instance ofMemOutStream
orViewOutStream
. -
Constructs an
OutStream
that writes to anOutPipe
. IfoutPipe
is an owned pointer, theOutStream
takes ownership of theOutPipe
and will automatically destroy it in its destructor. IfoutPipe
is a borrowed pointer, theOutStream
does not take ownership of theOutPipe
. SeeOptionallyOwned
. OutStream::~OutStream()
[code]-
Destructor.
flushMem()
is called before theOutStream
is destroyed. If theOutStream
owns anOutPipe
, theOutPipe
is also destroyed. If theOutStream
borrows anOutPipe
but does not own it, theOutPipe
is not destroyed. If theOutStream
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 whenother
is an instance ofMemOutStream
orViewOutStream
. -
Returns
true
if no further data can be written to the stream, such as at the end of a fixed-sizeViewOutStream
. This function also returnstrue
if there's an error in the underlyingOutPipe
that prevents further writing, such as when a network socket is closed prematurely. -
Returns the number of bytes between
curByte
andendByte
. Equivalent toviewAvailable().numBytes
. -
Returns the memory region between
curByte
andendByte
as aMutableStringView
. -
Returns
true
ifcurByte < endByte
. -
Returns a number that increases each time a byte is written to the
OutStream
. If the underlyingOutPipe
is a file, this number typically corresponds to the file offset. -
Flushes the internal memory buffer in the same manner as
flushMem()
, then performs an implementation-specific device flush if writing to anOutPipe
andtoDevice
istrue
. For example, iftoDevice
istrue
, this will callfsync()
on when writing to a POSIX file descriptor orFlushFileBuffers()
when writing to a Windows file handle. Returnstrue
unless there's an error in the implementation-specific device flush. -
Flushes the internal memory buffer to the underlying
OutPipe
or chunk list. If writing to anOutPipe
, also flushes any application-level memory buffers maintained by theOutPipe
, such as when theOutPipe
is a conversion, compression or encryption filter. -
Attempts to make at least
numBytes
available to write contiguously atcurByte
. Returns the number of bytes actually made available. If EOF/error is encountered, the return value will be less thannumBytes
; otherwise, it will be greater than or equal tonumBytes
. -
Always makes at least
numBytes
available to write contiguously atcurByte
. If EOF/error is encountered, this function will still make at leastnumBytes
available for write; they just won't be flushed to the underlyingOutPipe
later. -
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. Returnstrue
if the write was successful. The return value of this function is equivalent to!atEOF()
. -
Attempts to write
src
to the output stream in its entirety. Returnstrue
if the write was successful. The return value of this function is equivalent to!atEOF()
. -
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 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.