IO#

Input/output related functions for printing, flushing, writing, reading and scanning.

Info

To use declarations from this page, include the <essence/io.hpp> header.

std::string io::readline(std::FILE *stream, char delimiter = '\n')#: Read from a file stream until a delimiter is reached. The default is to read until a newline character.

std::string line = io::readline(stdin);

if (result.empty())
{
   io::eprintn("Got an empty line!");
   return 1;
}

io::printn("You entered {:s}", line);

template<scannable T> std::expected<T, error> io::scan(std::FILE *port = stdin)#: Scan a line from a file stream for a scannable type. Returns an error object on failure, containing a message and error number.

auto some_integer = io::scan<i32>(stdin);

if (not some_integer)
{
   // hanlde the error
   io::eprintn(some_integer.error().message());
   return some_integer.error().number();
}

io::printn("You entered the number {:d}", *some_integer);

template<scannable T> std::expected<T, error> io::prompt(std::string_view message = "")#: Print a message to stdout and scan a line for a scannable type. Returns an error object on failure, containing a message and error number.

auto result = io::prompt<std::string>("What is your name? ");

if (not result)
{
   io::eprintn(result.error().message());
   return result.error().number();
}

io::printn("Hello {:s}, nice to meet you.", *result);

void io::write(char c, std::FILE *port)#: Write a character to a file stream. stdout by default.

void io::write(const char *s, std::FILE *port)#: Write a string to a file stream. stdout by default.

void io::flush(std::FILE *port)#

Flush a file stream. stdout by default.

Passing a nullptr will cause all ports to be flushed, as in the behaviour of fflush.

template<typename ...Args> void io::print(std::string_view msg, Args&&... args)#

Print a string to stdout after applying the format arguments args.

Example

std::string name { "Will" };
i32 lucky_number = 7;
io::print("Hello {}, your lucky number is {}\n", name, lucky_number);

template<typename ...Args> void io::printn(std::string_view msg, Args&&... args)#

Print a string to stdout with a newline after applying the format arguments args.

Example

std::string name { "Will" };
i32 lucky_number = 7;
io::print("Hello {}, your lucky number is {}", name, lucky_number);

template<typename ...Args> void io::eprint(std::string_view msg, Args&&... args)#: Print a string to stderr after applying the format arguments args.

template<typename ...Args> void io::eprintn(std::string_view msg, Args&&... args)#: Print a string to stderr with a newline after applying the format arguments args.

std::string io::file::to_string(const std::string &path)#

Read a file from disk to a new string. On failure to read path, it will return an empty string.

Parameter path may also be a const char*.

void io::file::to_string(const std::string &path, std::string &out)#

Read a file from disk into the mutable string reference out.

On failure, the string will be unchanged.

Parameter path may also be a const char*.

std::vector<std::string> io::file::lines(const std::string &path) noexcept#

Read a file from disk into a new vector of strings, one entry for each line.

The returned vector will be empty on failure to read path.

Parameter path may also be a const char*.

Example

auto lines = io::file::lines("some-file.txt");

for (usize n = 1; const auto& line: lines)
{
   io::printn("{} | {}", n, line);
   ++n;
}

// output:
//
// 1 | this is line one
// 2 | this is line two
// ...

void io::file::lines(const std::string &path, std::vector<std::string> &out) noexcept#

Read a file from disk into the mutable string vector out.

On failure to read path, out will be unchanged.

Parameter path may also be a const char*.