I/O

A growing collection of I/O utilities. More...

Classes
class	sourcemeta::core::BinaryWriter
class	sourcemeta::core::BinaryReader
class	sourcemeta::core::InputByteStream
class	sourcemeta::core::OutputByteStream
class	sourcemeta::core::FileViewError
class	sourcemeta::core::IOFileNotFoundError
class	sourcemeta::core::IOFilePermissionError
class	sourcemeta::core::IOIsADirectoryError
class	sourcemeta::core::IONotADirectoryError
class	sourcemeta::core::IOFileAlreadyExistsError
class	sourcemeta::core::IOReadOutOfBoundsError
class	sourcemeta::core::IOStreamWriteError
class	sourcemeta::core::FileView
class	sourcemeta::core::TemporaryDirectory

Functions
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::canonical (const std::filesystem::path &path) -> std::filesystem::path
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::weakly_canonical (const std::filesystem::path &path) -> std::filesystem::path
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::is_under_path (const std::filesystem::path &path, const std::filesystem::path &prefix) -> bool
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::is_lexically_under_path (const std::filesystem::path &path, const std::filesystem::path &prefix) -> bool
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::strip_path_prefix (const std::filesystem::path &path, const std::filesystem::path &prefix) -> std::filesystem::path
template<typename CharT = char, typename Traits = std::char_traits<CharT>>
auto	sourcemeta::core::read_file (const std::filesystem::path &path) -> std::basic_ifstream< CharT, Traits >
template<typename CharT = char, typename Traits = std::char_traits<CharT>>
auto	sourcemeta::core::read_to_string (std::basic_istream< CharT, Traits > &stream) -> std::basic_string< CharT, Traits >
template<typename CharT = char, typename Traits = std::char_traits<CharT>>
auto	sourcemeta::core::resume_stream (std::basic_istream< CharT, Traits > &stream, const std::streampos start, const std::streamsize count) -> void
template<typename CharT = char, typename Traits = std::char_traits<CharT>>
auto	sourcemeta::core::read_file_to_string (const std::filesystem::path &path) -> std::basic_string< CharT, Traits >
auto	sourcemeta::core::read_stdin () -> std::string
template<typename Callback>
auto	sourcemeta::core::for_each_line (std::istream &stream, Callback callback) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::hardlink_directory (const std::filesystem::path &source, const std::filesystem::path &destination) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::write_file (const std::filesystem::path &path, const std::string_view contents) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::write_file (const std::filesystem::path &path, const std::span< const std::byte > contents) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::write_file (const std::filesystem::path &path, const std::function< void(std::ostream &)> &writer) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::flush (const std::filesystem::path &path) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::atomic_write_file (const std::filesystem::path &path, const std::string_view contents) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::atomic_write_file (const std::filesystem::path &path, const std::span< const std::byte > contents) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::atomic_write_file (const std::filesystem::path &path, const std::function< void(std::ostream &)> &writer) -> void
SOURCEMETA_CORE_IO_EXPORT auto	sourcemeta::core::atomic_directory_swap (const std::filesystem::path &original, const std::filesystem::path &replacement) -> void

Detailed Description

A growing collection of I/O utilities.

This functionality is included as follows:

#include <sourcemeta/core/io.h>

---

Class Documentation

sourcemeta::core::BinaryWriter

class sourcemeta::core::BinaryWriter

Typed wrapper over an output stream.

#include <sourcemeta/core/io.h>
#include <fstream>
 
std::ofstream raw{"/tmp/out.bin", std::ios::binary};
sourcemeta::core::BinaryWriter writer{raw};
writer.put_dword(0x12345678);

Public Member Functions
	BinaryWriter (std::ostream &stream) noexcept
	Construct a writer over the given output stream.
	BinaryWriter (const BinaryWriter &)=delete
	BinaryWriter (BinaryWriter &&)=delete
auto	put_byte (const std::uint8_t value) -> void
	Write a single byte.
auto	put_word (const std::uint16_t value) -> void
	Write a 16-bit unsigned integer.
auto	put_dword (const std::uint32_t value) -> void
	Write a 32-bit unsigned integer.
