Streams

A stream system to replace the C++ iostreams. More...

Files
file	io.hh
	File streams and standard output/input/error manipulation.
file	stream.hh
	A base class for streams plus stream utilities.

Classes
struct	ostd::file_stream
	A file stream. More...
struct	ostd::stream_range< T, bool >
struct	ostd::stream_error
	Thrown on stream errors. More...
struct	ostd::stream_line_range< T, TC >
	A range type for streams to read by line. More...
struct	ostd::stream
	A base stream class. More...
struct	ostd::stream_range< T, true >
	A range type for streams. More...

Typedefs
using	ostd::stream_off_t = off_t
	The stream offset type. More...

Enumerations
enum	ostd::stream_mode {   ostd::stream_mode::READ = 0, ostd::stream_mode::WRITE, ostd::stream_mode::APPEND, ostd::stream_mode::READ_U,   ostd::stream_mode::WRITE_U, ostd::stream_mode::APPEND_U }
	The mode to open file streams with. More...
enum	ostd::stream_seek { ostd::stream_seek::CUR = SEEK_CUR, ostd::stream_seek::END = SEEK_END, ostd::stream_seek::SET = SEEK_SET }
	Reference position for seeking. More...

Functions
void	ostd::swap (file_stream &a, file_stream &b)
	Swaps two file streams including ownership.
template<typename ... A>
void	ostd::write (A const &...args)
	Writes all given values into standard output. More...
template<typename ... A>
void	ostd::writeln (A const &...args)
	Writes all given values into standard output followed by a newline. More...
template<typename ... A>
void	ostd::writef (string_range fmt, A const &...args)
	Writes a formatted string into standard output. More...
template<typename ... A>
void	ostd::writefln (string_range fmt, A const &...args)
	Writes a formatted string into standard output followed by a newline. More...
template<typename T = char>
stream_range< T >	ostd::stream::iter ()
	Creates a range around the stream. More...
template<typename T = char, typename TC = std::basic_string<T>>
stream_line_range< T, TC >	ostd::stream::iter_lines (bool keep_nl=false)
	Creates a by-line range around the stream. More...
template<typename ... A>
void	ostd::stream::write (A const &...args)
	Writes all given values into the stream. More...
template<typename ... A>
void	ostd::stream::writef (string_range fmt, A const &...args)
	Writes a formatted string into the stream. More...

Variables
OSTD_EXPORT file_stream	ostd::cin
	Standard input file stream.
OSTD_EXPORT file_stream	ostd::cout
	Standard output file stream.
OSTD_EXPORT file_stream	ostd::cerr
	Standard error file stream.

Detailed Description

A stream system to replace the C++ iostreams.

Libostd provides a custom stream system with considerably simpler API and integration with other libostd features (such as ranges).

Some string examples:

#include <vector>

#include <ostd/algorithm.hh>
#include <ostd/string.hh>
#include <ostd/io.hh>

using namespace ostd;

int main() {
    writeln("writing sample file...");

    file_stream wtest{"test.txt", stream_mode::WRITE};

    std::string smpl =
        "This is a test file for later read.\n"
        "It contains some sample text in order to see whether "
        "things actually read correctly.\n\n\n"
        ""
        "This is after a few newlines. The file continues here.\n"
        "The file ends here.\n";

    copy(iter(smpl), wtest.iter());
    wtest.close();

    file_stream test{"test.txt"};

    writeln("## WHOLE FILE READ ##\n");

    auto fr = test.iter();
    writefln(
        "-- str beg --\n%s-- str end --",
        std::string{fr.iter_begin(), fr.iter_end()}
    );

    test.seek(0);

    writeln("\n## PART FILE READ ##\n");

    auto fr2 = test.iter().take(25);
    writefln(
        "-- str beg --\n%s\n-- str end --",
        std::string{fr2.iter_begin(), fr2.iter_end()}
    );

    test.seek(0);

    writeln("\n## BY LINE READ ##\n");

    for (auto const &line: test.iter_lines()) {
        writeln("got line: ", line);
    }

    test.close();

    writeln("\n## FILE SORT ##\n");

    wtest.open("test.txt", stream_mode::WRITE);

    smpl = "foo\n"
        "bar\n"
        "baz\n"
        "test\n"
        "this\n"
        "will\n"
        "be\n"
        "in\n"
        "order\n";

    copy(iter(smpl), wtest.iter());
    wtest.close();

    test.open("test.txt");

    auto lns = test.iter_lines();
    std::vector<std::string> x{lns.iter_begin(), lns.iter_end()};
    writeln("before sort: ", x);
    sort(iter(x));
    writeln("after sort: ", x);

    return 0;
}

And binary examples:

#include <ostd/platform.hh>
#include <ostd/io.hh>

using namespace ostd;

inline void print_result(uint32_t x) {
    writefln("got x: 0x%X", x);
}

