api-reference.md

API Reference

This page lists the public API exposed by the io module. The module lives in the vix::io namespace and provides stream-oriented helpers for reading bytes, reading lines, writing text, writing bytes, flushing output, copying streams, and wrapping standard input, standard output, and standard error.

For normal application code, include the public IO header:

#include <vix/io.hpp>

For examples that print diagnostic information, include the Vix print API:

#include <vix/print.hpp>

Namespace

All IO module APIs are available under:

namespace vix::io

Byte and result types

The module uses Bytes for raw byte data and result aliases for common I/O return values.

using Bytes = std::vector<std::uint8_t>;

using IoBoolResult   = vix::error::Result<bool>;
using IoStringResult = vix::error::Result<std::string>;
using IoBytesResult  = vix::error::Result<Bytes>;
using IoSizeResult   = vix::error::Result<std::uintmax_t>;

These aliases do not introduce a separate error model. They are named forms of vix::error::Result<T> for the values returned by I/O operations.

Alias	Meaning
`Bytes`	Raw byte storage used by read and write operations.
`IoBoolResult`	Result type for operations returning a boolean success value.
`IoStringResult`	Result type for operations returning text.
`IoBytesResult`	Result type for operations returning raw bytes.
`IoSizeResult`	Result type for operations returning a byte count.

Buffer

Buffer is a small in-memory byte buffer.

class Buffer
{
public:
  using value_type = std::uint8_t;
  using storage_type = std::vector<value_type>;

  Buffer();
  explicit Buffer(storage_type data);
  explicit Buffer(std::string_view text);

  bool empty() const noexcept;
  std::size_t size() const noexcept;
  void clear() noexcept;

  void append(const value_type *data, std::size_t size);
  void append(const storage_type &data);
  void append(std::string_view text);

  const storage_type &bytes() const noexcept;
  storage_type &bytes() noexcept;

  const value_type *data() const noexcept;
  value_type *data() noexcept;

  std::string to_string() const;
};

`Buffer()`

Creates an empty buffer.

vix::io::Buffer buffer;

vix::print("empty:", buffer.empty());

`Buffer(storage_type data)`

Creates a buffer from byte storage.

vix::io::Buffer buffer(vix::io::Buffer::storage_type{65, 66, 67});

vix::print("content:", buffer.to_string());

`Buffer(std::string_view text)`

Creates a buffer from text bytes.

vix::io::Buffer buffer("Hello Vix");

vix::print("size:", buffer.size());

`empty`

bool empty() const noexcept;

Returns true when the buffer contains no bytes.

`size`

std::size_t size() const noexcept;

Returns the number of bytes stored in the buffer.

`clear`

void clear() noexcept;

Removes all bytes from the buffer.

`append`

void append(const value_type *data, std::size_t size);
void append(const storage_type &data);
void append(std::string_view text);

Appends raw bytes, byte storage, or text bytes to the end of the buffer. Empty input does nothing.

`bytes`

const storage_type &bytes() const noexcept;
storage_type &bytes() noexcept;

Returns the underlying byte storage.

`data`

const value_type *data() const noexcept;
value_type *data() noexcept;

Returns a pointer to the underlying bytes. Use it together with size().

`to_string`

std::string to_string() const;

Builds a std::string from the stored bytes. This is useful when the buffer contains text-like data.

Input

Input wraps a readable stream.

class Input
{
public:
  explicit Input(std::istream &stream) noexcept;

  IoBytesResult read(std::size_t max_bytes);
  IoStringResult read_line();

  bool good() const noexcept;
  bool eof() const noexcept;

  std::istream &stream() noexcept;
};

`Input`

explicit Input(std::istream &stream) noexcept;

Creates an input wrapper around a readable stream.

std::istringstream source("hello");

vix::io::Input input(source);

`read`

IoBytesResult read(std::size_t max_bytes);

Reads up to max_bytes bytes from the stream.

auto bytes = input.read(5);

if (bytes.ok())
  vix::print("bytes read:", bytes.value().size());

An empty byte vector can mean end-of-stream. It is not automatically an error.

`read_line`

IoStringResult read_line();

Reads one line from the stream and returns it without the trailing newline.