auto	put_qword (const std::uint64_t value) -> void
	Write a 64-bit unsigned integer.
auto	put_bytes (const std::byte *data, const std::size_t size) -> void
	Write a raw sequence of bytes.
auto	position () const -> std::size_t
	The number of bytes written so far.

sourcemeta::core::BinaryReader

class sourcemeta::core::BinaryReader

Cursor-tracking reader over a FileView or an std::istream.

#include <sourcemeta/core/io.h>
 
sourcemeta::core::FileView view{"/tmp/out.bin"};
sourcemeta::core::BinaryReader reader{view};
const auto value{reader.get_dword()};

Public Member Functions
	BinaryReader (const FileView &view) noexcept
	Construct a reader over the given file view.
	BinaryReader (std::istream &stream) noexcept
	Construct a reader over the given input stream.
	BinaryReader (const BinaryReader &)=delete
	BinaryReader (BinaryReader &&)=delete
auto	get_byte () -> std::uint8_t
	Read a single byte.
auto	get_word () -> std::uint16_t
	Read a 16-bit unsigned integer.
auto	get_dword () -> std::uint32_t
	Read a 32-bit unsigned integer.
auto	get_qword () -> std::uint64_t
	Read a 64-bit unsigned integer.
auto	get_bytes (std::byte *destination, const std::size_t size) -> void
	Read a raw sequence of bytes.
auto	position () const -> std::size_t
	The current cursor position in bytes.
auto	seek (const std::size_t position) -> void
	Move the cursor to position.
auto	has_more_data () const -> bool
	Whether the source has unconsumed bytes at the current cursor.

sourcemeta::core::InputByteStream

class sourcemeta::core::InputByteStream

An input stream constructed from an inline list of byte values. For example:

#include <sourcemeta/core/io.h>
 
sourcemeta::core::InputByteStream stream{0x1f, 0x8b, 0x08, 0x00};

Inheritance diagram for sourcemeta::core::InputByteStream:

Public Member Functions
SOURCEMETA_CORE_IO_EXPORT	InputByteStream (std::initializer_list< std::uint8_t > bytes)
	Construct the stream from the given byte values.

sourcemeta::core::OutputByteStream

class sourcemeta::core::OutputByteStream

An output stream that exposes its accumulated bytes as a byte vector. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
sourcemeta::core::OutputByteStream stream;
stream.put('A');
assert(stream.bytes().size() == 1);

Inheritance diagram for sourcemeta::core::OutputByteStream:

Public Member Functions
SOURCEMETA_CORE_IO_EXPORT auto	bytes () const -> std::vector< std::byte >
	The accumulated bytes.

sourcemeta::core::FileViewError

class sourcemeta::core::FileViewError

An error that represents a failure to memory-map a file

Inheritance diagram for sourcemeta::core::FileViewError:

Public Member Functions
	FileViewError (std::filesystem::path path, const char *message)
	Construct the error given the offending path and a message.
	FileViewError (std::filesystem::path path, std::string message)=delete
	FileViewError (std::filesystem::path path, std::string &&message)=delete
	FileViewError (std::filesystem::path path, std::string_view message)=delete
auto	path () const noexcept -> const std::filesystem::path &
	The offending path.

sourcemeta::core::IOFileNotFoundError

class sourcemeta::core::IOFileNotFoundError

The requested file does not exist.

Inheritance diagram for sourcemeta::core::IOFileNotFoundError:

Public Member Functions
	IOFileNotFoundError (std::filesystem::path path)
	Construct the error given the offending path.
auto	path () const noexcept -> const std::filesystem::path &
	The offending path.

sourcemeta::core::IOFilePermissionError

class sourcemeta::core::IOFilePermissionError

The current process lacks permission to access the requested path.

Inheritance diagram for sourcemeta::core::IOFilePermissionError:

Public Member Functions
	IOFilePermissionError (std::filesystem::path path)
	Construct the error given the offending path.
auto	path () const noexcept -> const std::filesystem::path &
	The offending path.

sourcemeta::core::IOIsADirectoryError