int main() {
    file_stream wtest{"test.bin", stream_mode::WRITE};
    copy(
        iter({ 0xABCD1214, 0xBADC3264, 0xDEADBEEF, 0xBEEFDEAD }),
        wtest.iter<uint32_t>()
    );
    wtest.close();

    file_stream rtest{"test.bin"};
    writefln("stream size: %d", rtest.size());

    for (uint32_t x: map(rtest.iter<uint32_t>(), from_big_endian<uint32_t>())) {
        print_result(x);
    }

    return 0;
}

See the examples provided with the library for further information.

Typedef Documentation

stream_off_t

using ostd::stream_off_t = typedef off_t

The stream offset type.

This is a signed integer type that can represent file sizes and offsets. On POSIX systems, it defaults to the POSIX off_t type. On Windows, it's a signed 64-bit integer. On other systems it's long.

Enumeration Type Documentation

stream_mode

enum ostd::stream_mode

strong

The mode to open file streams with.

Libostd file streams are always opened in binary mode. Text mode is not directly supported (the only way to get it is to encapsulate a C FILE * that is already opened in text mode).

See the C fopen() function documentation for more info on modes.

Enumerator
READ	Reading, equivalent to the C rb mode.
WRITE	Writing, equivalent to the C wb mode.
APPEND	Appending, equivalent to the C ab mode.
READ_U	Read/update, equivalent to the C rb+ mode.
WRITE_U	Write/update, equivalent to the C wb+ mode.
APPEND_U	Append/update, equivalent to the C ab+ mode.

stream_seek

enum ostd::stream_seek

strong

Reference position for seeking.

Streams don't need to support the end of stream position. Therefore, do not rely on it for generic stream usage (though it's fine for files).

Enumerator
CUR	Current position in the stream.
END	End of stream position.
SET	Beginning of the stream.

Function Documentation

iter()

template<typename T >

stream_range< T > ostd::stream::iter ( )

inline

Creates a range around the stream.

The range stays valid as long as the stream is valid. The range does not own the stream, so you have to track the lifetime correctly.

By default, it's a char range that can be read from if the stream can be read from and written into if the stream can be written into. You can override the type by passing in the template parameter. The type must always be trivial.

Template Parameters

T	The type to use for reading/writing (char by default).

See also

iter_lines()

iter_lines()

template<typename T , typename TC >

stream_line_range< T, TC > ostd::stream::iter_lines ( bool  keep_nl = false )

inline

Creates a by-line range around the stream.

Same lifetime rules as with iter() apply. The range uses get_line() to read the lines.

Template Parameters

TC	The string type to use for line storage in the range.

See also

iter()

write() [1/2]

template<typename ... A>

void ostd::write ( A const &...  args )

inline

Writes all given values into standard output.

Behaves the same as calling ostd::stream::write() on ostd::cout, but with more convenience.

See also

ostd::writeln(), ostd::writef(), ostd::writefln()

Examples:

listdir.cc.

write() [2/2]

template<typename ... A>

void ostd::stream::write ( A const &...  args )

inline

Writes all given values into the stream.

There is no separator put between the values. It supports any type that can be formatted using ostd::format_spec with the default s format specifier. The stream's locale is passed into the formatter.

Exceptions

ostd::stream_error	on write error.
ostd::format_error	if a value cannot be formatted.

See also

writeln(), writef(), writefln()

writef() [1/2]

template<typename ... A>

void ostd::writef ( string_range  fmt, A const &...  args  )

inline

Writes a formatted string into standard output.

Behaves the same as calling ostd::stream::writef() on ostd::cout, but with more convenience.

See also

ostd::writefln(), ostd::write(), ostd::writeln()

writef() [2/2]

template<typename ... A>

void ostd::stream::writef ( string_range  fmt, A const &...  args  )

inline

Writes a formatted string into the stream.

Given a format string and arguments, this is just like using ostd::format() with this stream as the sink. The stream's locale is passed into the formatter.

Exceptions

ostd::stream_error	on write error.
ostd::format_error	if the formatting fails.

See also

writefln(), write(), writeln()

writefln()

template<typename ... A>

void ostd::writefln ( string_range  fmt, A const &...  args  )

inline

Writes a formatted string into standard output followed by a newline.

Behaves the same as calling ostd::stream::writefln() on ostd::cout, but with more convenience.

See also

ostd::writef(), ostd::write(), ostd::writeln()

Examples:

concurrency.cc, coroutine1.cc, coroutine2.cc, format.cc, glob.cc, stream1.cc, and stream2.cc.

writeln()

template<typename ... A>

void ostd::writeln ( A const &...  args )

inline

Writes all given values into standard output followed by a newline.

Behaves the same as calling ostd::stream::writeln() on ostd::cout, but with more convenience.

See also

ostd::write(), ostd::writef(), ostd::writefln()

Examples:

argparse.cc, concurrency.cc, coroutine1.cc, coroutine2.cc, format.cc, glob.cc, listdir.cc, range.cc, range_pipe.cc, and stream2.cc.