Input/Output module

Provides utilities to aid with usage of iostreams. More...

Classes
struct	gears::io::line_iterator< CharT, Traits >
	Iterator that iterates through stdin lines. More...
struct	gears::io::line_reader< CharT, Traits >
	A range object that returns line_iterators. More...

Functions
template<class Elem , class Traits , typename... Args>
void	gears::io::fprint (std::basic_ostream< Elem, Traits > &out, const std::basic_string< Elem, Traits > &str, Args &&...arguments)
	Type-safe iostream alternative to printf. More...
template<typename CharT , typename Traits , typename Alloc , typename Pred >
auto	gears::io::getline_until (std::basic_istream< CharT, Traits > &in, std::basic_string< CharT, Traits, Alloc > &str, Pred p) -> decltype(in)
	Reads a string until a predicate is met. More...
template<typename CharT , typename Traits >
line_reader< CharT, Traits >	gears::io::lines (std::basic_istream< CharT, Traits > &in)
	Returns a range object to iterate through input lines. More...

Detailed Description

This module provides tools to help with iostreams, including prettyprinting, typesafe printf and more.

Prettyprinting is provided in the <gears/io/prettyprint.hpp> header. It provides pretty printing for containers, tuples, and pairs. In order to enable the usage of prettyprinting, you need to use using namespace gears::io::operators. The list of outputs is as follows:

Type	Output of operator<<
std::pair	(a, b)
Containers	[a, b, ..., n]
std::tuple	(a, b, ..., n)

Example usage:

#include <gears/io.hpp>
#include <vector>

namespace io = gears::io;

// needed for operator<< of standard library types
using namespace gears::io::operators;

int main() {
    std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
    io::print("{0} + {0} = {1}\n", v.front(), v[1]);

    // note: generic operator<< doesn't work with io::print
    std::cout << v;
}

Output:

1 + 1 = 2
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Function Documentation

template<class Elem , class Traits , typename... Args>

void gears::io::fprint ( std::basic_ostream< Elem, Traits > &  out, const std::basic_string< Elem, Traits > &  str, Args &&...  arguments  )

inline

fprint is the type-safe and iostream alternative to fprintf. It accepts any ostream type and uses positional arguments rather than format specifiers. Index starts at 0.

Example:

io::fprint(std::cout, std::string("{0} {1} {0}"), 1, 2);
// could be shortened to:
io::print("{0} {1} {0}", 1, 2);
// or
io::fprint(std::cout, "{0} {1} {0}"_s, 1, 2);

would print 1 2 1, with 1 being index 0 and 2 being index 1.

If the argument is out of bounds, the function will throw std::out_of_range. There are two specialisations provided for this function, io::print and io::sprint. io::print is the equivalent of fprint(std::cout, ...) or fprint(std::wcout, ...) depending on the format string passed. io::sprint delegates the output stream to a std::stringstream object to return a string, similar to sprintf.

The format string is currently:

{index[,alignment][:format]}

Where:

index is the required positional argument of the string. If the positional argument is not found, then an exception is thrown.

alignment is an optional signed integer that dictates whether to align left or right. A negative value aligns left, as if calling std::left and a positive value will align right as if calling std::right. The comma is required to specify the alignment, e.g. {0,-10} or {0,10}.

format is an optional format specifier that dictates how to format the string. The format specifier has the syntax of :CN where C is a character dictating the format and N is the precision. The C argument of the format specifier is required to use the N argument. The N argument is the equivalent of std::setprecision(N).

The format specifiers and their equivalences are as follows:

Specifier	Equivalent	Notes
F	std::fixed
E	std::scientific	std::uppercase is enabled
e	std::scientific	std::uppercase is disabled
O	std::oct
X	std::hex	std::uppercase is enabled
x	std::hex	std::uppercase is disabled
B	std::boolalpha
S	std::showpos

In order to escape the { character, you have to insert another one. So for example:

io:print("{{0}", 1);
// prints {0}

There is no need to escape the } character as it is not used to delimit anything.

Parameters

out	stream to print to
str	format string
arguments	args to print

Exceptions

std::out_of_range	index in the format string is out of bounds
std::runtime_error	invalid format string

Definition at line 114 of file fprint.hpp.

template<typename CharT , typename Traits , typename Alloc , typename Pred >

auto gears::io::getline_until ( std::basic_istream< CharT, Traits > &  in, std::basic_string< CharT, Traits, Alloc > &  str, Pred  p  ) -> decltype(in)

inline

Reads a string until a predicate is met. This function behaves similarly to std::getline except that rather than reading until a newline, it reads until a predicate given. The predicate given must have a signature of bool(const CharT&). While this isn't strictly enforced, it's a good idea to not modify the characters as this might lead to unexpected behaviour.

Parameters

in	The input stream to read from.
str	String to write to.
p	Predicate to use.

Returns

The input stream.

Definition at line 46 of file getline.hpp.

template<typename CharT , typename Traits >

line_reader<CharT, Traits> gears::io::lines ( std::basic_istream< CharT, Traits > &  in )

inline

Iterates through input lines. Best used with the range-based for loop.

Example:

#include <gears/io/lines.hpp>
#include <iostream>
#include <fstream>

namespace io = gears::io;

int main() {
    std::ifstream in("test.txt"); // could be any file
    for(auto&& line : io::lines(in)) {
        std::cout << line << '\n';
    }
}

Parameters

in	std::istream derived object to iterate through lines

Returns

line_reader object to iterate through.

Definition at line 132 of file lines.hpp.