class sourcemeta::core::IOIsADirectoryError

The path resolves to a directory where a regular file was expected.

Inheritance diagram for sourcemeta::core::IOIsADirectoryError:

Public Member Functions
	IOIsADirectoryError (std::filesystem::path path)
	Construct the error given the offending path.
auto	path () const noexcept -> const std::filesystem::path &
	The offending path.

sourcemeta::core::IONotADirectoryError

class sourcemeta::core::IONotADirectoryError

The path resolves to a regular file where a directory was expected.

Inheritance diagram for sourcemeta::core::IONotADirectoryError:

Public Member Functions
	IONotADirectoryError (std::filesystem::path path)
	Construct the error given the offending path.
auto	path () const noexcept -> const std::filesystem::path &
	The offending path.

sourcemeta::core::IOFileAlreadyExistsError

class sourcemeta::core::IOFileAlreadyExistsError

The destination path already exists and cannot be replaced.

Inheritance diagram for sourcemeta::core::IOFileAlreadyExistsError:

Public Member Functions
	IOFileAlreadyExistsError (std::filesystem::path path)
	Construct the error given the offending path.
auto	path () const noexcept -> const std::filesystem::path &
	The offending path.

sourcemeta::core::IOReadOutOfBoundsError

class sourcemeta::core::IOReadOutOfBoundsError

A read attempted to access bytes outside the bounds of the underlying data.

Inheritance diagram for sourcemeta::core::IOReadOutOfBoundsError:

sourcemeta::core::IOStreamWriteError

class sourcemeta::core::IOStreamWriteError

A write to the underlying stream failed.

Inheritance diagram for sourcemeta::core::IOStreamWriteError:

sourcemeta::core::FileView

class sourcemeta::core::FileView

A read-only memory-mapped file. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
struct Header {
  std::uint32_t magic;
  std::uint32_t version;
};
 
sourcemeta::core::FileView view{"/path/to/file.bin"};
const auto *header = view.as<Header>();
assert(header->magic == 0x12345678);

Public Member Functions
	FileView (const std::filesystem::path &path)
	Memory-map the file at the given path.
	FileView (const FileView &)=delete
	FileView (FileView &&)=delete
auto	size () const noexcept -> std::size_t
	The size of the memory-mapped data in bytes.
template<typename T>
auto	as (const std::size_t offset=0) const noexcept -> const T *

Member Function Documentation

as()

template<typename T>

auto sourcemeta::core::FileView::as ( const std::size_t offset = 0 ) const -> const T *

inlinenodiscardnoexcept

Interpret the memory-mapped data as a pointer to T at the given offset. The caller must ensure that the offset yields a pointer suitably aligned for T, as dereferencing a misaligned pointer is undefined behavior.

sourcemeta::core::TemporaryDirectory

class sourcemeta::core::TemporaryDirectory

An RAII class that creates a uniquely-named temporary directory on construction and removes it on destruction.

#include <sourcemeta/core/io.h>
#include <cassert>
 
sourcemeta::core::TemporaryDirectory staging{"/tmp", ".my-prefix-"};
assert(std::filesystem::exists(staging.path()));

Public Member Functions
	TemporaryDirectory (const std::filesystem::path &parent, const std::string_view prefix)
	TemporaryDirectory (const TemporaryDirectory &)=delete
	TemporaryDirectory (TemporaryDirectory &&)=delete
auto	path () const noexcept -> const std::filesystem::path &
	The path to the temporary directory.

Constructor & Destructor Documentation

TemporaryDirectory()

sourcemeta::core::TemporaryDirectory::TemporaryDirectory	(	const std::filesystem::path &	parent,
		const std::string_view	prefix )

Create a uniquely-named temporary directory under the given parent using the given name prefix.

Function Documentation

atomic_directory_swap()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::atomic_directory_swap	(	const std::filesystem::path &	original,
		const std::filesystem::path &	replacement ) -> void

Atomically swap two directories. Both directories must reside on the same filesystem and the original path must not be a bare filename (it must have a parent component). After the call, the original path holds the contents of the replacement and the replacement path holds the former contents of the original. If the original does not exist, the replacement is simply renamed into place and the replacement path will no longer exist.