auto line = input.read_line();

if (line.ok())
  vix::print("line:", line.value());

`good`

bool good() const noexcept;

Returns whether the wrapped stream is still in a readable state.

`eof`

bool eof() const noexcept;

Returns whether the wrapped stream has reached end-of-stream.

`stream`

std::istream &stream() noexcept;

Returns the wrapped stream. Use this only when integrating with code that expects a standard C++ input stream.

Output

Output wraps a writable stream.

class Output
{
public:
  explicit Output(std::ostream &stream) noexcept;

  IoSizeResult write(const Bytes &data);
  IoSizeResult write(std::string_view text);

  IoBoolResult flush();

  bool good() const noexcept;

  std::ostream &stream() noexcept;
};

`Output`

explicit Output(std::ostream &stream) noexcept;

Creates an output wrapper around a writable stream.

std::ostringstream target;

vix::io::Output output(target);

`write(bytes)`

IoSizeResult write(const Bytes &data);

Writes raw bytes to the stream and returns the number of bytes written.

vix::io::Bytes bytes{65, 66, 67};

auto written = output.write(bytes);

if (written.ok())
  vix::print("bytes written:", written.value());

`write(text)`

IoSizeResult write(std::string_view text);

Writes text to the stream and returns the number of bytes written. It does not append a newline.

auto written = output.write("hello");

if (written.ok())
  vix::print("bytes written:", written.value());

`flush`

IoBoolResult flush();

Flushes the wrapped stream.

auto flushed = output.flush();

if (!flushed.ok())
  vix::eprint("flush failed:", flushed.error().message());

`good`

bool good() const noexcept;

Returns whether the wrapped stream is still in a writable state.

`stream`

std::ostream &stream() noexcept;

Returns the wrapped stream. Use this when integrating with code that expects a standard C++ output stream.

Read operations

`read`

IoBytesResult read(Input &input, std::size_t max_bytes);

Reads up to max_bytes bytes from an input stream.

auto bytes = vix::io::read(input, 1024);

if (!bytes.ok())
{
  vix::eprint("read failed:", bytes.error().message());
  return 1;
}

`read_all`

IoBytesResult read_all(Input &input, const IoOptions &options = {});

Reads all remaining bytes from an input stream.

auto bytes = vix::io::read_all(input);

if (bytes.ok())
  vix::print("bytes:", bytes.value().size());

read_all() reads in chunks. The chunk size is controlled by IoOptions::chunk_size.

`read_line`

IoStringResult read_line(Input &input, const IoOptions &options = {});

Reads a single line from an input stream.

auto line = vix::io::read_line(input);

if (line.ok())
  vix::print("line:", line.value());

By default, the returned string does not include the trailing newline. Set IoOptions::keep_newline to preserve it.

Write operations

`write(bytes)`

IoSizeResult write(Output &output, const Bytes &data);

Writes raw bytes to an output stream.

vix::io::Bytes bytes{65, 66, 67};

auto written = vix::io::write(output, bytes);

`write(text)`

IoSizeResult write(Output &output, std::string_view text);

Writes text to an output stream.

auto written = vix::io::write(output, "hello");

write() does not append a newline. Use write_line() for line-oriented output.

`write_line`

IoSizeResult write_line(Output &output,
                        std::string_view text,
                        const IoOptions &options = {});

Writes text followed by a newline sequence.

auto written = vix::io::write_line(output, "status: ok");

if (!written.ok())
{
  vix::eprint("write line failed:", written.error().message());
  return 1;
}

The newline sequence is controlled by IoOptions::newline_mode. The function returns the total number of bytes written, including the newline bytes.

`flush`

IoBoolResult flush(Output &output);

Flushes an output stream.

auto flushed = vix::io::flush(output);

if (!flushed.ok())
  vix::eprint("flush failed:", flushed.error().message());

Copy

`copy`

IoSizeResult copy(Input &input,
                  Output &output,
                  const IoOptions &options = {});

Copies all remaining bytes from an input stream to an output stream and returns the total number of bytes written.

auto copied = vix::io::copy(input, output);

if (!copied.ok())
{
  vix::eprint("copy failed:", copied.error().message());
  return 1;
}

