pw_sys_io

Oveview

Main docs: https://pigweed.dev/pw_sys_io.

Functions
Status	pw::sys_io::ReadByte (std::byte *dest)
Status	pw::sys_io::TryReadByte (std::byte *dest)
Status	pw::sys_io::WriteByte (std::byte b)
StatusWithSize	pw::sys_io::WriteLine (std::string_view s)
StatusWithSize	pw::sys_io::ReadBytes (ByteSpan dest)
StatusWithSize	pw::sys_io::WriteBytes (ConstByteSpan src)

Function Documentation

ReadByte()

Status pw::sys_io::ReadByte

(

std::byte *

dest

)

Reads a single byte from the pw_sys_io backend. This function blocks until it either succeeds or fails to read a byte.

Precondition

This function must be implemented by the pw_sys_io backend.

Warning

Do not build production projects on top of pw_sys_io.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A byte was successfully read and is in ``dest``.
* 
*     RESOURCE_EXHAUSTED: The underlying source vanished.
* 
*  

ReadBytes()

StatusWithSize pw::sys_io::ReadBytes

(

ByteSpan

dest

)

Fills a byte span from the pw_sys_io backend using ReadByte().

This function is implemented by the facade and simply uses ReadByte() to read enough bytes to fill the destination span. If there's an error reading a byte, the read is aborted and the contents of the destination span are undefined. This function blocks until either an error occurs or all bytes are successfully read from the backend's ReadByte() implementation.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The destination span was successfully filled.
* 
*  In all cases, the number of bytes successuflly read to the destination
*  span are returned as part of the ``StatusWithSize``.
* 
*  

TryReadByte()

Status pw::sys_io::TryReadByte

(

std::byte *

dest

)

Reads a single byte from the pw_sys_io backend, if available.

Precondition

This function must be implemented by the pw_sys_io backend.

Warning

Do not build production projects on top of pw_sys_io.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A byte was successfully read and is in ``dest``.
* 
*     UNAVAILABLE: No byte is available to read; try later.
* 
*     UNIMPLEMENTED: The function is not supported on this target.
* 
*  

WriteByte()

Status pw::sys_io::WriteByte

(

std::byte

b

)

Writes a single byte out the pw_sys_io backend. The function blocks until it either succeeds or fails to write the byte.

Precondition

This function must be implemented by the pw_sys_io backend.

Warning

Do not build production projects on top of pw_sys_io.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A byte was successfully written.
* 
*  

WriteBytes()

StatusWithSize pw::sys_io::WriteBytes

(

ConstByteSpan

src

)

Writes a span of bytes out the pw_sys_io backend using WriteByte().

This function is implemented by the facade and simply writes the source contents using WriteByte(). If an error writing a byte is encountered, the write is aborted and the error status is returned. This function blocks until either an error occurs, or all bytes are successfully written from the backend's WriteByte() implementation.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: All the bytes from the source span were successfully written.
* 
*  In all cases, the number of bytes successfully written are returned as
*  part of the ``StatusWithSize``.
* 
*  

WriteLine()

StatusWithSize pw::sys_io::WriteLine

(

std::string_view

s

)

Writes a string out the pw_sys_io backend.

This function takes a string_view and writes it out the pw_sys_io backend, adding any platform-specific newline character(s) (these are accounted for in the returned StatusWithSize).

Precondition

This function must be implemented by the pw_sys_io backend.

Warning

Do not build production projects on top of pw_sys_io.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: All the bytes from the source string were successfully
*     written.
* 
*  In all cases, the number of bytes successfully written are returned as
*  part of the ``StatusWithSize``.
* 
*