|
| constexpr bool | readable () const |
| |
| constexpr bool | writable () const |
| |
| constexpr bool | seekable () const |
| |
|
constexpr bool | seekable (Whence origin) const |
| | True if the stream supports seeking from the specified origin.
|
| |
| Result< ByteSpan > | Read (ByteSpan dest) |
| |
|
Result< ByteSpan > | Read (void *dest, size_t size_bytes) |
| | This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
| |
| Result< ByteSpan > | ReadExact (ByteSpan const buffer) |
| |
| Status | Write (ConstByteSpan data) |
| |
|
Status | Write (const void *data, size_t size_bytes) |
| | This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
| |
|
Status | Write (const std::byte b) |
| | This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
| |
| Status | Seek (ptrdiff_t offset, Whence origin=kBeginning) |
| |
| size_t | Tell () |
| |
| size_t | ConservativeReadLimit () const |
| |
| size_t | ConservativeWriteLimit () const |
| |
A generic stream that may support reading, writing, and seeking, but makes no guarantees about whether any operations are supported. Unsupported functions return Status::Unimplemented() Stream serves as the base for the Reader, Writer, and ReaderWriter interfaces.
Stream cannot be extended directly. Instead, work with one of the derived classes that explicitly supports the required functionality. Stream should almost never be used in APIs; accept a derived class with the required capabilities instead.
All Stream methods are blocking. They return when the requested operation completes.
| Result< ByteSpan > pw::stream::Stream::Read |
( |
ByteSpan |
dest | ) |
|
|
inline |
Reads data from the stream into the provided buffer, if supported. As many bytes as are available up to the buffer size are copied into the buffer. Remaining bytes may by read in subsequent calls. If any number of bytes are read returns OK with a span of the bytes read.
If the reader has been exhausted and is and can no longer read additional bytes it will return OUT_OF_RANGE. This is similar to end-of-file (EOF). Read will only return OUT_OF_RANGE if ConservativeReadLimit() is and will remain zero. A Read operation that is successful and also exhausts the reader returns OK, with all following calls returning OUT_OF_RANGE.
Derived classes should NOT try to override these public read methods. Instead, provide an implementation by overriding DoRead().
- Returns
embed:rst:leading-asterisk
*
* .. pw-status-codes::
*
* OK: Between 1 and ``dest.size_bytes()`` were successfully
* read. Returns the span of read bytes.
*
* UNIMPLEMENTED: This stream does not support reading.
*
* FAILED_PRECONDITION: The Reader is not in state to read data.
*
* RESOURCE_EXHAUSTED: Unable to read any bytes at this time. No
* bytes read. Try again once bytes become available.
*
* OUT_OF_RANGE: Reader has been exhausted, similar to EOF. No bytes
* were read, no more will be read.
*
*
| Result< ByteSpan > pw::stream::Stream::ReadExact |
( |
ByteSpan const |
buffer | ) |
|
|
inline |
Reads exactly the number of bytes requested into the provided buffer, if supported. Internally, the stream is read as many times as necessary to fill the destination buffer. If fewer bytes than requested are available, OUT_OF_RANGE is returned.
Other errors may be returned, as documented on Read().
| Status pw::stream::Stream::Write |
( |
ConstByteSpan |
data | ) |
|
|
inline |
Writes data to this stream. Data is not guaranteed to be fully written out to final resting place on Write return.
If the writer is unable to fully accept the input data size it will abort the write and return RESOURCE_EXHAUSTED.
If the writer has been exhausted and is and can no longer accept additional bytes it will return OUT_OF_RANGE. This is similar to end-of-file (EOF). Write will only return OUT_OF_RANGE if ConservativeWriteLimit() is and will remain zero. A Write operation that is successful and also exhausts the writer returns OK, with all following calls returning OUT_OF_RANGE. When ConservativeWriteLimit() is greater than zero, a Write that is a number of bytes beyond what will exhaust the Write will abort and return RESOURCE_EXHAUSTED rather than OUT_OF_RANGE because the writer is still able to write bytes.
Derived classes should NOT try to override the public Write methods. Instead, provide an implementation by overriding DoWrite().
- Returns
embed:rst:leading-asterisk
*
* .. pw-status-codes::
*
* OK: Data was successfully accepted by the stream.
*
* UNIMPLEMENTED: This stream does not support writing.
*
* FAILED_PRECONDITION: The writer is not in a state to accept data.
*
* RESOURCE_EXHAUSTED: The writer was unable to write all of requested
* data at this time. No data was written.
*
* OUT_OF_RANGE: The Writer has been exhausted, similar to EOF. No
* data was written; no more will be written.
*
*
1.9.6