vix::print("copied bytes:", copied.value());

copy() uses IoOptions::chunk_size for internal reads. When IoOptions::auto_flush is true, it flushes the output after the copy finishes.

Standard streams

`stdin_stream`

Input stdin_stream() noexcept;

Returns an Input wrapper around the process standard input stream.

auto input = vix::io::stdin_stream();

`stdout_stream`

Output stdout_stream() noexcept;

Returns an Output wrapper around the process standard output stream.

auto output = vix::io::stdout_stream();

auto written = vix::io::write_line(output, "hello");

`stderr_stream`

Output stderr_stream() noexcept;

Returns an Output wrapper around the process standard error stream.

auto error = vix::io::stderr_stream();

auto written = vix::io::write_line(error, "error: invalid input");

Options

`NewlineMode`

enum class NewlineMode
{
  LF,
  CRLF,
  Native
};

Controls the newline sequence used by write_line().

Value	Meaning
`NewlineMode::LF`	Write `\n`.
`NewlineMode::CRLF`	Write `\r\n`.
`NewlineMode::Native`	Use the platform convention.

On Windows, Native writes \r\n. On other supported platforms, it writes \n.

`IoOptions`

struct IoOptions
{
  std::size_t chunk_size{4096};
  bool keep_newline{false};
  bool auto_flush{false};
  NewlineMode newline_mode{NewlineMode::LF};
};

Common options reused by higher-level I/O operations.

Field	Default	Used by	Purpose
`chunk_size`	`4096`	`read_all`, `copy`	Preferred number of bytes read per chunk.
`keep_newline`	`false`	`read_line`	Preserve the trailing newline in the returned line.
`auto_flush`	`false`	`write_line`, `copy`	Flush output after the operation completes.
`newline_mode`	`NewlineMode::LF`	`write_line`	Choose the newline sequence appended to written lines.

I/O errors

`IoErrorCode`

enum class IoErrorCode
{
  None = 0,
  InvalidInput,
  InvalidOutput,
  InvalidOperation,
  ReadFailed,
  WriteFailed,
  FlushFailed,
  EndOfStream,
  Closed,
  Timeout,
  Unknown
};

Represents semantic I/O failures before they are mapped into the generic Vix error model.

Value	Meaning
`None`	No I/O error.
`InvalidInput`	The input stream or input operation is invalid.
`InvalidOutput`	The output stream or output operation is invalid.
`InvalidOperation`	The requested operation is invalid in the current context.
`ReadFailed`	Reading from the input stream failed.
`WriteFailed`	Writing to the output stream failed.
`FlushFailed`	Flushing the output stream failed.
`EndOfStream`	The operation reached the end of the stream.
`Closed`	The stream or channel is closed.
`Timeout`	The operation timed out.
`Unknown`	The failure could not be classified more precisely.

`io_error_category`

inline constexpr vix::error::ErrorCategory
io_error_category() noexcept;

Returns the IO module error category.

auto category = vix::io::io_error_category();

The category name is io.

`to_error_code`

inline constexpr vix::error::ErrorCode
to_error_code(IoErrorCode code) noexcept;

Converts an IoErrorCode to a generic vix::error::ErrorCode.

I/O error code	Generic error code
`IoErrorCode::None`	`vix::error::ErrorCode::Ok`
`IoErrorCode::InvalidInput`	`vix::error::ErrorCode::InvalidArgument`
`IoErrorCode::InvalidOutput`	`vix::error::ErrorCode::InvalidArgument`
`IoErrorCode::InvalidOperation`	`vix::error::ErrorCode::InvalidArgument`
`IoErrorCode::ReadFailed`	`vix::error::ErrorCode::IoError`
`IoErrorCode::WriteFailed`	`vix::error::ErrorCode::IoError`
`IoErrorCode::FlushFailed`	`vix::error::ErrorCode::IoError`
`IoErrorCode::EndOfStream`	`vix::error::ErrorCode::NotFound`
`IoErrorCode::Closed`	`vix::error::ErrorCode::InvalidState`
`IoErrorCode::Timeout`	`vix::error::ErrorCode::Timeout`
`IoErrorCode::Unknown`	`vix::error::ErrorCode::Unknown`