#include <sourcemeta/core/io.h>
 
sourcemeta::core::atomic_directory_swap("/output", "/staging");

atomic_write_file() [1/3]

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::atomic_write_file	(	const std::filesystem::path &	path,
		const std::function< void(std::ostream &)> &	writer ) -> void

Callback variant of atomic_write_file. For example:

#include <sourcemeta/core/io.h>
#include <sourcemeta/core/json.h>
 
sourcemeta::core::atomic_write_file("/tmp/foo.json",
    [&](std::ostream &stream) {
      sourcemeta::core::prettify(document, stream);
      stream << "\n";
    });

atomic_write_file() [2/3]

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::atomic_write_file	(	const std::filesystem::path &	path,
		const std::span< const std::byte >	contents ) -> void

Atomically write a byte span to path. For example:

#include <sourcemeta/core/io.h>
#include <array>
 
constexpr std::array<std::byte, 3> bytes{
    std::byte{0x41}, std::byte{0x42}, std::byte{0x43}};
sourcemeta::core::atomic_write_file("/tmp/foo.bin", std::span{bytes});

atomic_write_file() [3/3]

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::atomic_write_file	(	const std::filesystem::path &	path,
		const std::string_view	contents ) -> void

Atomically write contents to path. For example:

#include <sourcemeta/core/io.h>
 
sourcemeta::core::atomic_write_file("/tmp/foo.json", "{\"a\":1}");

canonical()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::canonical

(

const std::filesystem::path &

path

)

-> std::filesystem::path

A safe variant of std::filesystem::canonical that takes into account platform-specific oddities like FIFO on GNU/Linux. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
const auto output{sourcemeta::core::canonical("/tmp/../foo.json")};
assert(output == "/foo.json");

flush()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::flush

(

const std::filesystem::path &

path

)

-> void

Flush an existing file to disk, beyond just to the operating system. For example:

#include <sourcemeta/core/io.h>
 
sourcemeta::core::flush("/foo/bar.txt");

for_each_line()

template<typename Callback>

auto sourcemeta::core::for_each_line	(	std::istream &	stream,
		Callback	callback ) -> void

Iterate the lines of stream, invoking callback with each line. A trailing carriage return is dropped so that Windows line endings produce the same line as Unix ones. The line view is only valid for the duration of the callback. For example:

#include <sourcemeta/core/io.h>
#include <iostream>
#include <sstream>
 
std::istringstream stream{"alpha\nbeta\ngamma\n"};
sourcemeta::core::for_each_line(stream,
    [](const std::string_view line) {
      std::cout << line << '\n';
    });

hardlink_directory()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::hardlink_directory	(	const std::filesystem::path &	source,
		const std::filesystem::path &	destination ) -> void

Recursively mirror a directory tree using hard links for regular files. Directories are created, regular files are hard-linked. Both paths must reside on the same filesystem. The destination must not be inside the source tree, as that would cause infinite recursion.

#include <sourcemeta/core/io.h>
 
sourcemeta::core::hardlink_directory("/source", "/destination");

is_lexically_under_path()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::is_lexically_under_path	(	const std::filesystem::path &	path,
		const std::filesystem::path &	prefix ) -> bool

Check whether a path lies under another path lexically, comparing component by component without resolving against the filesystem. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
assert(sourcemeta::core::is_lexically_under_path("foo/bar/baz", "foo"));

is_under_path()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::is_under_path	(	const std::filesystem::path &	path,
		const std::filesystem::path &	prefix ) -> bool

Check whether a path lies under another path, comparing component by component after weak canonicalisation. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
assert(sourcemeta::core::is_under_path("/foo/bar/baz", "/foo"));

read_file()

template<typename CharT = char, typename Traits = std::char_traits<CharT>>

auto sourcemeta::core::read_file

(

const std::filesystem::path &

path

)

-> std::basic_ifstream< CharT, Traits >

A convenience function to open a stream from a file in binary mode, so that its positions are byte offsets on every platform. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
auto stream{sourcemeta::core::read_file("/tmp/foo.json")};
assert(stream.is_open());

read_file_to_string()

template<typename CharT = char, typename Traits = std::char_traits<CharT>>

auto sourcemeta::core::read_file_to_string

(

const std::filesystem::path &

path

)

-> std::basic_string< CharT, Traits >

Read an entire file into a string. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
const auto contents{sourcemeta::core::read_file_to_string("/tmp/foo.json")};
assert(!contents.empty());

read_stdin()

auto sourcemeta::core::read_stdin ( ) -> std::string

inline

Drain std::cin fully into a string. For example:

#include <sourcemeta/core/io.h>
 
const auto input{sourcemeta::core::read_stdin()};

read_to_string()

template<typename CharT = char, typename Traits = std::char_traits<CharT>>

auto sourcemeta::core::read_to_string

(

std::basic_istream< CharT, Traits > &

stream

)

-> std::basic_string< CharT, Traits >

Drain an input stream into a string. For example:

#include <sourcemeta/core/io.h>
#include <sstream>
#include <cassert>
 
std::istringstream stream{"hello"};
const auto contents{sourcemeta::core::read_to_string(stream)};
assert(contents == "hello");

resume_stream()

template<typename CharT = char, typename Traits = std::char_traits<CharT>>

auto sourcemeta::core::resume_stream	(	std::basic_istream< CharT, Traits > &	stream,
		const std::streampos	start,
		const std::streamsize	count ) -> void

Position an input stream a given number of characters after a position it previously reported, leaving a stream that could not report one untouched. The stream must address its contents in bytes, as one opened in binary mode does. For example:

#include <sourcemeta/core/io.h>
#include <sstream>
#include <cassert>
 
std::istringstream stream{"foobar"};
const auto start{stream.tellg()};
sourcemeta::core::resume_stream(stream, start, 3);
assert(stream.peek() == 'b');

strip_path_prefix()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::strip_path_prefix	(	const std::filesystem::path &	path,
		const std::filesystem::path &	prefix ) -> std::filesystem::path

Return the portion of a path that follows a given prefix, or the path unchanged if it does not lie under the prefix. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
assert(sourcemeta::core::strip_path_prefix("/foo/bar/baz", "/foo") ==
"bar/baz");

weakly_canonical()

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::weakly_canonical

(

const std::filesystem::path &

path

)

-> std::filesystem::path

A safe variant of std::filesystem::weakly_canonical that takes into account platform-specific oddities like FIFO on GNU/Linux, always resolving relative paths against the current working directory. For example:

#include <sourcemeta/core/io.h>
#include <cassert>
 
const auto output{sourcemeta::core::weakly_canonical("/tmp/../foo.json")};
assert(output == "/foo.json");

write_file() [1/3]

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::write_file	(	const std::filesystem::path &	path,
		const std::function< void(std::ostream &)> &	writer ) -> void

Callback variant of write_file. For example:

#include <sourcemeta/core/io.h>
#include <sourcemeta/core/json.h>
 
sourcemeta::core::write_file("/tmp/foo.json",
    [&](std::ostream &stream) {
      sourcemeta::core::prettify(document, stream);
      stream << "\n";
    });

write_file() [2/3]

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::write_file	(	const std::filesystem::path &	path,
		const std::span< const std::byte >	contents ) -> void

Non-atomically write a byte span to path. For example:

#include <sourcemeta/core/io.h>
#include <array>
 
constexpr std::array<std::byte, 3> bytes{
    std::byte{0x41}, std::byte{0x42}, std::byte{0x43}};
sourcemeta::core::write_file("/tmp/foo.bin", std::span{bytes});

write_file() [3/3]

SOURCEMETA_CORE_IO_EXPORT auto sourcemeta::core::write_file	(	const std::filesystem::path &	path,
		const std::string_view	contents ) -> void

Non-atomically write contents to path. For example:

#include <sourcemeta/core/io.h>
 
sourcemeta::core::write_file("/tmp/foo.json", "{\"a\":1}");