`to_string`

const char *to_string(IoErrorCode code) noexcept;

Converts an IoErrorCode to a stable symbolic string.

auto name = vix::io::to_string(vix::io::IoErrorCode::WriteFailed);

vix::print("io error:", name);

Returned values include:

none
invalid_input
invalid_output
invalid_operation
read_failed
write_failed
flush_failed
end_of_stream
closed
timeout
unknown

`make_io_error`

vix::error::Error make_io_error(IoErrorCode code,
                                std::string message);

Creates a structured vix::error::Error for the IO module.

auto error = vix::io::make_io_error(
  vix::io::IoErrorCode::WriteFailed,
  "failed to write text to output stream"
);

This helper is mostly useful inside module implementations and tests. Application code usually receives IO errors from public IO functions.

Complete API overview

API	Return type	Purpose
`vix::io::Buffer`	class	Store bytes in memory.
`vix::io::Input`	class	Wrap a readable stream.
`vix::io::Output`	class	Wrap a writable stream.
`vix::io::Bytes`	`std::vector<std::uint8_t>`	Represent raw byte data.
`vix::io::read(input, max_bytes)`	`IoBytesResult`	Read up to a fixed number of bytes.
`vix::io::read_all(input, options)`	`IoBytesResult`	Read all remaining bytes.
`vix::io::read_line(input, options)`	`IoStringResult`	Read one line.
`vix::io::write(output, bytes)`	`IoSizeResult`	Write raw bytes.
`vix::io::write(output, text)`	`IoSizeResult`	Write text.
`vix::io::write_line(output, text, options)`	`IoSizeResult`	Write text followed by a newline.
`vix::io::flush(output)`	`IoBoolResult`	Flush an output stream.
`vix::io::copy(input, output, options)`	`IoSizeResult`	Copy all remaining bytes from input to output.
`vix::io::stdin_stream()`	`Input`	Wrap standard input.
`vix::io::stdout_stream()`	`Output`	Wrap standard output.
`vix::io::stderr_stream()`	`Output`	Wrap standard error.
`vix::io::IoOptions`	struct	Configure chunk size, newline behavior, and auto-flush.
`vix::io::NewlineMode`	enum class	Select the newline sequence used by line writes.
`vix::io::IoErrorCode`	enum class	Represent I/O-specific error cases.
`vix::io::io_error_category()`	`ErrorCategory`	Return the IO error category.
`vix::io::to_error_code(code)`	`ErrorCode`	Convert an IO error code to a generic Vix error code.
`vix::io::to_string(code)`	`const char *`	Convert an IO error code to a symbolic string.
`vix::io::make_io_error(code, message)`	`Error`	Create a structured IO error.

Related pages

Use the topic pages when you need more explanation around a specific group of APIs:

Uh oh!

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Namespace

Byte and result types

Buffer

Buffer()

Buffer(storage_type data)

Buffer(std::string_view text)

empty

size

clear

append

bytes

data

to_string

Input

Input

read

read_line

good

eof

stream

Output

Output

write(bytes)

write(text)

flush

good

stream

Read operations

read

read_all

read_line

Write operations

write(bytes)

write(text)

write_line

flush

Copy

copy

Standard streams

stdin_stream

stdout_stream

stderr_stream

Options

NewlineMode

IoOptions

I/O errors

IoErrorCode

io_error_category

to_error_code

to_string

make_io_error

Complete API overview

Related pages

`Buffer()`

`Buffer(storage_type data)`

`Buffer(std::string_view text)`

`empty`

`size`

`clear`

`append`

`bytes`

`data`

`to_string`

`Input`

`read`

`read_line`

`good`

`eof`

`stream`

`Output`

`write(bytes)`

`write(text)`

`flush`

`good`

`stream`

`read`

`read_all`

`read_line`

`write(bytes)`

`write(text)`

`write_line`

`flush`

`copy`

`stdin_stream`

`stdout_stream`

`stderr_stream`

`NewlineMode`

`IoOptions`

`IoErrorCode`

`io_error_category`

`to_error_code`

`to_string`

`make_io_error`