__vic's C++ library (Windows) v1.0 [Draft]

1Introduction

1.1Why this library was created?

This library contains the features I'm missing in the Standard C++ library. It's a kind of my personal Boost.

Additionally, it's an abstraction layer that hides implementation details, quirks and idiosyncrasies of OS'es, compilers and the standard library implementations.

1.2General structure and usage

The topmost structural units of the library are headers and the library file (or archive) - lib__vic.a or __vic.lib. Usually the library file has some suffix like lib__vic14.a. All the headers are located in the __vic/ subdirectory. One should include them like this:

#include <__vic/header.h>

Where header.h is a name of the desired header.

Almost all the code is placed within __vic namespace, including other namespaces.

During program linking, the library file must be given to the linker. Example:

$ g++ -std=c++14 prog.cpp -l__vic14

The library can be built using one of the ISO C++ standards: C++98, C++11, C++14, C++17, C++20 or C++23. The standard suffix is used as a suffix for the library file (archive).

Some features require a specific minimal standard version to be available, e.g. many of them require at least C++11. These features are marked with [C++11] badge that means "C++11 or later".

Some features are available only in particular standard mode and not available otherwise. Such features are marked with [C++98 only] badge.

Detailed description of the library components is provided in the subsequent chapters. Descriptions are grouped by headers. C++23 language syntax is mainly used as a more complete and expressive one.

2Library components reference

2.1__vic/defs.h

Misc. fundamental definitions.

2.1.1nullptr [C++98 only]

Null pointer literal. Can be used instead of NULL or 0. In ISO C++ 98 mode defined as

const int nullptr = 0;

This definition allows to write C++11-style code using C++98 standard.

It is one of the few global definitions inroduced by the library. Definition can be prevented by definition __VIC_NO_NULLPTR_DEF macro before inclusion.

int *p = nullptr;
pthread_create(&tid, nullptr, thread_func, nullptr);

2.1.2noexcept [C++98 only]

A macro in C++98 mode, synonym for throw(). In other standard modes the definition is absent.

2.1.3array_size()

template<class T, size_t N>
constexpr size_t array_size(T (&array)[N]);

Returns number of elements in the array. Can be used as a compile-time expression.

int m[] = { 1, 2, 3, 5, 7 };

size_t n = __vic::array_size(m); // n == 5

int *dup = new int[n];

2.1.4non_copyable

class non_copyable
{
    non_copyable(const non_copyable &) = delete;
    non_copyable &operator=(const non_copyable &) = delete;
protected:
    non_copyable() = default;
};

Inheriting of this class suppresses generation of copy constructor and copy assignment. Same as boost::noncopyable.

class C : private __vic::non_copyable
{
};

C c1;
C c2 = c1; // Error! Non-copyable object

2.1.5non_heap_allocatable

class non_heap_allocatable
{
    void *operator new(std::size_t ) = delete;
    void *operator new(std::size_t , const std::nothrow_t & ) = delete;
    void *operator new[](std::size_t ) = delete;
    void *operator new[](std::size_t , const std::nothrow_t & ) = delete;
protected:
    non_heap_allocatable() = default;
};

Inheriting of this class prevents creation of the class object on a free store using operator new.

class C : private __vic::non_heap_allocatable
{
};

C c; // Ok. Allocation on stack
C *p = new C; // Error! Attempt to allocate on heap

2.1.6std::move(), std::forward(), std::swap() [C++11]

The header always includes this utilities in C++11 mode.

2.1.7__VIC_SWAP_HEADER

A macro for #include. Expands to the header name that contains std::swap() definition, dependig on the used language standard.

#include __VIC_SWAP_HEADER

2.1.8Platform-dependent macros

The library provides set of compiler-independent macros that help to determine the target platform and some platform-specific traits by checking macro presence using #ifdef.

List of hardware platforms (processors):

• __VIC_X86__ - Intel x86 (IA32)
• __VIC_X64__ - x64 aka AMD 64
• __VIC_IA64__ - Intel IA64
• __VIC_POWERPC__ - PowerPC

Other macros:

• __VIC_STRICT_RAM_ALIGNMENT__ - attempt to read unaligned data will cause bus error

2.2__vic/algorithm.h

Generic algorithms.

2.2.1skip_if_front()

template<
    std::forward_iterator Iter,
    std::predicate<std::iter_value_t<Iter>> Pred
>
Iter skip_if_front(Iter begin, Iter end, Pred pred);

Skips all leading elements that match the given predicate and returns new begin iterator.

2.2.2skip_if_back()

template<
    std::bidirectional_iterator Iter,
    std::predicate<std::iter_value_t<Iter>> Pred
>
Iter skip_if_back(Iter begin, Iter end, Pred pred);

Skips all trailing elements that match the given predicate and returns new end iterator.

2.3__vic/ascii.h

Fast, compact and locale-independent tools for ASCII-characters processing. All the tools are located within __vic::ascii namespace.

2.3.1ascii::is-functions

namespace ascii {

constexpr bool isdigit(char c);
constexpr bool isxdigit(char c);
constexpr bool islower(char c);
constexpr bool isupper(char c);
constexpr bool isalpha(char c);
constexpr bool isalnum(char c);
constexpr bool isspace(char c);
constexpr bool isblank(char c);
constexpr bool isprint(char c);
constexpr bool isgraph(char c);
constexpr bool ispunct(char c);
constexpr bool iscntrl(char c);
constexpr bool isascii(char c);

}

Counterparts of the corresponding <cctype> functions.

2.3.2ascii::todigit()

constexpr char ascii::todigit(int d);

Converts integer value from 0 to 9 to the decimal digit. The result is undefined if the input value goes beyond the range.

2.3.3ascii::toxdigit_upper(), ascii::toxdigit_lower()

namespace ascii {

constexpr char toxdigit_upper(int d);
constexpr char toxdigit_lower(int d);

}

Converts integer value from 0 to 15 to the hexadecimal digit. The first one uses upper case for A-F, the latter - lower. The result is undefined if the input value goes beyond the range.

2.3.4ascii::digit_to_number()

constexpr int ascii::digit_to_number(char d);

Converts the given decimal digit to the number if ascii::isdigit(d). -1 is returned otherwise.

2.3.5ascii::xdigit_to_number()

constexpr int ascii::xdigit_to_number(char d);

Converts the given hexadecimal digit to the number if ascii::isxdigit(d). -1 is returned otherwise.

2.3.6ascii::tolower(char), ascii::toupper(char)

namespace ascii {

constexpr char tolower(char c);
constexpr char toupper(char c);
constexpr char upper_to_lower(char upper);
constexpr char lower_to_upper(char lower);

}

constexpr char tolower(char c)

constexpr char toupper(char c)

constexpr char upper_to_lower(char upper)

constexpr char lower_to_upper(char lower)

2.3.7ascii::equal_icase(char,char)

constexpr bool ascii::equal_icase(char ch1, char ch2);

Checks equality of the two ASCII-characters ignoring the case.

2.4__vic/ascii_string.h

ASCII-strings processing tools.

2.4.1ascii::tolower()

namespace ascii {

char *tolower(char *str);
std::string &tolower(std::string &str);

}

Translates all Latin capital letters of str to the small ones. Returns str. C-string must not be nullptr!

2.4.2ascii::toupper()

namespace ascii {

char *toupper(char *str);
std::string &toupper(std::string &str);

}

Translates all Latin small letters of str to the capital ones. Returns str. C-string must not be nullptr!

2.4.3ascii::equal_icase()

namespace ascii {

bool equal_icase(const char *s1, const char *s2);
bool equal_icase(const char *s1, size_t s1_len,
                 const char *s2, size_t s2_len);

#if __cpp_lib_string_view // C++17

bool equal_icase(std::string_view s1, std::string_view s2);

#else // until C++17

bool equal_icase(const std::string &s1, const std::string &s2);
bool equal_icase(const std::string &s1, const char *s2);
bool equal_icase(const char *s1, const std::string &s2);

#endif
}

Checks equality of two ASCII-strings ignoring the case. The pointers must not be nullptr!

2.5__vic/base16.h

Base16 encoder and decoder.

2.5.1base16

A class used as a namespace. Contains only types, constants and static functions. No objects of this class are supposed to be created.

2.5.2base16::bad_format

struct base16::bad_format : public std::exception {};

Abstract base exception class.

2.5.3base16::bad_digit

struct base16::bad_digit : public base16::bad_format
{
    const char *what() const noexcept;
};

Exception class thrown by base16::decode() when the input sequence contains character that is not a valid HEX digit.

2.5.4base16::bad_length

struct base16::bad_length : public base16::bad_format
{
    const char *what() const noexcept;
};

Exception class thrown by base16::decode() when the input sequence length is odd.

2.5.5base16::status

enum class base16::status
{
    ok,
    invalid_length,
    invalid_digit
};
using base16::status_t = base16::status; // for C++98

Input sequence parsing outcome status codes returned by base16::try_decode().

2.5.6base16::encode_upper()

// Bytes -> Text
template<class ByteSReader, class CharSWriter>
void base16::encode_upper(ByteSReader reader, CharSWriter writer);

Encodes bytes from reader and writes the resulting characters to writer. Upper case is used for hexadecimal digits.

ByteSReader has to model sreader<unsigned char> concept. See S-readers.

CharSWriter has to model swriter<char> concept. See S-writers.

#include<__vic/sreaders/string.h>
#include<__vic/swriters/string.h>

using bytes = std::string;
using bytes_sreader = __vic::string_sreader;

std::string encode_base16(const bytes &s)
{
    std::string res;
    res.reserve(s.length() * 2);
    __vic::base16::encode_upper(bytes_sreader(s), __vic::string_swriter(res));
    return res;
}

2.5.7base16::encode_lower()

// Bytes -> Text
template<class ByteSReader, class CharSWriter>
void base16::encode_lower(ByteSReader reader, CharSWriter writer);

Same as base16::encode_upper() but lower case is used for hexadecimal digits.

2.5.8base16::encode_byte_lower()

// Byte -> Text
template<class CharSWriter>
void base16::encode_byte_lower(unsigned char byte, CharSWriter writer);

Same as base16::encode_lower() but encodes only single byte.

2.5.9base16::encode_byte_upper()

// Byte -> Text
template<class CharSWriter>
void base16::encode_byte_upper(unsigned char byte, CharSWriter writer);

Same as base16::encode_upper() but encodes only single byte.

2.5.10base16::decode()

// Text -> Bytes
template<class CharSReader, class ByteSWriter>
void base16::decode(CharSReader reader, ByteSWriter writer);

Decodes characters from reader and writes the resulting bytes to writer. Exception derived from base16::bad_format is thrown if the input sequence has invalid Base16 format.

CharSReader has to model sreader<char> concept. See S-readers.

ByteSWriter has to model swriter<unsigned char> concept. See S-writers.

#include<__vic/sreaders/string.h>
#include<__vic/swriters/string.h>

using bytes = std::string;
using bytes_swriter = __vic::string_swriter;

bytes decode_base16(const std::string &s)
{
    bytes res;
    res.reserve(s.length() / 2);
    __vic::base16::decode(__vic::string_sreader(s), bytes_swriter(res));
    return res;
}

2.5.11base16::try_decode()

// Text -> Bytes
template<class CharSReader, class ByteSWriter>
base16::status_t base16::try_decode(CharSReader reader, ByteSWriter writer);

Same as base16::decode() but returns base16::status different from base16::status::ok in case of invalid input sequence instead of throwing exception.

2.6__vic/base64.h

Base64 encoder and decoder.

2.6.1base64

A class used as a namespace. Contains only types, constants and static functions. No objects of this class are supposed to be created.

2.6.2base64::bad_format

struct base64::bad_format : public std::exception {};

Abstract base exception class.

2.6.3base64::bad_digit

struct base64::bad_digit : public base64::bad_format
{
    const char *what() const noexcept;
};

Exception class thrown by base64::decode() when the input sequence contains character that is not a valid Base64 digit.

2.6.4base64::bad_length

struct base64::bad_length : public base64::bad_format
{
    const char *what() const noexcept;
};

Exception class thrown by base64::decode() when the input sequence length is not a multiple of 4.

2.6.5base64::status

enum class base64::status
{
    ok,
    invalid_length,
    invalid_digit
};
using base64::status_t = base64::status; // for C++98

Input sequence parsing outcome status codes returned by base64::try_decode().

2.6.6base64::encode()

// Bytes -> Text
template<class ByteSReader, class CharSWriter>
void base64::encode(ByteSReader reader, CharSWriter writer);

Encodes bytes from reader and writes the resulting characters to writer.

ByteSReader has to model sreader<unsigned char> concept. See S-readers.

CharSWriter has to model swriter<char> concept. See S-writers.

#include<__vic/sreaders/string.h>
#include<__vic/swriters/string.h>

using bytes = std::string;
using bytes_sreader = __vic::string_sreader;

std::string encode_base64(const bytes &s)
{
    std::string res;
    res.reserve(__vic::base64::encoded_length(s.length()));
    __vic::base64::encode(bytes_sreader(s), __vic::string_swriter(res));
    return res;
}

2.6.7base64::decode()

// Text -> Bytes
template<class CharSReader, class ByteSWriter>
void base64::decode(CharSReader reader, ByteSWriter writer);

Decodes characters form reader and writes the resulting bytes to writer. Exception derived from base64::bad_format is thrown if the input sequence has invalid Base64 format.

CharSReader has to model sreader<char> concept. See S-readers.

ByteSWriter has to model swriter<unsigned char> concept. See S-writers.

#include<__vic/sreaders/string.h>
#include<__vic/swriters/string.h>

using bytes = std::string;
using bytes_swriter = __vic::string_swriter;

bytes decode_base64(const std::string &s)
{
    bytes res;
    res.reserve(__vic::base64::max_decoded_length(s.length()));
    __vic::base64::decode(__vic::string_sreader(s), bytes_swriter(res));
    return res;
}

2.6.8base64::try_decode()

// Text -> Bytes
template<class CharSReader, class ByteSWriter>
base64::status_t base64::try_decode(CharSReader reader, ByteSWriter writer);

Same as base64::decode() but returns base64::status different from base64::status::ok in case of invalid input sequence instead of throwing exception.

2.6.9base64::encoded_length()

constexpr size_t base64::encoded_length(size_t orig_len);

Calculates the length of encoded sequence of characters using the original length of the bytes sequence.

2.6.10base64::max_decoded_length()

constexpr size_t base64::max_decoded_length(size_t orig_len);

Estimates the maximum length of decoded sequence of bytes using the original length of the characters sequence. The actual value depends on trailing '=' in the encoded value.

2.7__vic/bin_file.h

2.7.1bin_file

class bin_file : private non_copyable
{
public:
    enum in_t { in };
    enum out_t { out };
    enum append_t { append };

    bin_file();
    bin_file(const char *fname, in_t);
    bin_file(const char *fname, out_t);
    bin_file(const char *fname, append_t);
    bin_file(const wchar_t *fname, in_t);
    bin_file(const wchar_t *fname, out_t);
    bin_file(const wchar_t *fname, append_t);
    ~bin_file();

    // BEGIN C++11
    bin_file(bin_file &&o) noexcept;
    bin_file &operator=(bin_file &&o) noexcept;
    // END C++11

    bool open_in(const char *fname);
    bool open_out(const char *fname);
    bool open_append(const char *fname);

    bool open_in(const wchar_t *fname);
    bool open_out(const wchar_t *fname);
    bool open_append(const wchar_t *fname);

    size_t read_max(void *buf, size_t n);
    size_t read_some(void *buf, size_t n);

    void write_all(const void *buf, size_t n);

    bool is_open() const;
    void close();
    bool close_nt() noexcept;

    void swap(bin_file &o) noexcept;

    [[noreturn]] void throw_last_error(const char *msg);
    void throw_if_closed(const char *msg);
};

Unbuffered binary file. OS-independent wrapper for low-level system API.

Following open modes are available:

• in - open existing file for reading;
• out - create new file for writing, overwrite if exists;
• append - open existing file for appending (writing at end of file), create if does not exist.

enum in_t { in }

enum out_t { out }

enum append_t { append }

bin_file()

bin_file(const char *fname, in_t)

bin_file(const char *fname, out_t)

bin_file(const char *fname, append_t)

bin_file(const wchar_t *fname, in_t)

bin_file(const wchar_t *fname, out_t)

bin_file(const wchar_t *fname, append_t)

~bin_file()

bin_file(bin_file &&o) noexcept [C++11]

bin_file &operator=(bin_file &&o) noexcept [C++11]

bool open_in(const char *fname)

bool open_out(const char *fname)

bool open_append(const char *fname)

bool open_in(const wchar_t *fname)

bool open_out(const wchar_t *fname)

bool open_append(const wchar_t *fname)

bool is_open() const

size_t read_max(void *buf, size_t n)

size_t read_some(void *buf, size_t n)

void write_all(const void *buf, size_t n)

void close()

bool close_nt() noexcept

void swap(bin_file &o) noexcept

[[noreturn]] void throw_last_error(const char *msg)

void throw_if_closed(const char *msg)

// Copy file
__vic::bin_file in("file", __vic::bin_file::in);
in.throw_if_closed("Cannot open file")
__vic::bin_file out("file.copy", __vic::bin_file::out);
out.throw_if_closed("Cannot create file")

char buf[512];
while(size_t n = in.read_some(buf, sizeof buf))
    out.write_all(buf, n);

out.close();
// in will be closed by destructor

2.8__vic/bits.h

Bits and bytes manipulation tools.

2.8.1lo_nibble(), hi_nibble()

constexpr uint8_t lo_nibble(uint8_t byte);
constexpr uint8_t hi_nibble(uint8_t byte);

Return the value of the low-order/high-order half-byte (tetrad), respectively.

2.8.2msb_ones(), lsb_ones()

template<class T> constexpr T lsb_ones(unsigned bits_num);
template<class T> constexpr T msb_ones(unsigned bits_num);

Return the value of the type T with all least/most significant bits_num bits filled with 1, respectively. All other bits are set to 0.

2.8.3get_lsbs()

template<class T> constexpr T get_lsbs(T v, unsigned bits_num);

Returns bits_num least significant bits of v. In other words, zeroes all but bits_num least significant bits.

2.8.4ord()

constexpr int ord(char ch);

Returns the character code from 0 to 255.

2.8.5popcount()

unsigned popcount(unsigned v);
unsigned popcount(unsigned long v);
unsigned popcount(unsigned long long v);
unsigned popcount(unsigned short v);
unsigned popcount(unsigned char v);

Returns the number of one bits in the given value.

2.8.6msb_position()

unsigned msb_position(unsigned v)
unsigned msb_position(unsigned long v);
unsigned msb_position(unsigned long long v);
unsigned msb_position(unsigned short v);
unsigned msb_position(unsigned char v);

Returns the position of the most significant 1-bit. The result is unspecified if v == 0.

2.8.7ispow2()

template<class UInt>
bool ispow2(UInt n);

Returns true if n is an integral power of 2.

2.8.8ceil2()

template<class UInt>
UInt ceil2(UInt n);

Returns the minimal value m such that ispow2(m) && m >= n. If m is not representable as a value of type UInt, the result is an unspecified value.

2.8.9floor2()

template<class UInt>
UInt floor2(UInt n);

If n != 0 returns the maximal value m such that ispow2(m) && m <= n. Otherwise 0 is returned.

2.8.10ceil_log2()

template<class UInt>
unsigned ceil_log2(UInt n);

Returns ceil(log2(n)) if n != 0 or 0 otherwise.

2.8.11floor_log2()

template<class UInt>
unsigned floor_log2(UInt n);

Returns floor(log2(n)) if n != 0 or 0 otherwise.

2.8.12rotl(), rotr()

unsigned long long rotl(unsigned long long v, int shift);
unsigned long      rotl(unsigned long v, int shift);
unsigned           rotl(unsigned v, int shift);
unsigned short     rotl(unsigned short v, int shift);
unsigned char      rotl(unsigned char v, int shift);

unsigned long long rotr(unsigned long long v, int shift);
unsigned long      rotr(unsigned long v, int shift);
unsigned           rotr(unsigned v, int shift);
unsigned short     rotr(unsigned short v, int shift);
unsigned char      rotr(unsigned char v, int shift);

The functions perform circular left (rotl) or right (rotr) bitwise shift (rotation).

2.8.13swapped_nibbles()

constexpr uint8_t swapped_nibbles(uint8_t b);

Swaps a low-order half-byte with a high-order one and returns the value.

2.9__vic/bounded_vector.h

2.9.1bounded_vector

template<class T>
class bounded_vector : private non_copyable
{
public:
    using value_type     = T;
    using iterator       = <implementation-defined>;
    using const_iterator = <implementation-defined>;

    bounded_vector();
    explicit bounded_vector(size_t max_size);
    ~bounded_vector();

    // BEGIN C++11
    bounded_vector(bounded_vector &&o) noexcept;
    bounded_vector &operator=(bounded_vector &&o) noexcept;
    template<class... Args> T &emplace_back(Args &&... args)
    // END C++11

    // size in objects
    size_t size() const;
    size_t capacity() const;
    bool full() const;
    bool empty() const;

    void recreate(size_t new_max_size, bool size_exact = false);
    void *alloc(); // returns pointer to memory for object allocation
    void push_allocated(); // adds last allocated object to the container
    void pop_back();
    void clear();
    void swap(bounded_vector &o) noexcept;

    // element access
    T &operator[](size_t i);
    iterator begin();
    iterator end();
    T &front();
    T &back();

    const T &operator[](size_t i) const;
    const_iterator begin() const;
    const_iterator end() const;
    const_iterator cbegin() const;
    const_iterator cend() const;
    const T &front() const;
    const T &back() const;
};
template<class T>
void swap(bounded_vector<T> &o1, bounded_vector<T> &o2) noexcept;

The standard containers in C++98 don't allow to store non-copiable elements. Even in C++11 elements of containers like std::vector have to be at least noexcept movable. This class solves the problem. It is a dynamic array for non-copyable objects or just std::vector without autogrowing capacity().

Without emplace_back() it is impossible to create arbitrary new object right in the container's memory. C++98 lacks forwarding references so it is ear impossible to pass arbitrary parameters to the element's constructor. bounded_vector overcomes this problem using the following mechanism. The new element is created using several phases:

1. Requesting memory for the new element in the container - alloc(),
2. Creation of the object using placement new - new(ptr) type(...),
3. Fixation of the newly created object in the container - push_allocated().

See the example at the end of the article.

Maximum capacity is specified on creation of the container. Later it can be changed but all the elements has to be destroyed before. In other words, the container can be recreated (recreate() function).

When available, emplace_back() must be used for elements creation. If not, the unsafe interface described above must be used with care. It is very ugly and error-prone but solves the task. After the element is created in the container, you operate with it almost as easy as with any other copyable object in the standard container. Anyway, it is more efficient and convenient to use in general than alternative approaches like creating the objects on the free store and placing only pointers to the container, even if we have std::unique_ptr to manage lifetime of the objects.

Fundamental differences from std::vector:

1. Elements don't have to be copyable or movable (std::vector requires at least noexcept-movability);
2. Elements have stable addresses after addition of new element;
3. emplace_back() has precondition (!full()).

typename value_type

typename iterator

typename const_iterator

bounded_vector()

explicit bounded_vector(size_t max_size)

~bounded_vector()

bounded_vector(bounded_vector &&o) noexcept [C++11]

bounded_vector &operator=(bounded_vector &&o) noexcept [C++11]

size_t size() const

size_t capacity() const

bool empty() const

bool full() const

void recreate(size_t new_max_size, bool size_exact = false)

void *alloc()

void push_allocated()

template<class... Args> T &emplace_back(Args &&... args) [C++11]

void pop_back()

void clear()

void swap(bounded_vector &o)

template<class T> void swap(bounded_vector<T> &o1, bounded_vector<T> &o2) noexcept

T &operator[](size_t i)

const T &operator[](size_t i) const

T &front()

const T &front() const

T &back()

const T &back() const

iterator begin()

const_iterator begin() const

const_iterator cbegin() const

iterator end()

const_iterator end() const

const_iterator cend() const

// Creating vector for 2 objects of class C
__vic::bounded_vector<C> v(2);

// Creating new object in C++98 mode:
new(v.alloc()) C(...); // Request memory and construct the object
v.push_allocated();    // Fixate successfully created object in the container

// Creating new object in C++11 mode:
v.emplace_back(...);

2.10__vic/date_time.h

Date and time utilies.

2.10.1is_leap_year()

constexpr bool is_leap_year(int year);

Determines if the year is a leap year according to Gregorian calendar.

2.10.2days_in_month()

int days_in_month(int month, int year);

Returns number of days in the month. Month is a number from 1 to 12. The second parameter is used only if the month is 2 (february), otherwise is just ignored.

2.10.3days_between_years()

long days_between_years(unsigned year1, unsigned year2);

Returns the difference in days between the beginning of the 2nd year and the beginning of the 1st year.

2.10.4invalid_date

class invalid_date; // : public std::exception

The exception thrown when the value of the date or time element is invalid.

2.10.5validate_date(), validate_time(), validate_date_time()

void validate_date(int yy, int mm, int dd);
void validate_time(int hh, int mi, int ss);
void validate_date_time(int yy, int mm, int dd, int hh, int mi, int ss);

Checks if the date/time value is valid. Following constraints are checked:

• yy (year) - cannot be 0,
• mm (month) - 1..12,
• dd (day of the month) - 1..{28..31}, depending on the month,
• hh (hour) - 0..23,
• mi (minute) - 0..59,
• ss (second) - 0..59.

invalid_date is thrown in case of the constraint violation.

2.11__vic/endian.h

Byte order-related utilities.

2.11.1endianness

namespace endian {
enum endianness
{
    unknown = 0,
    little  = 1234,
    big     = 4321,
    pdp     = 3412,
    native  = <one-of-the-above>
};
} // namespace

using endian::endianness;

Byte order constants. endian::native is set equal to one of the constants and represents the byte order used on the current platform (like __BYTE_ORDER__ macro on UNIX-like platforms). The values are supposed to be used for template specializations or for compile-time checks (e.g. in static_assert).

template<__vic::endianness > struct some_algo; // not implemented

// Implementation for little-endian
template<> struct some_algo<__vic::endian::little>
{
    static void doit() { ... }
};
// Implementation for big-endian
template<> struct some_algo<__vic::endian::big>
{
    static void doit() { ... }
};

// Automatically choose an appropriate implementation for the used platform
some_algo<__vic::endian::native>::doit();

static_assert(__vic::endian::native == __vic::endian:little,
    "Litte-endian is expected");

2.11.2endian::from_...()

template<class T> [[nodiscard]] constexpr T endian::from_little(T v);
template<class T> [[nodiscard]] constexpr T endian::from_big(T v);

Return a value represented in native byte order converted from litte/big endian if appropriate.

T can be any integral type or enum with size up to sizeof(long long).

uint16_t v;
read_bytes(&v, 2); // serialized as big endian
std::cout << "The value is " << __vic::endian::from_big(v) << '\n';

2.11.3endian::to_...()

template<class T> [[nodiscard]] constexpr T endian::to_little(T v);
template<class T> [[nodiscard]] constexpr T endian::to_big(T v);

Return a value represented in litte/big endian byte order.

T can be any integral type or enum with size up to sizeof(long long).

uint16_t v = __vic::endian::to_big(...);
write_bytes(&v, 2); // serialize as big endian

2.11.4swab16(), swab32(), swab64()

[[nodiscard]] constexpr uint16_t swab16(uint16_t v);
[[nodiscard]] constexpr uint32_t swab32(uint32_t v);
[[nodiscard]] constexpr uint64_t swab64(uint64_t v);

Fast utilities to reverse byte order (usually implemented using compiler-specific intrinsics).

static_assert(__vic::swab32(0x01020304) == 0x04030201);

2.12__vic/error.h

Error handling tools.

2.12.1exception

class exception : public std::exception
{
public:
    exception();
    explicit exception(const char *message);
    const char *what() const noexcept;
protected:
    void set_message(const char *message);
};

Small extension of std::exception - the object carries message specified in the constructor, what() returns this message. Can be used either as a base or a concrete exception class. Does not use/depend on std::string as opposed to std::logic_error and std::runtime_error. You also don't have to decide which one of them you should use in the particular case.

exception()

explicit exception(const char *message)

const char *what() const noexcept

void set_message(const char *message)

struct custom_exception : public __vic::exception
{
    explicit custom_exception(const char *msg) : __vic::exception(msg) {}
};

throw custom_exception("Error condition description");

2.12.2libc_error

class libc_error : public std::exception
{
public:
    explicit libc_error(int err_no = errno);
    explicit libc_error(const char *prompt, int err_no = errno);

    const char *what() const noexcept;
    int code() const;
    int get_errno() const;
};

This class is an easy and straightforward replacement of the standard error handling machinery used in the C-world - errno, with exceptions. The class is also suitable for usage in the multithread environment instead of not always reentrant call std::strerror().

Below you can see typical C code:

// C:

int fd;
if((fd = open("qqqq", O_RDONLY)) == -1)
{
    perror("open");
    if(errno == ENOENT) exit(1);
}

If the file is not found, the message like this

open: No such file or directory

is printed to stderr and the program exits with the status 1.

What issues are inherent in this code? Firstly, not every program has stderr, so a library function is not allowed to print error messages there. Secondly, the value of the global variable errno can be rewritten by any subsequent call unless the value is saved explicitly right after the call. Thirdly, the decision about termination of the process can only be made by the application. An ordinary library function is not allowed to do this. Fourthly, in general case C++ program cannot call std::exit(), because destructors of the live objects allocated on the stack won't be called, and program's logic can be corrupted.

The example adapted for C++ using our class:

// C++:

try
{
    int fd = open("qqqq", O_RDONLY);
    if(fd == -1) throw __vic::libc_error("open");
    // or just
    // if(fd == -1) throw __vic::libc_error();
}
catch(const __vic::libc_error &ex)
{
    std::cerr << ex.what() << '\n';
    if(ex.code() == ENOENT) return 1;
}

As it can be seen, the function handles erroneous situation correctly and reports it to the caller. Afterwards the caller can handle the error appropriately. In the elementary case it acts as the former C-program: prints the message to the standard error output stream and terminates. Moreover, error code is now saved in the exception and cannot be rewritten by accident.

explicit libc_error(int err_no = errno)

explicit libc_error(const char *prompt, int err_no = errno)

const char *what() const noexcept

int code() const

int get_errno() const

2.13__vic/fs.h

Filesystem utilities.

2.13.1path_exists(), file_exists(), dir_exists()

bool path_exists(const char *path);
bool path_exists(const wchar_t *path);
bool path_exists(const std::string &path);
bool path_exists(const std::wstring &path);

bool file_exists(const char *path);
bool file_exists(const wchar_t *path);
bool file_exists(const std::string &path);
bool file_exists(const std::wstring &path);

bool dir_exists(const char *path);
bool dir_exists(const wchar_t *path);
bool dir_exists(const std::string &path);
bool dir_exists(const std::wstring &path);

path_exists() checks whether the path exists in the system. Second and third functions additionally check, besides the presence, if the path references to a regular file or to a directory, respectively.

2.13.2mkdir(), mkdir_if_absent()

void mkdir(const char *path);
void mkdir(const wchar_t *path);
void mkdir(const std::string &path);
void mkdir(const std::wstring &path);

bool mkdir_if_absent(const char *path);
bool mkdir_if_absent(const wchar_t *path);
bool mkdir_if_absent(const std::string &path);
bool mkdir_if_absent(const std::wstring &path);

Creates a directory. Throws exception in case of failure. mkdir_if_absent() returns false instead of throwing if the directory already exists.

2.13.3rmdir(), rmdir_if_exists()

void rmdir(const char *path);
void rmdir(const wchar_t *path);
void rmdir(const std::string &path);
void rmdir(const std::wstring &path);

bool rmdir_if_exists(const char *path);
bool rmdir_if_exists(const wchar_t *path);
bool rmdir_if_exists(const std::string &path);
bool rmdir_if_exists(const std::wstring &path);

Deletes an empty directory. Throws exception in case of failure. rmdir_if_exists() returns false instead of throwing if the directory doesn't exist.

2.13.4get_current_dir()

std::string get_current_dir();

Returns current working directory.

2.13.5remove_file(), remove_file_if_exists(), remove_file_nt()

void remove_file(const char *path);
void remove_file(const wchar_t *path);
void remove_file(const std::string &path);
void remove_file(const std::wstring &path);

bool remove_file_if_exists(const char *path);
bool remove_file_if_exists(const wchar_t *path);
bool remove_file_if_exists(const std::string &path);
bool remove_file_if_exists(const std::wstring &path);

bool remove_file_nt(const char *path) noexcept;
bool remove_file_nt(const wchar_t *path) noexcept;
bool remove_file_nt(const std::string &path) noexcept;
bool remove_file_nt(const std::wstring &path) noexcept;

Deletes the file. Throws exception in case of failure.

remove_file_if_exists() returns false instead of throwing if the file doesn't exist.

remove_file_nt() doestn't throw any exceptions at all, false is returned in case of failure.

2.13.6copy_file(), copy_file_if_exists(), copy_file_replace(), copy_file_replace_if_exists()

void copy_file(
    const char *src_path, const char *dest_path, bool replace = false);
void copy_file(
    const wchar_t *src_path, const wchar_t *dest_path, bool replace = false);
void copy_file(
    const std::string &src_path, const std::string &dest_path,
    bool replace = false);
void copy_file(
    const std::wstring &src_path, const std::wstring &dest_path,
    bool replace = false);

bool copy_file_if_exists(
    const char *src_path, const char *dest_path, bool replace = false);
bool copy_file_if_exists(
    const wchar_t *src_path, const wchar_t *dest_path, bool replace = false);
bool copy_file_if_exists(
    const std::string &src_path, const std::string &dest_path,
    bool replace = false);
bool copy_file_if_exists(
    const std::wstring &src_path, const std::wstring &dest_path,
    bool replace = false);

void copy_file_replace(
    const char *src_path, const char *dest_path);
void copy_file_replace(
    const wchar_t *src_path, const wchar_t *dest_path);
void copy_file_replace(
    const std::string &src_path, const std::string &dest_path);
void copy_file_replace(
    const std::wstring &src_path, const std::wstring &dest_path);

bool copy_file_replace_if_exists(
    const char *src_path, const char *dest_path);
bool copy_file_replace_if_exists(
    const wchar_t *src_path, const wchar_t *dest_path);
bool copy_file_replace_if_exists(
    const std::string &src_path, const std::string &dest_path);
bool copy_file_replace_if_exists(
    const std::wstring &src_path, const std::wstring &dest_path);

Creates a new file dest_path which is a copy of a file src_path. If the new file exists and replace == false, the functions fail.

copy_file_if_exists() returns false instead of throwing if src_path doesn't exist.

copy_file_replace() is the same as copy_file(..., true).

copy_file_replace_if_exists() is the same as copy_file_if_exists(..., true).

2.13.7move_file(), move_file_if_exists(), move_file_replace(), move_file_replace_if_exists()

void move_file(const char *src_path, const char *dest_path);
void move_file(const wchar_t *src_path, const wchar_t *dest_path);
void move_file(const std::string &src_path, const std::string &dest_path);
void move_file(const std::wstring &src_path, const std::wstring &dest_path);

bool move_file_if_exists(const char *src_path, const char *dest_path);
bool move_file_if_exists(const wchar_t *src_path, const wchar_t *dest_path);
bool move_file_if_exists(
    const std::string &src_path, const std::string &dest_path);
bool move_file_if_exists(
    const std::wstring &src_path, const std::wstring &dest_path);

void move_file_replace(const char *src_path, const char *dest_path);
void move_file_replace(const wchar_t *src_path, const wchar_t *dest_path);
void move_file_replace(
    const std::string &src_path, const std::string &dest_path);
void move_file_replace(
    const std::wstring &src_path, const std::wstring &dest_path);

bool move_file_replace_if_exists(
    const char *src_path, const char *dest_path);
bool move_file_replace_if_exists(
    const wchar_t *src_path, const wchar_t *dest_path);
bool move_file_replace_if_exists(
    const std::string &src_path, const std::string &dest_path);
bool move_file_replace_if_exists(
    const std::wstring &src_path, const std::wstring &dest_path);

Moves a file src_path to new location specified by dest_path.

The functions with _replace suffix overwrite existing destination file if exists, others - fail in such case.

move_file_if_exists() returns false instead of throwing if src_path doesn't exist.

2.13.8rename_file(), rename_file_if_exists(), rename_file_replace(), rename_file_replace_if_exists()

void rename_file(const char *src_name, const char *dest_name);
void rename_file(const wchar_t *src_name, const wchar_t *dest_name);
void rename_file(const std::string &src_name, const std::string &dest_name);
void rename_file(const std::wstring &src_name, const std::wstring &dest_name);

bool rename_file_if_exists(const char *src_name, const char *dest_name);
bool rename_file_if_exists(const wchar_t *src_name, const wchar_t *dest_name);
bool rename_file_if_exists(
    const std::string &src_name, const std::string &dest_name);
bool rename_file_if_exists(
    const std::wstring &src_name, const std::wstring &dest_name);

void rename_file_replace(const char *src_name, const char *dest_name);
void rename_file_replace(const wchar_t *src_name, const wchar_t *dest_name);
void rename_file_replace(
    const std::string &src_name, const std::string &dest_name);
void rename_file_replace(
    const std::wstring &src_name, const std::wstring &dest_name);

bool rename_file_replace_if_exists(
    const char *src_name, const char *dest_name);
bool rename_file_replace_if_exists(
    const wchar_t *src_name, const wchar_t *dest_name);
bool rename_file_replace_if_exists(
    const std::string &src_name, const std::string &dest_name);
bool rename_file_replace_if_exists(
    const std::wstring &src_name, const std::wstring &dest_name);

Renames a file src_path to dest_path. The new path has to be located within the same physical filesystem.

As opposed to std::rename(), the functions without _replace suffix fail if dest_path exists.

rename_file_if_exists() returns false instead of throwing if src_path doesn't exist.

2.13.9file_size()

uintmax_t file_size(const char *path);
uintmax_t file_size(const wchar_t *path);
uintmax_t file_size(const std::string &path);
uintmax_t file_size(const std::wstring &path);

Returns file size in bytes.

2.14__vic/ip_addr.h

2.14.1ipv4_addr

class ipv4_addr : public ::in_addr
{
public:
    ipv4_addr() = default;
    constexpr ipv4_addr(::in_addr a);
    constexpr explicit ipv4_addr(::in_addr_t a);
    constexpr ipv4_addr(uint8_t a, uint8_t b, uint8_t c, uint8_t d);

    static constexpr ipv4_addr any();
    static constexpr ipv4_addr loopback();

    constexpr bool is_any() const;
    constexpr bool is_loopback() const;

    static bool parse(const char *begin, const char *end, ::in_addr &res);
#if __cpp_lib_string_view // C++17
    static bool parse(std::string_view s, ::in_addr &res);
#else // until C++17
    static bool parse(const std::string &s, ::in_addr &res)
    static bool parse(const char *s, ::in_addr &res);
#endif
};

constexpr ipv4_addr operator&(ipv4_addr a1, ipv4_addr a2);

constexpr bool operator==(ipv4_addr a1, ipv4_addr a2);
constexpr bool operator!=(ipv4_addr a1, ipv4_addr a2);
constexpr bool operator< (ipv4_addr a1, ipv4_addr a2);
constexpr bool operator> (ipv4_addr a1, ipv4_addr a2);
constexpr bool operator<=(ipv4_addr a1, ipv4_addr a2);
constexpr bool operator>=(ipv4_addr a1, ipv4_addr a2);

constexpr bool operator==(ipv4_addr a1, ::in_addr a2);
constexpr bool operator!=(ipv4_addr a1, ::in_addr a2);
constexpr bool operator< (ipv4_addr a1, ::in_addr a2);
constexpr bool operator> (ipv4_addr a1, ::in_addr a2);
constexpr bool operator<=(ipv4_addr a1, ::in_addr a2);
constexpr bool operator>=(ipv4_addr a1, ::in_addr a2);

constexpr bool operator==(::in_addr a1, ipv4_addr a2);
constexpr bool operator!=(::in_addr a1, ipv4_addr a2);
constexpr bool operator< (::in_addr a1, ipv4_addr a2);
constexpr bool operator> (::in_addr a1, ipv4_addr a2);
constexpr bool operator<=(::in_addr a1, ipv4_addr a2);
constexpr bool operator>=(::in_addr a1, ipv4_addr a2);

void to_text_append(::in_addr ip, std::string &res);

template<> struct std::hash<ipv4_addr>;

An IPv4 address. A handy C++-wrapper for ::in_addr.

ipv4_addr() = default

constexpr ipv4_addr(uint8_t a, uint8_t b, uint8_t c, uint8_t d)

constexpr ipv4_addr(::in_addr a)

constexpr explicit ipv4_addr(::in_addr_t a)

static constexpr ipv4_addr any()

static constexpr ipv4_addr loopback()

constexpr bool is_any() const

constexpr bool is_loopback() const

static bool parse(const char *begin, const char *end, ::in_addr &res)

static bool parse(std::string_view s, ::in_addr &res) [C++17]

static bool parse(const std::string &s, ::in_addr &res) [until C++17]

static bool parse(const char *s, ::in_addr &res) [until C++17]

constexpr ipv4_addr operator&(ipv4_addr a1, ipv4_addr a2)

constexpr bool operator==(ipv4_addr a1, ipv4_addr a2)

constexpr bool operator!=(ipv4_addr a1, ipv4_addr a2)

constexpr bool operator==(ipv4_addr a1, ::in_addr a2)

constexpr bool operator!=(ipv4_addr a1, ::in_addr a2)

constexpr bool operator==(::in_addr a1, ipv4_addr a2)

constexpr bool operator!=(::in_addr a1, ipv4_addr a2)

constexpr bool operator< (ipv4_addr a1, ipv4_addr a2)

constexpr bool operator> (ipv4_addr a1, ipv4_addr a2)

constexpr bool operator<=(ipv4_addr a1, ipv4_addr a2)

constexpr bool operator>=(ipv4_addr a1, ipv4_addr a2)

constexpr bool operator< (ipv4_addr a1, ::in_addr a2)

constexpr bool operator> (ipv4_addr a1, ::in_addr a2)

constexpr bool operator<=(ipv4_addr a1, ::in_addr a2)

constexpr bool operator>=(ipv4_addr a1, ::in_addr a2)

constexpr bool operator< (::in_addr a1, ipv4_addr a2)

constexpr bool operator> (::in_addr a1, ipv4_addr a2)

constexpr bool operator<=(::in_addr a1, ipv4_addr a2)

constexpr bool operator>=(::in_addr a1, ipv4_addr a2)

void to_text_append(::in_addr ip, std::string &res)

template<> struct std::hash<ipv4_addr>

http_connect(__vic::ipv4_addr{127,0,0,1}, 80);

std::string_view s = ..;
__vic::ipv4_addr ip;
if(__vic::ipv4_addr::parse(s, ip))
    log.info() << "Connecting to " << ip << "...";
else
    log.error("Bad IPv4 address format");

2.14.2ipv6_addr

class ipv6_addr : public ::in6_addr
{
public:
    ipv6_addr() = default;
    constexpr ipv6_addr(::in6_addr a);
    constexpr ipv6_addr(uint8_t a, uint8_t b, uint8_t c, uint8_t d,
                        uint8_t e, uint8_t f, uint8_t g, uint8_t h,
                        uint8_t i, uint8_t j, uint8_t k, uint8_t l,
                        uint8_t m, uint8_t n, uint8_t o, uint8_t p);
    constexpr ipv6_addr(uint16_t a, uint16_t b, uint16_t c, uint16_t d,
                        uint16_t e, uint16_t f, uint16_t g, uint16_t h)
    explicit ipv6_addr(const ::in_addr &ip4);

    static constexpr ipv6_addr any();
    static constexpr ipv6_addr loopback();

    bool is_any() const;
    bool is_loopback() const;
    bool is_ipv4_mapped() const;
    ipv4_addr to_ipv4() const;

    static bool parse(const char *begin, const char *end, ::in6_addr &res);
#if __cpp_lib_string_view
    static bool parse(std::string_view s, ::in6_addr &res);
#else
    static bool parse(const std::string &s, ::in6_addr &res);
    static bool parse(const char *s, ::in6_addr &res);
#endif
};

ipv6_addr operator&(const ipv6_addr &a1, const ipv6_addr &a2);

constexpr bool operator==(ipv6_addr a1, ipv6_addr a2);
constexpr bool operator!=(ipv6_addr a1, ipv6_addr a2);
constexpr bool operator< (ipv6_addr a1, ipv6_addr a2);
constexpr bool operator> (ipv6_addr a1, ipv6_addr a2);
constexpr bool operator<=(ipv6_addr a1, ipv6_addr a2);
constexpr bool operator>=(ipv6_addr a1, ipv6_addr a2);

constexpr bool operator==(ipv6_addr a1, ::in6_addr a2);
constexpr bool operator!=(ipv6_addr a1, ::in6_addr a2);
constexpr bool operator< (ipv6_addr a1, ::in6_addr a2);
constexpr bool operator> (ipv6_addr a1, ::in6_addr a2);
constexpr bool operator<=(ipv6_addr a1, ::in6_addr a2);
constexpr bool operator>=(ipv6_addr a1, ::in6_addr a2);

constexpr bool operator==(::in6_addr a1, ipv6_addr a2);
constexpr bool operator!=(::in6_addr a1, ipv6_addr a2);
constexpr bool operator< (::in6_addr a1, ipv6_addr a2);
constexpr bool operator> (::in6_addr a1, ipv6_addr a2);
constexpr bool operator<=(::in6_addr a1, ipv6_addr a2);
constexpr bool operator>=(::in6_addr a1, ipv6_addr a2);

void to_text_append(::in6_addr ip, std::string &res);

template<> struct std::hash<ipv6_addr>;

ipv4_addr analogue for IPv6/::in6_addr.

explicit ipv6_addr(const ::in_addr &ip4)

static constexpr ipv6_addr any()

static constexpr ipv6_addr loopback()

bool is_any() const

bool is_loopback() const

bool is_ipv4_mapped() const

ipv4_addr to_ipv4() const

2.15__vic/iterator.h

Iterators-related utilities.

2.15.1begin(T[]), end(T[]), cbegin(T[]), cend(T[])

template<class T, size_t N> constexpr T *begin(T (&arr)[N]);
template<class T, size_t N> constexpr T *end(T (&arr)[N]);

template<class T, size_t N> constexpr const T *cbegin(T (&arr)[N]);
template<class T, size_t N> constexpr const T *cend(T (&arr)[N]);

Return a pointer to the beginning and past-the-end of the array.

int vals[] = { 1, 2, 3 };
std::list<int> lst(__vic::begin(vals), __vic::end(vals));
assert(lst.size() == 3);

2.15.2advance()

template<class Iter>
void advance(Iter &it, Iter end, size_t n);

A counterpart of std::advance() but differs in parameters and behaviour:

1. Allows only forward movement (++),
2. Checks the range bounds. Returns immediately if end is reached.

2.15.3next(), prev()

template<class ForwardIterator>
ForwardIterator next(ForwardIterator it);

template<class ForwardIterator>
ForwardIterator next(ForwardIterator it, size_t n);

template<class BidirectionalIterator>
BidirectionalIterator prev(BidirectionalIterator it);

template<class BidirectionalIterator>
BidirectionalIterator prev(BidirectionalIterator it, size_t n);

next() returns an iterator advanced by n positions. prev() does the same but in reverse order. As opposed to C++11 STL functions of the same name, the offset cannot be negative. The versions with single parameter just call ++it/--it and return the result.

template<class Container>
void f(const Container &c)
{
    // Begin a traversal starting from the second element
    // v.begin() + 1 works only with RandomAccessIterator
    // ++v.begin() may cause a compile error
    for(auto it = __vic::next(c.begin()); it != c.end(); ++it) ...;
}

2.16__vic/logger.h

2.16.1logger

class logger : private non_copyable
{
public:
    enum class severity : unsigned char
    {
        trace,
        debug,
        info,
        notice,
        warning,
        error,
        fatal
    };
    using severity_t = severity; // use this alias as a type name
    struct output
    {
        virtual void publish_record(severity_t , const char * , size_t ) = 0;
    protected:
        ~output() = default;
    };
    class settings_t
    {
        struct output &output() const;
        severity_t level() const;
    };
    class record;

    explicit logger(output &out, severity_t = severity::info);
    explicit logger(settings_t s);
    ~logger();

    severity_t level() const;
    void level(severity_t new_level);
    settings_t settings() const;
    output &reset_output(output &out);
    output &get_output();
    const output &get_output() const;

    static constexpr size_t min_buffer_size = ...;
    void shrink_buffer(size_t limit);

    void message(severity_t severity, const char *msg, size_t msg_len);
#if __cpp_lib_string_view // C++17
    void message(severity_t severity, std::string_view msg);

    void trace(std::string_view msg);
    void debug(std::string_view msg);
    void info(std::string_view msg);
    void notice(std::string_view msg);
    void warning(std::string_view msg);
    void error(std::string_view msg);
    void fatal(std::string_view msg);
#else // until C++17
    void message(severity_t severity, const char *msg);
    void message(severity_t severity, const std::string &msg);

    void trace(const char *msg);
    void debug(const char *msg);
    void info(const char *msg);
    void notice(const char *msg);
    void warning(const char *msg);
    void error(const char *msg);
    void fatal(const char *msg);

    void trace(const std::string &msg);
    void debug(const std::string &msg);
    void info(const std::string &msg);
    void notice(const std::string &msg);
    void warning(const std::string &msg);
    void error(const std::string &msg);
    void fatal(const std::string &msg);
#endif

#if __cpp_lib_format >= 202106L // C++20 + P2508
    template<class... Args>
    void format(severity_t s,
        std::format_string<Args...> fmt, Args&&... args);

    template<class Arg1, class... Args>
    void trace(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
    template<class Arg1, class... Args>
    void debug(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
    template<class Arg1, class... Args>
    void info(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
    template<class Arg1, class... Args>
    void notice(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
    template<class Arg1, class... Args>
    void warning(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
    template<class Arg1, class... Args>
    void error(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
    template<class Arg1, class... Args>
    void fatal(std::format_string<Arg1,Args...> fmt,
                                        Arg1 &&arg1, Args&&... args);
#endif

    record trace();
    record debug();
    record info();
    record notice();
    record warning();
    record error();
    record fatal();

    bool trace_visible() const;
    bool debug_visible() const;
    bool info_visible() const;
    bool notice_visible() const;
    bool warning_visible() const;
    bool error_visible() const;
    bool fatal_visible() const;
};
class logger::record
{
public:
    record(logger &log, severity_t sev);
    ~record();

    record append(const char *str, size_t str_len);

    template<class T> record operator<<(const T &v);
};
template<class T> struct log_value
{
    static void to_text(const T &v, std::string &s);
};
const char *to_string(logger::severity_t s);
#if __cpp_lib_string_view // C++17
constexpr std::string_view to_string_view(logger::severity s);
#endif

Logging front-end. Provides building of the log records using operator <<, like iostream. Each log record has the associated severity. The logger itself can filter out the records by severity. There are 7 predefined levels of the severity (in ascending order):

1. TRACE - detailed debug,
2. DEBUG - debug,
3. INFO - informational,
4. NOTICE - normal but significant event,
5. WARNING - insignificant error or suspicious situation,
6. ERROR - severe error but the application can continue,
7. FATAL - critical unrecoverable error, the application can't continue.

INFO is the default logging level but any other can be chosen. If severity of the log message (record) is below the logging level, it will be ignored and will not be published in the log's output.

For creation of messages with the required severity, the set of functions with the same name as the severity is available. For instance info() for INFO messages. Or alternatively the universal function message() can be used, in which the severity is the argument. Usually the specific functions should be used.

There are two ways of logging. The first is plain and common:

log.trace("Trace message");
log.debug("Debug message");
log.info("Info message");
log.notice("Notice");
log.warning("Warning");
log.error("Recoverable error");
log.fatal("Fatal error");

The second is slightly more complex but provides more capabilities:

log.error() << "Cannot open file " << filename << '!';
log.warning() << "Loop iteration no " << i;

The call without parameters creates the object of type logger::record with the corresponding severity. Futher, the message is formed using operators <<. The message will be output to the log at the end of the full-expression (term from the Standard).

If the message can't or shouldn't be formed with a single expression, the named object of type logger::record has to be created, and parts of the message have to be written to it. The resulting message will be output to the log by it's destructor:

{
    logger::record rec = log.info(); // Begin new record
    rec << "List elements: ";
    for(auto el : list) rec << el << ", ";
    // Constructed record will be printed to the log when the block exits
}

log.info("Message");
// but not
log.info() << "Message";

Output of the records with the severities DEBUG and TRACE is usually disabled. Such records will not be published in the log but the program will waste time to format it. Therefore before creating any debug message using operator << one should check if debug is enabled using debug_visible() or trace_visible() call:

if(log.debug_visible())
    log.debug() << ...; // build the message

This advice doesn't cover plain calls debug(msg) and trace(msg), which have a prepared message already and don't perform any formatting.

To use logger one has to implement abstract base class logger::output (override publish_record()). The implementation has to output the passed record somewhere, e.g. to file, terminal or DB. The output specified during logger construction can be replaced later using reset_output().

severity::trace

severity::debug

severity::info

severity::notice

severity::warning

severity::error

severity::fatal

typename severity_t

class output

void output::publish_record(severity_t sev, const char *buf, size_t buf_len)

class settings_t

explicit logger(output &out, severity_t level = severity::info)

explicit logger(settings_t s)

severity_t level() const

void level(severity_t new_level)

settings_t settings() const

output &reset_output(output &out)

output &get_output()

const output &get_output() const

static constexpr size_t min_buffer_size

void shrink_buffer(size_t limit)

void message(severity_t severity, const char *msg, size_t msg_len)

void message(severity_t severity, std::string_view msg) [C++17]

void message(severity_t severity, const char *msg) [until C++17]

void message(severity_t severity, const std::string &msg) [until C++17]

void trace(std::string_view msg) [C++17]

void trace(const char *msg) [until C++17]

void trace(const std::string &msg) [until C++17]

void debug(std::string_view msg) [C++17]

void debug(const char *msg) [until C++17]

void debug(const std::string &msg) [until C++17]

void info(std::string_view msg) [C++17]

void info(const char *msg) [until C++17]

void info(const std::string &msg) [until C++17]

void notice(std::string_view msg) [C++17]

void notice(const char *msg) [until C++17]

void notice(const std::string &msg) [until C++17]

void warning(std::string_view msg) [C++17]

void warning(const char *msg) [until C++17]

void warning(const std::string &msg) [until C++17]

void error(std::string_view msg) [C++17]

void error(const char *msg) [until C++17]

void error(const std::string &msg) [until C++17]

void fatal(std::string_view msg) [C++17]

void fatal(const char *msg) [until C++17]

void fatal(const std::string &msg) [until C++17]

template<class... Args>
void format(severity_t s,
    std::format_string<Args...> fmt, Args&&... args) [C++20]

template<class Arg1, class... Args>
void trace(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

template<class Arg1, class... Args>
void debug(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

template<class Arg1, class... Args>
void info(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

template<class Arg1, class... Args>
void notice(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

template<class Arg1, class... Args>
void warning(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

template<class Arg1, class... Args>
void error(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

template<class Arg1, class... Args>
void fatal(std::format_string<Arg1,Args...> fmt, Arg1 &&arg1, Args&&... args) [C++20]

logger::record trace()

logger::record debug()

logger::record info()

logger::record notice()

logger::record warning()

logger::record error()

logger::record fatal()

bool trace_visible() const

bool debug_visible() const

bool info_visible() const

bool notice_visible() const

bool warning_visible() const

bool error_visible() const

bool fatal_visible() const

record::record(logger &log, severity_t sev)

record::~record()

record record::append(const char *str, size_t str_len)

template<class T> record record::operator<<(const T &v)

template<class T> void log_value<T>::to_text(const T &v, std::string &s)

const char *to_string(logger::severity_t s)

constexpr std::string_view to_string_view(logger::severity s) [C++17]

/////////////////////////////////////////////////////////////////////////////
// Output messages to std::clog with the severity label
class coutput : public __vic::logger::output
{
public:
    void publish_record(__vic::logger::severity_t s,
                            const char *rec, size_t rec_n)
    {
        std::clog << to_string(s) << ": ";
        std::clog.write(rec, rec_n) << std::endl;
    }
};
/////////////////////////////////////////////////////////////////////////////

int main()
{
    coutput log_output:
    __vic::logger log(log_output, __vic::logger::severity::debug);

    log.info("Application is started");

    for(int i = 0; i < 5; i++)
        log.debug() << "Loop i = " << i;

    log.warning("Application end");
}

Output:

INFO: Application is started
DEBUG: Loop i = 0
DEBUG: Loop i = 1
DEBUG: Loop i = 2
DEBUG: Loop i = 3
DEBUG: Loop i = 4
WARNING: Application end

2.17__vic/memory.h

Memory-related utilities.

2.17.1load_unaligned()

template<class T>
T load_unaligned(const void *p);

Load value from potentially unaligned address without causing bus error (SIGBUS).

const void *p = ...;
// int data = *static_cast<const int *>(p); // potential bus error
int data = __vic::load_unaligned<int>(p);

2.17.2store_unaligned()

template<class T>
void store_unaligned(void *p, T v);

Store value to potentially unaligned address without causing bus error (SIGBUS).

void *p = ...;
// *static_cast<int *>(p) = 123; // potential bus error
__vic::store_unaligned(p, 123);

2.18__vic/mutex.h

2.18.1mutex

class mutex : private non_copyable
{
public:
    mutex();
    ~mutex();

    void lock();
    bool try_lock();
    bool unlock() noexcept;
};

Plain non-recursive mutex.

In most cases explicit usage of lock() and unlock() should be avoided. Use class mutex_lock to manage locks instead. It provides exception safety and it's handy for usage.

In C++11 mode std::mutex can be a better alternative.

mutex()

~mutex()

void lock()

bool try_lock()

bool unlock() noexcept

See mutex_lock.

2.18.2mutex_lock

class mutex_lock : private non_copyable
{
public:
    enum adopt_t { adopt };

    explicit mutex_lock(mutex &mtx);
    mutex_lock(mutex &mtx, adopt_t);
    ~mutex_lock();
};

Manages the lock on a mutex. The lock exists while the object is alive.

adopt

explicit mutex_lock(mutex &mtx)

~mutex_lock()

mutex_lock(mutex &mtx, adopt_t)

// Typical usage
__vic::mutex mtx;
void reentrant_function()
{
    __vic::mutex_lock lock(mtx);
    // Critical section code until the end of the block
    ...
}

// Usage of non-acquiring constructor
if(mtx.try_lock()) // Try to acquire the mutex
{
    // The mutex has been successfully acquired
    __vic::mutex_lock lock(mtx, __vic::mutex_lock::adopt);
    // Critical section code until the end of the block
    ...
}
else
{
    // The mutex is acquired by another thread
    ...
}

2.19__vic/packon.h & __vic/packoff.h

Inclusion of the first file turns off struct members alignment. In other words, turns on "structures packing" - size of the struct is strictly a sum of its members sizes. Inclusion of the second one restores the default alignment. So that the pair of #include directives forms a section in the source file where structs alignment is disabled.

struct unpacked
{
    bool f1;
    int f2;
};
static_assert(sizeof(unpacked) >= sizeof(bool) + sizeof(int),
    "Total struct size can exceed the sum of members sizes");

#include<__vic/packon.h> // alignment disabled starting from here

struct packed
{
    bool f1;
    int f2;
};
static_assert(sizeof(packed) == sizeof(bool) + sizeof(int),
    "Total struct size is exactly the sum of members sizes");

#include<__vic/packoff.h> // alignment enabled again

2.20__vic/readonly_cstring.h

2.20.1readonly_cstring

class readonly_cstring
{
public:
    readonly_cstring();
    readonly_cstring(const char *str);
    readonly_cstring(const char *begin, const char *end);
    readonly_cstring(const char *chars, size_t n);
    readonly_cstring(const readonly_cstring &str);
    ~readonly_cstring() noexcept;

    // BEGIN C++11
    readonly_cstring(readonly_cstring &&str) noexcept;
    readonly_cstring &operator=(readonly_cstring &&str) noexcept;
    // END C++11

    readonly_cstring &operator=(const char *str);
    readonly_cstring &operator=(const readonly_cstring &str);
    readonly_cstring &assign(const char *str);
    readonly_cstring &assign(const char *chars, size_t n);
    readonly_cstring &assign(const char *begin, const char *end);

    bool empty() const;
    const char *c_str() const;
    operator const char*() const;

    char *reserve(size_t n);
    void swap(readonly_cstring &str) noexcept;
};

int compare(const readonly_cstring &s1, const readonly_cstring &s2);
int compare(const readonly_cstring &s1, const char *s2);
int compare(const char *s1, const readonly_cstring &s2);

bool operator==(const readonly_cstring &s1, const readonly_cstring &s2);
bool operator!=(const readonly_cstring &s1, const readonly_cstring &s2);
bool operator<(const readonly_cstring &s1, const readonly_cstring &s2);
bool operator>(const readonly_cstring &s1, const readonly_cstring &s2);
bool operator<=(const readonly_cstring &s1, const readonly_cstring &s2);
bool operator>=(const readonly_cstring &s1, const readonly_cstring &s2);

bool operator==(const readonly_cstring &s1, const char *s2);
bool operator!=(const readonly_cstring &s1, const char *s2);
bool operator<(const readonly_cstring &s1, const char *s2);
bool operator>(const readonly_cstring &s1, const char *s2);
bool operator<=(const readonly_cstring &s1, const char *s2);
bool operator>=(const readonly_cstring &s1, const char *s2);

bool operator==(const char *s1, const readonly_cstring &s2);
bool operator!=(const char *s1, const readonly_cstring &s2);
bool operator<(const char *s1, const readonly_cstring &s2);
bool operator>(const char *s1, const readonly_cstring &s2);
bool operator<=(const char *s1, const readonly_cstring &s2);
bool operator>=(const char *s1, const readonly_cstring &s2);

void swap(readonly_cstring &s1, readonly_cstring &s2) noexcept;

The simple non-mutable null-terminated string class with automatic memory management. Has simple and predictable structure that can be useful when ABI compatibility/stability is required or when usage of std::string is objectionable for some reason. The functionality provided by the class is also minimal. It provides string copying and storing and read access to it. One cannot modify string parts - only replace the whole value.

If one need to store a string value in a class, usage of this class may be a good choice. It's easier-to-use, more clear and safer than array of chars (char[]) and can be more efficient than std::string, though, of course, less universal. If modifications of the string parts are expected, usage of another string class should be considered, for instance, __vic::string_buffer. Class readonly_cstring is not designed for such purposes.

• Null pointer value is treated as an empty string.
• Cast to C-string (const char *) always returns valid pointer, never nullptr.
• For each string value, exact amount of memory is allocated. No extra memory reserved.
• Class contains single data member - pointer to the holded string, so the total object's size is likely one pointer.

readonly_cstring()

readonly_cstring(const char *str)

readonly_cstring(const readonly_cstring &str)

readonly_cstring(const char *chars, size_t n)

readonly_cstring(const char *begin, const char *end)

readonly_cstring &operator=(const char *str)

readonly_cstring &operator=(const readonly_cstring &str)

readonly_cstring &assign(const char *str)

readonly_cstring(readonly_cstring &&str) noexcept [C++11]

readonly_cstring &operator=(readonly_cstring &&str) noexcept [C++11]

readonly_cstring &assign(const char *begin, const char *end)

readonly_cstring &assign(const char *chars, size_t n)

bool empty() const

const char *c_str() const

operator const char*() const

char *reserve(size_t n)

void swap(readonly_cstring &str) noexcept

int compare(const readonly_cstring &s1, const readonly_cstring &s2)

int compare(const readonly_cstring &s1, const char *s2)

int compare(const char *s1, const readonly_cstring &s2)

bool operator==(const readonly_cstring &s1, const readonly_cstring &s2)

...

bool operator>=(const char *s1, const readonly_cstring &s2)

void swap(readonly_cstring &s1, readonly_cstring &s2) noexcept

class C
{
    __vic::readonly_cstring st;
public:
    explicit C(const char *str) : st(str) {}
    const char *get_str() const { return st; }
};

2.21__vic/set_of_chars.h

2.21.1set_of_chars

class set_of_chars
{
public:
    constexpr set_of_chars();
    template<class Iter> constexpr set_of_chars(Iter begin, Iter end);
    constexpr set_of_chars(std::initializer_list<char> set); // C++11
    constexpr set_of_chars(const char *c_str);

    constexpr bool contains(char ch) const;

    constexpr void add(char ch);
    constexpr void remove(char ch);

    template<class Iter> constexpr void add(Iter begin, Iter end);
    constexpr void add(const char *c_str);
    constexpr void add(std::initializer_list<char> set); // C++11

    template<class Iter> void assign(Iter begin, Iter end);
    void assign(const char *c_str)
    void assign(std::initializer_list<char> set); // C++11

    void clear();
};

Compact (only 32 bytes) and very fast implemetation of a set of chars. The cost of the contains() operation is always constant regardles of the argument and number of elements in the set.

constexpr set_of_chars()

template<class Iter> constexpr set_of_chars(Iter begin, Iter end)

constexpr set_of_chars(std::initializer_list<char> set) [C++11]

constexpr set_of_chars(const char *c_str)

bool contains(char ch) const

constexpr void add(char ch)

constexpr void remove(char ch)

template<class Iter> constexpr void add(Iter begin, Iter end)

constexpr void add(std::initializer_list<char> set) [C++11]

constexpr void add(const char *c_str)

template<class Iter> void assign(Iter begin, Iter end)

void assign(const char *c_str)

void assign(std::initializer_list<char> set) [C++11]

void clear()

2.22__vic/stdint.h

ISO C99 <stdint.h> for C++98. Since C++11 - just a redirector to <cstdint>.

Additionally, some metafunctions for template metaprogramming are provided.

2.22.1Exact-width integer types

Following types are guaranteed to be available in the global namespace:

• int8_t
• int16_t
• int32_t
• int64_t
• uint8_t
• uint16_t
• uint32_t
• uint64_t

2.22.2Minimum-width integer types

Following types are guaranteed to be available in the global namespace:

• int_least8_t
• int_least16_t
• int_least32_t
• int_least64_t
• uint_least8_t
• uint_least16_t
• uint_least32_t
• uint_least64_t

2.22.3Fastest minimum-width integer types

Following types are guaranteed to be available in the global namespace:

• int_fast8_t
• int_fast16_t
• int_fast32_t
• int_fast64_t
• uint_fast8_t
• uint_fast16_t
• uint_fast32_t
• uint_fast64_t

2.22.4Greatest-width integer types

Following types are guaranteed to be available in the global namespace:

• intmax_t
• uintmax_t

2.22.5Integer types capable of holding object pointers

Following types are guaranteed to be available in the global namespace:

• intptr_t
• uintptr_t

2.22.6int_exactly_bytes<>, uint_exactly_bytes<>

template<unsigned SizeInBytes>
struct int_exactly_bytes
{
    using type = <signed-integer-type-of-the-corresponding-size>;
};

template<unsigned SizeInBytes>
struct uint_exactly_bytes
{
    using type = <unsigned-integer-type-of-the-corresponding-size>;
};

// BEGIN C++11
template<unsigned N>
using int_exact_bytes = typename int_exactly_bytes<N>::type;

template<unsigned N>
using uint_exact_bytes = typename uint_exactly_bytes<N>::type;
// END C++11

Metafunctions returning the signed/unsigned interger type of the requested exact size in bytes. Shorter aliases are available in C++11 mode and higher. Valid SizeInBytes values are 1, 2, 4, 8.

typedef __vic::int_exactly_bytes< sizeof(void *) >::type my_intptr_t;
// or in C++11
using my_intptr_t = __vic::int_exact_bytes< sizeof(void *) >
assert( sizeof(my_intptr) == sizeof(intptr_t) );

2.23__vic/stdio_file.h

std::FILE-related C++ wrappers.

2.23.1stdio_file

class stdio_file : private non_copyable
{
public:
    explicit stdio_file(std::FILE *fp = nullptr);
    stdio_file(const char *name, const char *mode);
    ~stdio_file();

    // BEGIN C++11
    stdio_file(stdio_file &&o) noexcept;
    stdio_file &operator=(stdio_file &&o) noexcept;
    // END C++11

    bool open(const char *name, const char *mode);
    bool is_open() const;
    void close();
    bool close_nt() noexcept;

    void swap(stdio_file &o) noexcept;
    std::FILE *detach_handle() noexcept;
    std::FILE *attach_handle(std::FILE *fp) noexcept;
    std::FILE *handle() const;
    operator std::FILE*() const;
};

Thin RAII-wrapper for std::FILE *. Controls file's life time. Automatic conversion to std::FILE * allows usage of the object whereever the file pointer is allowed/required.

explicit stdio_file(std::FILE *fp = nullptr)

stdio_file(const char *name, const char *mode)

~stdio_file()

stdio_file(stdio_file &&o) noexcept [C++11]

stdio_file &operator=(stdio_file &&o) noexcept [C++11]

bool open(const char *name, const char *mode)

bool is_open() const

void close()

bool close_nt() noexcept

void swap(stdio_file &o) noexcept

std::FILE *detach_handle() noexcept

std::FILE *attach_handle(std::FILE *fp) noexcept

std::FILE *handle() const

operator std::FILE*() const

__vic::stdio_file file("file.txt", "w");
if(!file.is_open()) throw __vic::exception("Cannot open file");
std::fprintf(file, "Message");
file.close();
// fclose() also will be called in case of exception by destructor

2.23.2read(std::FILE)

sread_result<char> read(std::FILE *fp);

Attempts to read a byte from the C-stream. Returns the succesful result on success, unsuccessful result on EOF or throws on error.

2.23.3write(std::FILE)

void write(std::FILE *fp, char ch);

Writes a byte to the C-stream. Throws on error.

2.23.4getline(std::FILE)

bool getline(std::FILE *fp, std::string &str, char delim = '\n');

A counterpart of std::getline but for C-stream. Returns false if the end of the file was reached and nothing was read.

2.24__vic/str2num.h

2.24.1decimal_to_number()

#if __cpp_lib_string_view // since C++17

void decimal_to_number(std::string_view s, long long &res);
void decimal_to_number(std::string_view s, long &res);
void decimal_to_number(std::string_view s, int &res);
void decimal_to_number(std::string_view s, short &res);
void decimal_to_number(std::string_view s, signed char &res);

void decimal_to_number(std::string_view s, unsigned long long &res);
void decimal_to_number(std::string_view s, unsigned long &res);
void decimal_to_number(std::string_view s, unsigned &res);
void decimal_to_number(std::string_view s, unsigned short &res);
void decimal_to_number(std::string_view s, unsigned char &res);

template<class Integer>
[[nodiscard]] Integer decimal_to_number(std::string_view s);

#else // until C++17

void decimal_to_number(const std::string &s, long long &res);
void decimal_to_number(const std::string &s, long &res);
void decimal_to_number(const std::string &s, int &res);
void decimal_to_number(const std::string &s, short &res);
void decimal_to_number(const std::string &s, signed char &res);

void decimal_to_number(const std::string &s, unsigned long long &res);
void decimal_to_number(const std::string &s, unsigned long &res);
void decimal_to_number(const std::string &s, unsigned &res);
void decimal_to_number(const std::string &s, unsigned short &res);
void decimal_to_number(const std::string &s, unsigned char &res);

void decimal_to_number(const char *s, long long &res);
void decimal_to_number(const char *s, long &res);
void decimal_to_number(const char *s, int &res);
void decimal_to_number(const char *s, short &res);
void decimal_to_number(const char *s, signed char &res);

void decimal_to_number(const char *s, unsigned long long &res);
void decimal_to_number(const char *s, unsigned long &res);
void decimal_to_number(const char *s, unsigned &res);
void decimal_to_number(const char *s, unsigned short &res);
void decimal_to_number(const char *s, unsigned char &res);

template<class Integer>
[[nodiscard]] Integer decimal_to_number(const std::string &s);

template<class Integer>
[[nodiscard]] Integer decimal_to_number(const char *s);

#endif

The set of functions converts a string, that represents an integer in decimal notation, to one of the standard C++ integer types. The string can be a C-string as well as std::string.

As opposed to the standard converters, like std::strtol(), strict validation of the format of the whole string and value range is performed. In particular leading spaces and non-digit characters at the end are not allowed. For unsigned types minus ('-') is disallowed, which is happily accepted by std::strtoul() by unknown reason.

In case of errors the following exceptions are thrown:

• std::invalid_argument - the string is not a correct decimal integer;
• std::range_error - the string is probably correct but the result cannot be represented by the used type (integer overflow).

There are two kinds of the function prototypes:

1. The result is returned via additional output parameter and
2. The result is returned using the natural way, the type is specified using the template parameter.

2.24.2decimal_to_number_range()

template<class T, class InputIterator>
void decimal_to_number_range(InputIterator begin, InputIterator end, T &res);

template<class T, class InputIterator>
[[nodiscard]] T decimal_to_number_range(InputIterator begin, InputIterator end);

The functions are complete analogs of decimal_to_number() except they work with generic ranges of characters instead of strings.

2.24.3parse_decimal()

#if __cpp_lib_string_view // since C++17

template<class T>
[[nodiscard]] number_parse_result<T> parse_decimal(std::string_view s);

#else // until C++17

template<class T>
[[nodiscard]] number_parse_result<T> parse_decimal(const std::string &s);
template<class T>
[[nodiscard]] number_parse_result<T> parse_decimal(const char *s);

#endif

template<class T, class InputIterator>
[[nodiscard]]
number_parse_result<T> parse_decimal(InputIterator begin, InputIterator end);

A counterpart of decimal_to_number() functions but doesn't throw exceptions. The returned object is boolean-testable and indicates the success of the operation. Also it contains the resulting number in case of success, or an error code otherwise. See number_parse_result for more information.

if(auto res = __vic::parse_decimal<int>("123"))
{
    int num = res.value();
    // Use num
}

2.24.4decimal_parser

template<class T>
class decimal_parser
{
    using status = number_parse_status; // for brevity only
public:
    template<class InputIterator>
    [[nodiscard]] status parse(InputIterator begin, InputIterator end);
#if __cpp_lib_string_view // since C++17
    [[nodiscard]] status parse(std::string_view str);
#else // until C++17
    [[nodiscard]] status parse(const std::string &str);
    [[nodiscard]] status parse(const char *str);
#endif
    [[nodiscard]] T result() const;
};

A counterpart of decimal_to_number() functions but doesn't throw exceptions, number_parse_status codes are returned instead by parse().

number_parse_status::ok

number_parse_status::invalid_number

number_parse_status::unrepresentable

template<class InputIterator>
[[nodiscard]] status parse(InputIterator begin, InputIterator end)

[[nodiscard]] status parse(std::string_view str) [C++17]

[[nodiscard]] status parse(const std::string &str) [until C++17]

[[nodiscard]] status parse(const char *str) [until C++17]

[[nodiscard]] T result() const

template<class T>
bool to_number(const std::string &s, T &result) noexcept
{
    __vic::decimal_parser<T> p;
    if(p.parse(s) != __vic::number_parse_status::ok) return false;
    result = p.result();
    returt true; // 'result' contains the result of conversion
}

2.24.5number_parse_status

enum class number_parse_status : unsigned char
{
    ok,
    invalid_number,
    unrepresentable
};
using number_parse_status_t = number_parse_status; // for C++98

Number parsing outcome status codes.

typename number_parse_status_t

2.24.6number_parse_result

template<class T>
class number_parse_result
{
public:
    typedef T value_type;

    number_parse_result(number_parse_status_t s);
    explicit number_parse_result(T n);

    number_parse_status_t status() const;
    explicit operator bool() const;
    bool has_value() const;

    T value() const;
};

number_parse_status + the resulting value in case of success.

number_parse_result(number_parse_status_t s)

explicit number_parse_result(T n)

number_parse_status_t status() const

bool has_value() const

explicit operator bool() const

T value() const

2.25__vic/string_buffer.h

2.25.1string_buffer

class string_buffer : public std::string
{
public:
    string_buffer();
    explicit string_buffer(size_type n);
    string_buffer(const char *str);
    string_buffer(std::string str);
    string_buffer(string_ref sr);
    string_buffer(const std::string &str, size_type off, size_type n = npos);
    string_buffer(const char *char_buf, size_type n);
    string_buffer(const char *begin, const char *end);
    template<class InputIterator>
    string_buffer(InputIterator begin, InputIterator end);

    template<class T> string_buffer &operator<<(const T &v);

    string_buffer &operator=(string_ref sr);
    string_buffer &operator+=(string_ref sr);
    string_buffer &assign(string_ref sr);
    string_buffer &append(string_ref sr);

    // improved std::string calls
    string_buffer &assign(const std::string &str,
                            size_type off, size_type n = npos);
    string_buffer &append(const std::string &str,
                            size_type off, size_type n = npos);
    string_buffer &insert(size_type pos, const std::string &str,
                            size_type off, size_type n = npos);

    string_buffer &reserve(size_type n);
    string_buffer &clear();

    // missing container interface of std::string
    reference front();
    reference back();
    const_reference front() const;
    const_reference back() const;
    void pop_back();

    operator const char *() const;
};

string_buffer operator+(const string_buffer &s1, const string_buffer &s2);
string_buffer operator+(const string_buffer &s1, const std::string &s2);
string_buffer operator+(const std::string &s1, const string_buffer &s2);

string_buffer operator+(const string_buffer &s1, const char *s2);
string_buffer operator+(const char *s1, const string_buffer &s2);

string_buffer operator+(const string_buffer &s, char ch);
string_buffer operator+(char ch, const string_buffer &s);

using msg = string_buffer;

Class is an extended and improved std::string. It has following advantages:

1. Left-associative append operator (<<) that allows constructions like this:

   str << "Error message: " << err_msg << "\n";
   

2. Specific amount of bytes can be reserved using constructor as well as reserve() call. Reserving required amount of space in advance can improve performance significantly.

   __vic::string_buffer st(4096);
   
   // is same as
   std::string st;
   st.reserve(4096);
   

3. Operator << accepts all fundamental types: numbers, chars, pointers, bool, and other types for which to_text_append() is applicable:

   for(int i=0; i<10; i++)
       str << "i = " << i << '\n';
   

4. All input nullptr values of const char * are treated as an empty string. Such values usually cause crash with std::string.

   std::string s1("Str");
   const char *p = nullptr;
   s1.append(p); // Oops.... Null pointer access!
   
   __vic::string_buffer s2("Str");
   s2.append(p); // Ok. s2 == "Str" still
   s2 = p; // Ok. s2.empty() == true
   

5. Automatic conversion to const char * that allows usage of the object in context requires C-string, without explicit c_str() call.

   std::string fname(...);
   FILE *fp = fopen(fname.c_str(), "r");
   
   __vic::string_buffer fname(...);
   FILE *fp = fopen(fname, "r");)
   

6. Some design irregularities of std::string are corrected. For instance std::string is a complete container but operations front() and back() are missed in C++98. There is push_back() but no pop_back().

In spite of all these improvements, the interface of this class is completely backward compatible with std::string. Objects can be passed in contexts that require std::string. Class has no additional data-members.

Using of inserter (operator <<) provides the easiest way to convert numbers to decimal string representation. Using of std::ostringstream for this purposes is more functional (you can specify radix, formatting, etc) but too tedious and not efficient in most cases.

Additionally this type has a short synonym msg. It is very convenient for usage when one needs to construct a complex message with a single expression, without introducing unnecessary variables:

oresult res = db_open(db_name);
if(res != 0) throw __vic::exception(
    __vic::msg(64) << "Cannot open DB " << db_name << ". res = " << res
);

As you can see, the maximum size of the message expected is specified in the constructor for optimization purposes.

string_buffer()

explicit string_buffer(size_type n)

string_buffer(const char *str)

string_buffer(std::string str)

string_buffer(const std::string &str, size_type off, size_type n = npos)

string_buffer(const char *char_buf, size_type n)

string_buffer(string_ref sr)

string_buffer(const char *begin, const char *end)

template<class InputIterator>
string_buffer(InputIterator begin, InputIterator end)

template<class T> string_buffer &operator<<(const T &v)

string_buffer &reserve(size_type n)

string_buffer &clear()

reference front()

reference back()

const_reference front() const

const_reference back() const

void pop_back()

operator const char *() const

string_buffer operator+(const string_buffer &s1, const string_buffer &s2)

string_buffer operator+(const string_buffer &s1, const std::string &s2)

string_buffer operator+(const std::string &s1, const string_buffer &s2)

string_buffer operator+(const string_buffer &s1, const char *s2)

string_buffer operator+(const char *s1, const string_buffer &s2)

string_buffer operator+(const string_buffer &s, char ch)

string_buffer operator+(char ch, const string_buffer &s)

2.26__vic/string_ref.h

2.26.1string_ref

template<class charT>
class basic_string_ref
{
public:
    using value_type = charT;
    using iterator = const value_type *;
    using const_iterator = iterator;

    // Constructors
    basic_string_ref();
    basic_string_ref(const charT *str);
    basic_string_ref(const charT *chars, size_t n);
    basic_string_ref(const charT *begin, const charT *end);
    template<class Traits, class Alloc>
    explicit basic_string_ref(
        const std::basic_string<charT,Traits,Alloc> &str);
    basic_string_ref(
        typename std::basic_string<charT>::const_iterator begin,
        typename std::basic_string<charT>::const_iterator end);
    // BEGIN C++11
    basic_string_ref(std::initializer_list<charT> );
    // END C++11

#if __cpp_lib_string_view // since C++17
    template<class Traits>
    basic_string_ref(std::basic_string_view<charT,Traits> s);
    operator std::basic_string_view<charT>() const;
#endif

    // Accessors
    iterator begin() const;
    iterator end() const;
    iterator cbegin() const;
    iterator cend() const;

    charT front() const;
    charT back() const;
    charT operator[](size_t i) const;
    const charT *data() const;

    bool empty() const;
    size_t size() const;
    size_t length() const;

    int compare(basic_string_ref s) const;

    // Converters
    std::basic_string<charT> str() const;
    template<class Traits>
    std::basic_string<charT,Traits> str() const;
    template<class Traits, class Alloc>
    std::basic_string<charT,Traits,Alloc> str(const Alloc &a = Alloc())const;

    operator std::basic_string<charT>() const;
};

using string_ref = basic_string_ref<char> ;

template<class charT>
bool operator==(basic_string_ref<charT> s1, basic_string_ref<charT> s2);
template<class charT>
bool operator!=(basic_string_ref<charT> s1, basic_string_ref<charT> s2);
template<class charT>
bool operator<(basic_string_ref<charT> s1, basic_string_ref<charT> s2);
template<class charT>
bool operator>(basic_string_ref<charT> s1, basic_string_ref<charT> s2);
template<class charT>
bool operator<=(basic_string_ref<charT> s1, basic_string_ref<charT> s2);
template<class charT>
bool operator>=(basic_string_ref<charT> s1, basic_string_ref<charT> s2);

#ifdef __VIC_DEFINE_OSTREAM_INSERTERS
template<class charT, class Traits>
std::basic_ostream<charT,Traits> &operator<<(
    std::basic_ostream<charT,Traits> &os, const basic_string_ref<charT> &sr);
#endif

The class represents a reference to the read-only continuous range of characters. When used as a return value, it is significantly more lightweight than std::string, because no string copy or memory allocation performed. But, when std::string is required, automatic conversion happens. Let's consider the example:

class C
{
    std::string v;
public:
    std::string       get_v_1() const { return v; }
    __vic::string_ref get_v_2() const { return v; }
};

As you can see, class contains one string field. Two read-only access-functions are defined. The first as usual returns std::string, the second - string_ref. When the first is used, temporay string is created every time. When the second is used, just reference is returned.

Another use case - input read-only string argument. The class is a drop-in replacement for const std::string &. In most cases, it can also be used instead of const char *. The overhead in this case is an additional scan of the string to find the NULL-terminator, which is nothing in cases when we need the string end or length anyway. Let's consider 3 sets of overloaded functions:

void f1(const std::string & );

void f2(const std::string & );
void f2(const char * );

void f3(string_ref );

Each of them can be used as

fx("Nul-terminated string");

as well as

fx(std::string("std::string"));

But with f1() we will have redundant string copying in the first case, just to read the value. With f2() several overloads are required. And while it isn't a big issue when function has single argument, with two or more string arguments it quickly becomes very tedious. The last alternative - f3() - is at the same time as short and universal as f1() and "friendlier" to the string literals and strings from the C-world - they are not copied to the heap and not converted to std::string.

basic_string_ref()

basic_string_ref(const charT *str)

template<class Traits, class Alloc>
basic_string_ref(const std::basic_string<charT,Traits,Alloc> &str)

basic_string_ref(const charT *chars, size_t n)

basic_string_ref(const charT *begin, const charT *end)

basic_string_ref(const charT *chars, size_t n)

basic_string_ref(
    typename std::basic_string<charT>::const_iterator begin,
    typename std::basic_string<charT>::const_iterator end)

basic_string_ref(std::initializer_list<charT> ) [C++11]

template<class Traits>
basic_string_ref(std::basic_string_view<charT,Traits> s) [C++17]

operator std::basic_string_view<charT>() const [C++17]

iterator begin() const

iterator cbegin() const

const charT *data() const

iterator end() const

iterator cend() const

charT front() const

charT back() const

charT operator[](size_t i) const

bool empty() const

size_t size() const

size_t length() const

int compare(basic_string_ref s) const

std::basic_string<charT> str() const

template<class Traits>
std::basic_string<charT,Traits> str() const

template<class Traits, class Alloc>
std::basic_string<charT,Traits,Alloc> str(const Alloc &a = Alloc()) const

operator std::basic_string<charT>() const

template<class charT>
bool operator==(basic_string_ref<charT> s1, basic_string_ref<charT> s2)

template<class charT>
bool operator!=(basic_string_ref<charT> s1, basic_string_ref<charT> s2)

template<class charT>
bool operator<(basic_string_ref<charT> s1, basic_string_ref<charT> s2)

template<class charT>
bool operator>(basic_string_ref<charT> s1, basic_string_ref<charT> s2)

template<class charT>
bool operator<=(basic_string_ref<charT> s1, basic_string_ref<charT> s2)

template<class charT>
bool operator>=(basic_string_ref<charT> s1, basic_string_ref<charT> s2)

template<class charT, class Traits>
std::basic_ostream<charT,Traits> &operator<<(
    std::basic_ostream<charT,Traits> &os, const basic_string_ref<charT> &sr)

C c; // see the class description above
__vic::string_ref s = c. get_v_2();

// print the string using different ways
for(__vic::string_ref::iterator it = s.begin(); it != s.end(); ++it)
    std::cout << *it;

// C++11
for(auto ch : s) std::cout << ch;

std::copy(s.begin(), s.end(), std::ostream_iterator<char>(std::cout));

std::cout << s;

// automatic conversion to std::string
std::string ss = s;

2.27__vic/string_utils.h

Miscellaneous strings-related utilities.

2.27.1trim functions

char *trim(char *str);
char *trim_front(char *str);
char *trim_back(char *str);
char *trim(char *str, char ch);
char *trim_front(char *str, char ch);
char *trim_back(char *str, char ch);
char *trim(char *str, const char *set);
char *trim_front(char *str, const char *set);
char *trim_back(char *str, const char *set);

std::string &trim(std::string &str);
std::string &trim_front(std::string &str);
std::string &trim_back(std::string &str);
std::string &trim(std::string &str, char ch);
std::string &trim_front(std::string &str, char ch);
std::string &trim_back(std::string &str, char ch);
std::string &trim(std::string &str, const char *set);
std::string &trim_front(std::string &str, const char *set);
std::string &trim_back(std::string &str, const char *set);

#if __cpp_lib_string_view // C++17
std::string_view trimmed(std::string_view str);
std::string_view trimmed_front(std::string_view str);
std::string_view trimmed_back(std::string_view str);
std::string_view trimmed(std::string_view str, char ch);
std::string_view trimmed_front(std::string_view str, char ch);
std::string_view trimmed_back(std::string_view str, char ch);
std::string_view trimmed(std::string_view str, const char *set);
std::string_view trimmed_front(std::string_view str, const char *set);
std::string_view trimmed_back(std::string_view str, const char *set);
#else // until C++17
std::string trimmed(const std::string &str);
std::string trimmed_left(const std::string &str);
std::string trimmed_right(const std::string &str);
std::string trimmed(const std::string &str, char ch);
std::string trimmed_left(const std::string &str, char ch);
std::string trimmed_right(const std::string &str, char ch);
std::string trimmed(const std::string &str, const char *set);
std::string trimmed_left(const std::string &str, const char *set);
std::string trimmed_right(const std::string &str, const char *set);
#endif

The set of functions stripping unwanted characters from the string edges. Characters to strip can be specified. One can specify single character ch as well as the set of characters set. If no characters is specified, all ASCII-whitespaces are implied. Following naming rules for the functions are used:

• trim - strips from both edges,
• trim_front - strips from the beginning,
• trim_back - strips from the end.

Functions trim modify the string in-situ and return the pointer or reference to it. If the original value should be preserved, trimmed functions should be used.

• trimmed - return stripped copy of the string, argument itself is not modified.

The implementation is optimized for common case when the string does not have anything to trim. In such cases no modifications of the argument are performed, the function returns immediately after the checks are completed, and the call is maximally cheap.

All nullptr values are treated as an empty string.

char st1[] = "\t value    \n";

// CHOICE:
__vic::trim(st1);       // result: "value"
__vic::trim_front(st1); // result: "value    \n"
__vic::trim_back(st1);  // result: "\t value"

std::string st2("...value123");

// CHOICE:
// trim dot chars
__vic::trim_front(st1, '.');        // result: "value123"
// trim all digits
__vic::trim_back(st1, "123456789"); // result: "...value"

2.27.2sift()

char *sift(char *str, const char *trash_chars);
std::string &sift(std::string &str, const char *trash_chars);

Removes all characters from the set from the string. All nullptr values are treated as an empty string.

char st[] = "..ab.c..d.e.";
__vic::sift(st, ".");
assert(std::strcmp(st, "abcde") == 0);

2.27.3sift_if()

template<class Pred>
char *sift(char *str, Pred pred);
template<class Pred>
std::string &sift(std::string &str, Pred pred);

Removes all characters satify the predicate pred. All nullptr values are treated as an empty string.

2.27.4pad_front()

std::string &pad_front(std::string &str, size_t size, char pad_ch = ' ');
char *pad_front(char *str, size_t size, char pad_ch = ' ');

Complements the string up to length size by adding the required number of pad_ch chars to the beginning. Nothing happens if str length is equal or greather than size or the pointer is null. Returns str.

2.27.5pad_back()

std::string &pad_back(std::string &str, size_t size, char pad_ch = ' ');
char *pad_back(char *str, size_t size, char pad_ch = ' ');

Complements the string up to length size by adding the required number of pad_ch chars to the end. Nothing happens if str length is equal or greather than size or the pointer is null. Returns str.

2.27.6starts_with()

bool starts_with(const char *s, char pref);
bool starts_with(const char *s, const char *pref);
bool starts_with(const char *s, const char *pref, size_t pref_len);

#if __cpp_lib_string_view // C++17
bool starts_with(std::string_view s, char pref);
bool starts_with(std::string_view s, std::string_view pref);
bool starts_with(std::string_view s, const char *pref);
#else // until C++17
bool starts_with(const std::string &s, char pref);
bool starts_with(const std::string &s, const char *pref);
bool starts_with(const std::string &s, const std::string &pref);
bool starts_with(const std::string &s, const char *pref, size_t pref_len);
#endif

bool starts_with(const char *s, size_t s_len, char pref);
bool starts_with(const char *s, size_t s_len, const char *pref);
bool starts_with(const char *s, size_t s_len, const char *pref, size_t pref_len);

Returns true if string s starts with the specified prefix.

2.27.7ends_with()

#if __cpp_lib_string_view // C++17
bool ends_with(std::string_view s, char suff);
bool ends_with(std::string_view s, std::string_view suff);
#else // until C++17
bool ends_with(const char *s, char suff);
bool ends_with(const char *s, const char *suff);
bool ends_with(const char *s, const char *suff, size_t suff_len);
bool ends_with(const char *s, size_t s_len, const char *suff);

bool ends_with(const std::string &s, char suff);
bool ends_with(const std::string &s, const char *suff);
bool ends_with(const std::string &s, const std::string &suff);
bool ends_with(const std::string &s, const char *suff, size_t suff_len);
#endif

bool ends_with(const char *s, size_t s_len, char suff);
bool ends_with(const char *s, size_t s_len, const char *suff, size_t suff_len);

Returns true if string s ends with the specified suffix.

2.28__vic/tchar.h

Generic functions to manipulate C-strings regardless of the underlying char-type, like std::char_traits<>. All the functions are located within __vic::tchar namespace.

Most of the functions are just generic redirectors to calls like strcpy, wcscpy, et al. Searching functions have more intelligible names that ones in the C-library and unified parameters: they always take pointers and never indices. Also the set of the functions is complemented with "logically symmetrical" ones missed in the standard library. Searching functions return nullptr in case of failure.

template<class charT>
charT *generic_dup(const charT *st)
{
    namespace tchar = __vic::tchar;

    charT *st_copy = new charT[tchar::length(st) + 1];
    tchar::copy(st_copy, st);
    return st_copy;
}

2.28.1tchar::length()

template<class charT>
size_t tchar::length(const charT *str);

String length in elements. Generic strlen / wcslen.

2.28.2tchar::empty()

template<class charT>
bool tchar::empty(const charT *str);

Checks if str is nullptr or has no characters.

2.28.3tchar::end()

namespace tchar {

template<class charT>
const charT *end(const charT *str);

template<class charT>
charT *end(charT *str);

}

Pointer to the NULL-terminator. Generic strchr(str, '\0') / wcschr(str, L'\0').

2.28.4tchar::compare()

template<class charT>
int tchar::compare(const charT *str1, const charT *str2);

Compare two strings. Generic strcmp / wcscmp.

2.28.5tchar::equal()

template<class charT>
bool tchar::equal(const charT *str1, const charT *str2);

Checks if two strings are equal.

2.28.6tchar::copy()

template<class charT>
charT *tchar::copy(charT *dest, const charT *src);

Copy string. Generic strcpy / wcscpy.

2.28.7tchar::move()

template<class charT>
charT *tchar::move(charT *dest, const charT *src);

Move the string in memory (memmove).

2.28.8tchar::concat()

template<class charT>
charT *tchar::concat(charT *dest, const charT *src);

Concatenate two strings. Generic strcat / wcscat.

2.28.9tchar::find()

namespace tchar {

template<class charT>
const charT *find(const charT *str, charT ch);

template<class charT>
charT *find(charT *str, charT ch);

template<class charT>
const charT *find(const charT *str, const charT *sub);

template<class charT>
charT *find(charT *str, const charT *sub);

}

Find the first occurrence of the character or substring. Generic strchr / wcschr / strstr / wcsstr.

2.28.10tchar::rfind()

namespace tchar {

template<class charT>
const charT *rfind(const charT *str, charT ch);

template<class charT>
charT *rfind(charT *str, charT ch);

}

Find the last occurrence of the character. Generic strrchr / wcsrchr.

2.28.11tchar::find_if()

namespace tchar {

template<class charT, class Pred>
const charT *find_if(const charT *str, Pred pred);

template<class charT, class Pred>
charT *find_if(charT *str, Pred pred);

}

Find the first occurrence of the character that satisfies the specified predicate.

2.28.12tchar::find_if_not()

namespace tchar {

template<class charT, class Pred>
const charT *find_if_not(const charT *str, Pred pred);

template<class charT, class Pred>
charT *find_if_not(charT *str, Pred pred);

}

Find the first occurrence of the character that doesn't satisfy the specified predicate.

2.28.13tchar::rfind_if()

namespace tchar {

template<class charT, class Pred>
const charT *rfind_if(const charT *str, Pred pred);

template<class charT, class Pred>
charT *rfind_if(charT *str, Pred pred);

}

Find the last occurrence of the character that satisfies the specified predicate.

2.28.14tchar::rfind_if_not()

namespace tchar {

template<class charT, class Pred>
const charT *rfind_if_not(const charT *str, Pred pred);

template<class charT, class Pred>
charT *rfind_if_not(charT *str, Pred pred);

}

Find the last occurrence of the character that doesn't satisfy the specified predicate.

2.28.15tchar::find_first_of()

namespace tchar {

template<class charT>
const charT *find_first_of(const charT *str, const charT *set);

template<class charT>
charT *find_first_of(charT *str, const charT *set);

}

Find the first occurrence of the character from the specified set. Generic strpbrk / wcspbrk.

2.28.16tchar::find_first_not_of()

namespace tchar {

template<class charT>
const charT *find_first_not_of(const charT *str, const charT *set);

template<class charT>
charT *find_first_not_of(charT *str, const charT *set);

}

Find the first occurrence of the character absent in the specified set. Generic strspn / wcsspn.

2.28.17tchar::find_last_of()

namespace tchar {

template<class charT>
const charT *find_last_of(const charT *str, const charT *set);

template<class charT>
charT *find_last_of(charT *str, const charT *set);

}

Find the last occurrence of the character from the specified set.

2.28.18tchar::find_last_not_of()

namespace tchar {

template<class charT>
const charT *find_last_not_of(const charT *str, const charT *set);

template<class charT>
charT *find_last_not_of(charT *str, const charT *set);

}

Find the last occurrence of the character absent in the specified set.

2.28.19tchar::skip()

namespace tchar {

template<class charT>
const charT *skip(const charT *str, charT ch);

template<class charT>
charT *skip(charT *str, charT ch);

}

Skip all occurrences of the specified character and return the pointer. Pointer to NULL-terminator is returned if no other characters is presented.

2.29__vic/thread.h

Threads support.

2.29.1thread

class thread : private non_copyable
{
public:
    class id;
    using native_handle_type = <implementation-defined>;

    thread();
    virtual ~thread();

    // BEGIN C++11
    thread(thread &&o) noexcept;
    thread &operator=(thread &&o) noexcept;
    // END C++11

    void start();
    void cancel();
    void join();

    bool alive() const;
    bool joinable() const;

    id get_id() const;
    native_handle_type handle() const;
protected:
    virtual void worker() = 0;
};

Abstract base class for thread objects. Implements "Active object" pattern. Inherit it and define worker() function which content will be executed in the new thread after start() call. Then at some point in your program you must call join() to free OS resources associated with the spawned thread.

thread()

~thread()

thread(thread &&o) noexcept [C++11]

thread &operator=(thread &&o) noexcept [C++11]

void start()

void cancel()

void join()

bool alive() const

bool joinable() const

id get_id() const

native_handle_type handle() const

2.29.2thread::id

class thread::id
{
public:
    id();
    explicit operator bool() const;
    native_handle_type handle() const;
};
bool operator==(thread::id a, thread::id b);
bool operator!=(thread::id a, thread::id b);

Unique thread ID. It can hold a value associated with some thread or the special distinct value not associated with any thread.

id()

explicit operator bool() const

native_handle_type handle() const

bool operator==(thread::id a, thread::id b)

bool operator!=(thread::id a, thread::id b)

2.29.3this_thread

namespace this_thread
{
    thread::id get_id();
    void sleep_ms(unsigned msec);
}

Set of the functions to control the current (calling) thread.

thread::id get_id()

void sleep_ms(unsigned msec)

2.30__vic/throw_errno.h

2.30.1throw_errno()

[[noreturn]] void throw_errno(const char *prompt);
[[noreturn]] void throw_errno(const char *prompt, int err_no);

Throw an exception with global errno value or given err_no correspondingly. Default exception type is libc_error at the moment but can be changed at link time by overriding this functions. For example std::system_error can be used. Just create cpp-file with the following content in your project:

#include<__vic/throw_errno.h>
#include<system_error>

//----------------------------------------------------------------------------
// Override library functions to throw std::system_error
//----------------------------------------------------------------------------
void __vic::throw_errno(const char *prompt, int err_no)
{
    throw std::system_error(err_no, std::system_category(), prompt);
}
//----------------------------------------------------------------------------

It's enough to override only one functions because the second one just calls throw_errno(prompt, errno).

ssize_t written = ::write(fd, buf, buf_size);
if(written < 0) __vic::throw_errno("write");
// ...

2.31__vic/to_text.h

Generic converters to some text representation.

2.31.1to_text_append()

void to_text_append(long long n, std::string &str);
void to_text_append(long n, std::string &str);
void to_text_append(int n, std::string &str);
void to_text_append(short n, std::string &str);
void to_text_append(signed char n, std::string &str);

void to_text_append(unsigned long long n, std::string &str);
void to_text_append(unsigned long n, std::string &str);
void to_text_append(unsigned n, std::string &str);
void to_text_append(unsigned short n, std::string &str);
void to_text_append(unsigned char n, std::string &str);

void to_text_append(long double n, std::string &str);
void to_text_append(double n, std::string &str);
void to_text_append(float n, std::string &str);

void to_text_append(bool f, std::string &str);

void to_text_append(const void *p, std::string &str);

void to_text_append(const std::string &st, std::string &s);
void to_text_append(const char *st, std::string &s);
void to_text_append(char ch, std::string &s);

#if __cpp_lib_string_view // C++17
void to_text_append(std::string_view sv, std::string &s);
#endif

Converts the specified first argument to some text representation and appends it to the second argument.

This function is a customization point (like std::swap) for the library. Users can define additional overloads for own types (in the same namespace where the type is defined) in order to "teach" the library how to create a text from the value of the specified type.

void to_text_append(long long n, std::string &str)

void to_text_append(long n, std::string &str)

void to_text_append(int n, std::string &str)

void to_text_append(short n, std::string &str)

void to_text_append(signed char n, std::string &str)

void to_text_append(unsigned long long n, std::string &str)

void to_text_append(unsigned long n, std::string &str)

void to_text_append(unsigned n, std::string &str)

void to_text_append(unsigned short n, std::string &str)

void to_text_append(unsigned  char n, std::string &str)

void to_text_append(long double n, std::string &str)

void to_text_append(double n, std::string &str)

void to_text_append(float n, std::string &str)

void to_text_append(bool f, std::string &str)

void to_text_append(const void *p, std::string &str)

void to_text_append(const std::string &st, std::string &s)

void to_text_append(const char *st, std::string &s)

void to_text_append(char ch, std::string &s)

void to_text_append(std::string_view sv, std::string &s) [C++17]

int n = 5;
std::string st = "n = ";
__vic::to_text_append(n, st);
assert(st == "n = 5");

2.32__vic/type_traits.h

Template metaprogramming support.

All the predicate metafunctions have boolean member value and, usually, derived from integral_constant.

All the type transformer metafunctions have type member type containing the conversion result.

All of the template aliases are available only in C++11 mode.

2.32.1integral_constant

template<class T, T Val>
struct integral_constant
{
    using value_type = T;
    using type = integral_constant<T, Val>;

    static constexpr T value = Val;
};

The topmost base class of the most metafunctions.

2.32.2true_type

using true_type = integral_constant<bool, true>;

Base class for predicate metafunctions that have value true.

2.32.3false_type

using false_type = integral_constant<bool, false>;

Base class for predicate metafunctions that have value false.

2.32.4is_same

template<class T1, class T2> struct is_same;

A predicate. True if T1 and T2 are exactly the same type.

2.32.5is_const

template<class T> struct is_const;

A predicate. True if T has const qualifier.

2.32.6is_byte

template<class T> struct is_byte;

A predicate. True, if T is a type representing byte:

• char
• unsigned char
• std::byte [C++17]
• char8_t [C++20]

2.32.7byte_cast()

template<class To, class From>
constexpr To byte_cast(From v);

Casts value of From type to To type if both types are byte types (see is_byte).

2.32.8is_signed_integer

template<class T> struct is_signed_integer;

A predicate. True if T is a one of the "standard signed integer types" (see the Standard).

2.32.9is_unsigned_integer

template<class T> struct is_unsigned_integer;

A predicate. True if T is a one of the "standard unsigned integer types" (see the Standard).

2.32.10conjunction [C++11]

template<class... B> struct conjunction;

A predicate. The logical conjunction of the predicates B.... False iff one of the B... is false.

2.32.11disjunction [C++11]

template<class... B> struct disjunction;

A predicate. The logical disjunction of the predicates B.... True iff one of the B... is true.

2.32.12negation

template<class B> struct negation;

A predicate. The logical negation of the predicate B.

2.32.13remove_const

template<class T> struct remove_const;
template<class T> using remove_const_t = typename remove_const<T>::type;

A type transformer. Removes the top-level const qualifier or just returns T if it doesn't have such qualifier.

2.32.14remove_volatile

template<class T> struct remove_volatile;
template<class T> using remove_volatile_t = typename remove_volatile<T>::type;

A type transformer. Removes the top-level volatile qualifier or just returns T if it doesn't have such qualifier.

2.32.15remove_cv

template<class T> struct remove_cv;
template<class T> using remove_cv_t = typename remove_cv<T>::type;

A type transformer. Removes any top-level cv-qualifier or just returns T if it doesn't have such qualifiers.

2.32.16remove_reference

template<class T> struct remove_reference;
template<class T> using remove_reference_t = typename remove_reference<T>::type;

A type transformer. Returns the type referred by T or just T if it isn't a reference type.

2.32.17remove_cvref

template<class T> struct remove_cvref;
template<class T> using remove_cvref_t = typename remove_cvref<T>::type;

A type transformer. Applies remove_reference then remove_cv to T.

2.32.18remove_pointer

template<class T> struct remove_pointer;
template<class T> using remove_pointer_t = typename remove_pointer<T>::type;

A type transformer. Returns the type pointed by T or just T if it isn't a pointer type.

2.32.19conditional

template<bool Cond, class Then, class Else> struct conditional;

template<bool Cond, class Then, class Else>
using conditional_t = typename conditional<Cond, Then, Else>;

A type transformer. Returns Then if Cond == true. Else is returned otherwise.

2.32.20enable_if, disable_if

template<bool Test, class T = void>
struct enable_if
{
    using type = T;
};
template<class T>
struct enable_if<false, T> {};

template<bool Test, class T = void>
struct disable_if : enable_if<!Test, T> {};

Classical tools for SFINAE-magic.

2.32.21index_sequence, make_index_sequence [C++11]

template<size_t... I>
struct index_sequence
{
    static constexpr size_t size() { return sizeof...(I); }
};

template<size_t Size>
using make_index_sequence = index_sequence<0, 1, ..., Size-1>;

Implementation of C++14 std::index_sequence for C++11.

2.33__vic/unicode.h

Unicode support utilities.

2.33.1unicode_t

using unicode_t = char32_t; // since C++11
// or
using unicode_t = uint_least32_t; // C++98

Type able to store any Unicode code point.

2.33.2utf_transcode()

template<class UTFReader, class UTFWriter>
void utf_transcode(UTFReader r, UTFWriter w);

An algorithm that reads all code points of type unicode_t from UTFReader using r() and writes them to UTFWriter using w().

2.33.3Code point constants

constexpr unicode_t unicode_max = 0x10FFFF;
constexpr unicode_t unicode_bom = 0xFEFF;
constexpr unicode_t unicode_replacement_char = 0xFFFD;

Named constants for some useful Unicode code points.

2.34__vic/utf8/status.h

2.34.1utf8::status

enum class utf8::status : unsigned char
{
    ok = 0,
    eof,
    // Errors
    no_leading_byte,
    truncated_code_point,
    overlong_encoding,
    code_point_too_big
};
using utf8::status_t = utf8::status; // for C++98

Values returned by utf8::reader parse() function.

• ok - code point successfully read
• eof - no more code points to read
• no_leading_byte - continuation byte w/o leading
• truncated_code_point - incomplete multibyte sequence
• overlong_encoding - overlong encoded code point
• code_point_too_big - code point value is too big

2.34.2utf8::is_error()

constexpr bool utf8::is_error(utf8::status s);

Returns false for utf8::status::ok and utf8::status::eof values. true is returned otherwise.

2.35__vic/utf8/exceptions.h

namespace utf8 {

class bad_encoding; // public std::exception
    class no_leading_byte;
    class truncated_code_point;
    class overlong_encoding;
    class code_point_too_big;

} // namespace

Exception classes thrown by utf8::reader read() function. All exceptions are derived from abstract base class utf8::bad_encoding. See utf8::status for equivalent status codes.

2.36__vic/utf8/read_result.h

2.36.1utf8::read_result

class utf8::read_result
{
public:
    read_result(utf8::status_t s);
    read_result(unicode_t v);

    unicode_t value() const;
    utf8::status_t status() const;
    explicit operator bool() const;
};

A read result returned by utf8::reader::parse() function.

read_result(utf8::status_t s)

unicode_t value() const

utf8::status_t status() const

explicit operator bool() const

2.36.2utf8::convert_or_throw()

sread_result<unicode_t> utf8::convert_or_throw(utf8::read_result r);

Converts utf8::read_result to sread_result. Throws exception from __vic/utf8/exceptions.h if is_error(r.status()).

2.37__vic/utf8/reader.h

2.37.1utf8::reader

template<class ByteSReader>
class utf8::reader
{
public:
    using byte_reader_type = ByteSReader;
    ByteSReader &get_byte_reader();
    const ByteSReader &get_byte_reader() const;

    template<class... Args>
    explicit reader(Args&&... args); // since C++11

    reader(); // C++98 only
    explicit reader(ByteSReader r); // C++98 only

    utf8::read_result parse();
    sread_result<unicode_t> read()
    sread_result<unicode_t> operator()();
};

template<class ByteSReader>
utf8::reader<ByteSReader> utf8::make_reader(ByteSReader r);

UTF-8 code points from byte sequence reader. The sequence is accessed using ByteSReader which models sreader<unsigned char> (see S-readers).

ByteSReader &get_byte_reader()

const ByteSReader &get_byte_reader() const

template<class... Args>
explicit reader(Args&&... args) [C++11]

reader() [C++98 only]

explicit reader(ByteSReader r) [C++98 only]

utf8::read_result parse()

sread_result<unicode_t> read()

sread_result<unicode_t> operator()()

template<class ByteSReader>
utf8::reader<ByteSReader> utf8::make_reader(ByteSReader r)

#include<__vic/utf8/reader.h>
#include<__vic/sreaders/string.h>
#include<string>
#include<cstdint>
#include<iostream>

// C++11
using utf8_string_reader = __vic::utf8::reader<__vic::string_sreader>;

// C++98
struct utf8_string_reader : __vic::utf8::reader<__vic::string_sreader>
{
    explicit utf8_string_reader(const std::string &s)
        : __vic::utf8::reader<__vic::string_sreader>(__vic::string_sreader(s)) {}
};

void print_utf8_code_points(const string &s)
{
    utf8_string_reader r(s);
    while(__VIC_SREAD_RESULT(unicode_t) cp = r())
        std::cout << uint_least32_t(cp.value()) << '\n';
}

2.38__vic/utf8/writer.h

2.38.1utf8::writer

template<class ByteSWriter>
class utf8::writer
{
public:
    using byte_writer_type = ByteSWriter;
    ByteSWriter &get_byte_writer();
    const ByteSWriter &get_byte_writer() const;

    template<class... Args>
    explicit writer(Args&&... args); // since C++11

    writer(); // C++98 only
    explicit writer(ByteSWriter w); // C++98 only

    void write(unicode_t cp);
    void operator()(unicode_t cp);
};

template<class ByteSWriter>
utf8::writer<ByteSWriter> utf8::make_writer(ByteSWriter w);

UTF-8 code points to byte sequence writer. ByteSWriter which models swriter<unsigned char> (see S-writers) is used as a byte output.

ByteSWriter &get_byte_writer()

const ByteSWriter &get_byte_writer() const

template<class... Args>
explicit writer(Args&&... args) [C++11]

writer() [C++98 only]

explicit writer(ByteSWriter r) [C++98 only]

void write(unicode_t cp)

void operator()(unicode_t cp)

template<class ByteSWriter>
utf8::writer<ByteSWriter> utf8::make_writer(ByteSWriter w)

#include<__vic/utf8/writer.h>
#include<__vic/swriters/string.h>
#include<string>
#include<vector>

// C++11
using utf8_string_writer = __vic::utf8::writer<__vic::string_swriter>;

// C++98
struct utf8_string_writer : __vic::utf8::writer<__vic::string_swriter>
{
    explicit utf8_string_writer(std::string &s)
        : __vic::utf8::writer<__vic::string_swriter>(__vic::string_swriter(s)) {}
};

std::string encode_utf8(const std::vector<__vic::unicode_t> &code_points)
{
    std::string utf8_res;
    utf8_string_writer w(utf8_res);
    for(auto cp : code_points) w(cp);
    return utf8_res;
}

2.39__vic/utf16/defs.h

2.39.1utf16::code_unit_t

namespace utf16 {

using code_unit_t = char16_t; // since C++11
// or
using code_unit_t = uint_least16_t; // C++98

} // namespace

UTF-16 code unit type.

2.40__vic/utf16/status.h

2.40.1utf16::status

enum class utf16::status : unsigned char
{
    ok = 0,
    eof,
    // Errors
    truncated_code_unit,
    truncated_code_point,
    invalid_sequence
};
using utf16::status_t = utf16::status; // for C++98

Values returned by utf16::reader parse() function.

• ok - code point successfully read
• eof - no more code points to read
• truncated_code_unit - incomplete code unit
• truncated_code_point - incomplete code point
• invalid_sequence - the bytes don't represent any valid UTF-16 code point

2.40.2utf16::is_error()

constexpr bool utf16::is_error(utf16::status s);

Returns false for utf16::status::ok and utf16::status::eof values. true is returned otherwise.

2.41__vic/utf16/exceptions.h

namespace utf16 {

class bad_encoding; // public std::exception
    class truncated_code_unit;
    class truncated_code_point;
    class invalid_sequence;

} // namespace

Exception classes thrown by utf16::reader read() function. All exceptions are derived from abstract base class utf16::bad_encoding. See utf16::status for equivalent status codes.

2.42__vic/utf16/read_result.h

2.42.1utf16::read_result

class utf16::read_result
{
public:
    read_result(utf16::status_t s)
    read_result(unicode_t v);

    unicode_t value() const;
    utf16::status_t status() const;
    explicit operator bool() const;
};

A read result returned by utf16::reader::parse() function.

read_result(utf16::status_t s)

unicode_t value() const

utf16::status_t status() const

explicit operator bool() const

2.42.2utf16::read_unit_result

class utf16::read_unit_result
{
public:
    read_unit_result(utf16::status_t s)
    read_unit_result(utf16::code_unit_t v);

    utf16::code_unit_t value() const;
    utf16::status_t status() const;
    explicit operator bool() const;
};

The same as utf16::read_result but for utf16::code_unit_t.

2.42.3utf16::convert_or_throw()

sread_result<unicode_t> utf16::convert_or_throw(utf16::read_result r);

Converts utf16::read_result to sread_result. Throws exception from __vic/utf16/exceptions.h if is_error(r.status()).

2.43__vic/utf16/reader.h

2.43.1utf16::reader

template<class CodeUnitReader>
class utf16::reader
{
public:
    using code_unit_reader_type = CodeUnitReader;
    CodeUnitReader &get_code_unit_reader();
    const CodeUnitReader &get_code_unit_reader() const;

    template<class... Args>
    explicit reader(Args&&... args);  // since C++11

    reader(); // C++98 only
    explicit reader(CodeUnitReader r); // C++98 only

    utf16::read_result parse();
    sread_result<unicode_t> read();
    sread_result<unicode_t> operator()();
};

template<class CodeUnitReader>
utf16::reader<CodeUnitReader> utf16::make_reader(CodeUnitReader r);

UTF-16 code points from 2-byte utf16::code_unit_t sequence reader. The sequence is accessed using the special reader of the following structure:

class CodeUnitReader
{
public:
    utf16::read_unit_result operator()();
};

utf16::read_unit_result operator()()

CodeUnitReader &get_code_unit_reader()

const CodeUnitReader &get_code_unit_reader() const

template<class... Args>
explicit reader(Args&&... args) [C++11]

reader() [C++98 only]

explicit reader(CodeUnitReader r) [C++98 only]

utf16::read_result parse()

sread_result<unicode_t> read()

sread_result<unicode_t> operator()()

template<class CodeUnitReader>
utf16::reader<CodeUnitReader> utf16::make_reader(CodeUnitReader r)

#include<__vic/utf16/reader.h>
#include<__vic/sreaders/string.h>
#include<string>
#include<cstdint>
#include<iostream>

class u16string_code_unit_reader
{
    __vic::basic_string_sreader<char16_t> r;
public:
    explicit u16string_code_unit_reader(const std::u16string &s) : r(s) {}

    __vic::utf16::read_unit_result operator()()
    {
        if(__vic::sread_result<__vic::utf16::code_unit_t> u = r())
            return u.value();
        return __vic::utf16::status::eof;
    }
};

void print_utf16_code_points(const std::u16string &s)
{
    __vic::utf16::reader<u16string_code_unit_reader> r(s);
    __vic::unicode_t cp;
    while(__VIC_SREAD_RESULT(unicode_t) cp = r())
        std::cout << uint_least32_t(cp.value()) << '\n';
}

2.44__vic/utf16/writer.h

2.44.1utf16::writer

template<class CodeUnitSWriter>
class utf16::writer
{
public:
    using code_unit_writer_type = CodeUnitSWriter;
    CodeUnitSWriter &get_code_unit_writer();
    const CodeUnitSWriter &get_code_unit_writer() const;

    template<class... Args>
    explicit writer(Args&&... args); // since C++11

    writer(); // C++98 only
    explicit writer(CodeUnitSWriter w); // C++98 only

    void write(unicode_t cp);
    void operator()(unicode_t cp);
};

template<class CodeUnitSWriter>
utf16::writer<CodeUnitSWriter> utf16::make_writer(CodeUnitSWriter w);

UTF-16 code points to 2-byte utf16::code_unit_t sequence writer. CodeUnitSWriter which models swriter<utf16::code_unit_t> (see S-writers) is used as a code units output.

CodeUnitSWriter &get_code_unit_writer()

const CodeUnitSWriter &get_code_unit_writer() const

template<class... Args>
explicit writer(Args&&... args) [C++11]

writer() [C++98 only]

explicit writer(CodeUnitSWriter r) [C++98 only]

void write(unicode_t cp)

void operator()(unicode_t cp)

template<class CodeUnitSWriter>
utf16::writer<CodeUnitSWriter> utf16::make_writer(CodeUnitSWriter w)

#include<__vic/utf16/writer.h>
#include<__vic/swriters/string.h>
#include<string>
#include<vector>

std::u16string encode_utf16(const std::vector<__vic::unicode_t> &code_points)
{
    std::u16string utf16_res;
    __vic::utf16::writer<__vic::basic_string_swriter<char16_t>> w(utf16_res);
    for(auto cp : code_points) w(cp);
    return utf16_res;
}

2.45__vic/waitable_event.h

2.45.1waitable_event

class waitable_event : private non_copyable
{
public:
    explicit waitable_event(bool signaled = false);
    ~waitable_event();

    void set();
    void reset();
    bool signaled() const;

    void wait();
    bool wait_ms(unsigned msec);

    // BEGIN C++11
    template<class Rep, class Period>
    bool wait_for(const std::chrono::duration<Rep,Period> &d);
    template<class Clock, class Duration>
    bool wait_until(const std::chrono::time_point<Clock,Duration> &t);
    // END C++11
};

A synchronization object like Event Object in Windows. Can be in ether of two states: signaled or nonsignaled. A thread can effectively wait for the signaled state using one of the available wait-functions (with minimal system resources consumption).

explicit waitable_event(bool signaled = false)

bool signaled() const

void set()

void reset()

void wait()

bool wait_ms(unsigned msec)

template<class Rep, class Period>
bool wait_for(const std::chrono::duration<Rep,Period> &d) [C++11]

template<class Clock, class Duration>
bool wait_until(const std::chrono::time_point<Clock,Duration> &t) [C++11]

2.46__vic/windows/bitmap.h

2.46.1windows::Bitmap

class windows::Bitmap
{
public:
    Bitmap() = default;
    explicit Bitmap(HBITMAP h);

    static Bitmap CreateCompatible(HDC hdc, int w, int h);

    bool DeleteNT() noexcept;
    void Delete();

    void ClearHandle();
    HBITMAP Handle() const;
    void Handle(HBITMAP h);
    operator HBITMAP() const;
};

C++ wrapper for Win32 API HBITMAP.

Bitmap() = default

explicit Bitmap(HBITMAP h)

static Bitmap CreateCompatible(HDC hdc, int w, int h)

bool DeleteNT() noexcept

void Delete()

void ClearHandle()

HBITMAP Handle() const

operator HBITMAP() const

void Handle(HBITMAP h)

2.47__vic/windows/critical_section.h

2.47.1windows::CriticalSection

class windows::CriticalSection : private non_copyable
{
public:
    CriticalSection();
    explicit CriticalSection(DWORD dwSpinCount); // _WIN32_WINNT >= 0x0403
    ~CriticalSection();

    void Enter();
    bool TryEnter();
    void Leave() noexcept;

    ::CRITICAL_SECTION *handle();
    const ::CRITICAL_SECTION *handle() const;
};

A C++ wrapper for Win32 API CRITICAL_SECTION.

CriticalSection()

explicit CriticalSection(DWORD dwSpinCount) [_WIN32_WINNT >= 0x0403]

~CriticalSection()

void Enter()

bool TryEnter()

void Leave() noexcept

2.47.2windows::CSGuard

class windows::CSGuard : private non_copyable
{
public:
    enum adopt_t { adopt };

    explicit CSGuard(::CRITICAL_SECTION &cs);
    CSGuard(::CRITICAL_SECTION &cs, adopt_t);

    explicit CSGuard(CriticalSection &cs);
    CSGuard(CriticalSection &cs, adopt_t);

    ~CSGuard();
};

A scoped lock guard. Works with ::CRITICAL_SECTION as well as with windows::CriticalSection objects.

explicit CSGuard(::CRITICAL_SECTION &cs)

explicit CSGuard(CriticalSection &cs)

CSGuard(::CRITICAL_SECTION &cs, adopt_t)

CSGuard(CriticalSection &cs, adopt_t)

~CSGuard()

// Typical usage
void reentrant_function()
{
    static __vic::windows::CriticalSection cs;
    __vic::windows::CSGuard guard(cs);
    // Critical section code until the end of the block
    ...
}

// Usage of the adopt-constructor
__vic::windows::CriticalSection cs;
if(cs.TryEnter()) // Try to enter the critical section
{
    // Success
    using __vic::windows::CSGuard;
    CSGuard guard(cs, CSGuard::adopt);
    // Critical section code until the end of the block
    ...
}
else
{
    // The critical section is busy
    ...
}

2.48__vic/windows/dc.h

C++ wrappers for Win32 GDI device context (DC).

2.48.1windows::DC

class windows::DC
{
public:
    DC() = default;
    explicit DC(HDC hdc);

    static DC CreateCompatible(HDC hdc);

    bool ReleaseNT(HWND hwnd) noexcept;
    void Release(HWND hwnd);
    bool DeleteNT() noexcept;
    void Delete();

    int GetHorzRes() const;
    int GetVertRes() const;
    HWND GetWindow() const;
    HGDIOBJ GetCurrentObject(UINT uObjType) const;
    HBRUSH GetCurrentBrush() const;
    HPEN GetCurrentPen() const;
    HFONT GetCurrentFont() const;
    HBITMAP GetCurrentBitmap() const;

    void Select(HGDIOBJ hObj); // not a region object
    void Select(HRGN hReg);

    COLORREF SetPixel(int x, int y, COLORREF c);
    bool MoveTo(int x, int y, POINT *p = 0);
    bool LineTo(int x, int y);
    bool PolyBezier(const POINT *lppt, DWORD cPoints);
    bool FillRect(const RECT &rect, HBRUSH hbr);

    bool BlitTo(HDC dcDest, int x, int y,
                            int w, int h, DWORD dwRop = SRCCOPY) const;
    bool BlitTo(HDC dcDest, const RECT &r, DWORD dwRop = SRCCOPY) const;

    void ClearHandle();
    HDC Handle() const;
    void Handle(HDC hdc);
    operator HDC() const;
};

General purpose HDC wrapper. Use windows::ClientDC instead of ::ReleaseDC(). Use windows::PaintDC instead of ::BeginPaint()/::EndPaint().

DC() = default

explicit DC(HDC hdc)

static DC CreateCompatible(HDC hdc)

bool ReleaseNT(HWND hwnd) noexcept

void Release(HWND hwnd)

bool DeleteNT() noexcept

void Delete()

int GetHorzRes() const

int GetVertRes() const

HWND GetWindow() const

HGDIOBJ GetCurrentObject(UINT uObjType) const

HBRUSH GetCurrentBrush() const

HPEN GetCurrentPen() const

HFONT GetCurrentFont() const

HBITMAP GetCurrentBitmap() const

void Select(HGDIOBJ hObj)

void Select(HRGN hReg)

COLORREF SetPixel(int x, int y, COLORREF c)

bool MoveTo(int x, int y, POINT *p = 0)

bool LineTo(int x, int y)

bool PolyBezier(const POINT *lppt, DWORD cPoints)

bool FillRect(const RECT &rect, HBRUSH hbr)

bool BlitTo(HDC dcDest, int x, int y, int w, int h, DWORD dwRop = SRCCOPY) const

bool BlitTo(HDC dcDest, const RECT &r, DWORD dwRop = SRCCOPY) const

void ClearHandle()

HDC Handle() const

operator HDC() const

void Handle(HDC hdc)

2.48.2windows::ClientDC

class windows::ClientDC : public windows::DC, private non_copyable
{
public:
    explicit ClientDC(HWND hwnd);
    ClientDC(HDC hdc, HWND hwnd);
    ~ClientDC();
};

RAII-wrapper. Calls ::ReleaseDC() in destructor.

explicit ClientDC(HWND hwnd)

ClientDC(HDC hdc, HWND hwnd)

~ClientDC()

2.48.3windows::PaintDC

class windows::PaintDC :
    public windows::DC, public PAINTSTRUCT, private non_copyable
{
public:
    explicit PaintDC(HWND hwnd);
    ~PaintDC();
};

Wrapper for PAINTSTRUCT and ::BeginPaint()/::EndPaint() calls.

explicit PaintDC(HWND hwnd)

~PaintDC()

2.49__vic/windows/error.h

Windows-specific error handling tools.

2.49.1windows::error

class windows::error : public std::exception
{
public:
    explicit error(DWORD err_code = ::GetLastError());
    explicit error(const char *prompt, DWORD err_code = ::GetLastError());

    const char *what() const noexcept;
    DWORD code() const;
};

Wrapper for Windows system error codes returned by Win32 API function GetLastError(). See libc_error for reference.

2.50__vic/windows/event.h

2.50.1windows::Event

class windows::Event : private non_copyable
{
public:
    explicit Event(bool bManualReset,
         bool bInitialSignaled = false, LPCWSTR lpName = nullptr);
    ~Event();

    void Set();
    void Reset();
    bool Wait(DWORD timeout = INFINITE) const;
    bool wait_for(std::chrono::milliseconds ms) const; // C++11

    HANDLE handle() const;
};

Wrapper for Win32 API event synchronization object.

explicit Event(bool bManualReset, bool bInitialSignaled = false, LPCWSTR lpName = nullptr)

~Event()

void Set()

void Reset()

bool Wait(DWORD timeout = INFINITE) const

bool wait_for(std::chrono::milliseconds ms) const [C++11]

HANDLE handle() const

2.51__vic/windows/find_file.h

2.51.1windows::FindFile

class windows::FindFile : public WIN32_FIND_DATA, private non_copyable
{
public:
    FindFile();
    ~FindFile();

    bool FindFirst(LPCTSTR filename);
    bool FindNext();

    bool IsOpen() const;
    void Close();
    bool CloseNT() noexcept;
};

Wrapper for Win32 API FindFirstFile()/FindNextFile() functions. Special entries . and .. are newer included in the resulting set.

FindFile()

~FindFile()

bool FindFirst(LPCTSTR filename)

bool FindNext()

bool Close()

bool CloseNT() noexcept

2.52__vic/windows/handle.h

2.52.1windows::Handle

class windows::Handle
{
public:
    Handle() = default; // uninitialized
    constexpr Handle(HANDLE h);

    void Close();
    bool CloseNT() noexcept;
    static void Close(HANDLE h);

    bool Wait(DWORD timeout = INFINITE) const;

    bool IsInvalid() const;
    void SetInvalid();
    operator HANDLE() const;

    void swap(Handle &o) noexcept;
};

A C++ wrapper for Win32 API HANDLE.

Handle() = default

constexpr Handle(HANDLE h)

operator HANDLE() const

bool IsInvalid() const

void SetInvalid()

void Close()

static void Close(HANDLE h)

bool CloseNT() noexcept

bool Wait(DWORD timeout = INFINITE) const

void swap(Handle &o) noexcept

2.52.2windows::WaitAbandoned

struct windows::WaitAbandoned : public std::exception
{
    const char *what() const noexcept;
};

An exception class thrown by __vic::windows::Handle::Wait().

2.53__vic/windows/shadow_dc.h

2.53.1windows::ShadowDC

class windows::ShadowDC : public windows::DC, private non_copyable
{
public:
    ShadowDC();
    ~ShadowDC();

    void Create(HWND hwnd);
    void Create(HWND hwnd, int w, int h);
    void Destroy();
    bool IsCreated() const;
};

Virtual in-memory DC.

ShadowDC()

~ShadowDC()

void Create(HWND hwnd, int w, int h)

void Create(HWND hwnd)

void Destroy()

bool IsCreated() const

2.54__vic/windows/throw_last_error.h

2.54.1windows::throw_last_error()

[[noreturn]] void throw_last_error(const char *prompt);
[[noreturn]] void throw_last_error(const char *prompt, DWORD code);

Throw an exception with the global GetLastError() value or the given code correspondingly.

if(!CloseHandle(h)) __vic::windows::throw_last_error("CloseHandle");

2.54.2windows::throw_wsa_error()

[[noreturn]] void throw_wsa_error(const char *prompt);
[[noreturn]] void throw_wsa_error(const char *prompt, int code);

Same as windows::throw_last_error(), but for the error codes returned by WSAGetLastError().

2.55__vic/windows/wait_cursor.h

2.55.1windows::WaitCursor

class windows::WaitCursor : private non_copyable
{
public:
    explicit WaitCursor(HCURSOR h);
    ~WaitCursor();

    static HCURSOR GetDefault();
};

A RAII-wrapper. Temporarily replaces the mouse cursor with the one given in the constructor. The destructor restores the previous cursor.

explicit WaitCursor(HCURSOR h)

~WaitCursor()

static HCURSOR GetDefault()

using __vic::windows::WaitCursor;
static HCURSOR hWaitCursor = WaitCursor::GetDefault();
{
    WaitCursor _(hWaitCursor); // the cursor is replaced here by hWaitCursor
    some_long_processing();
    // here the destructor restores the cursor
}

2.56__vic/windows/wchar.h

UTF-8 <-> UTF-16 interconversion tools.

2.56.1windows::wstring

class windows::wstring : public std::wstring
{
public:
    wstring() = default;
    explicit wstring(size_type n) { reserve(n); }
    wstring(const wchar_t *st);
    wstring(std::wstring st);

    operator const wchar_t *() const { return c_str(); }
};

std::wstring with automatic conversion to const wchar_t *.

2.56.2windows::utf8to16()

windows::wstring windows::utf8to16(const char *s, size_t len);
#if __cpp_lib_string_view // C++17
windows::wstring windows::utf8to16(std::string_view s);
#else
windows::wstring windows::utf8to16(const char *s);
windows::wstring windows::utf8to16(const std::string &s);
#endif

UTF-8 to UTF-16 converter.

2.56.3windows::utf16to8()

std::string windows::utf16to8(const wchar_t *s, size_t len);
#if __cpp_lib_string_view // C++17
std::string windows::utf16to8(std::wstring_view s);
#else
std::string windows::utf16to8(const wchar_t *s);
std::string windows::utf16to8(const std::wstring &s);
#endif

UTF-16 to UTF-8 converter.

2.56.4windows::utf16to8_append()

std::string &windows::utf16to8_append(
                            const wchar_t *s, size_t len, std::string &res);
#if __cpp_lib_string_view // C++17
std::string &windows::utf16to8_append(std::wstring_view s, std::string &res);
#else
std::string &windows::utf16to8_append(const wchar_t *s, std::string &res);
std::string &windows::utf16to8_append(const std::wstring &s, std::string &res);
#endif

Same as windows::utf16to8() but appends the result to res. Returns a reference to res.

2.57__vic/windows/window.h

2.57.1windows::Window

class windows::Window
{
public:
    struct Class;
    struct CreateParams;

    Window() = default;
    explicit Window(HWND hwnd);

    static void Register(WNDCLASSEXW wcl);
    void Create(DWORD dwExStyle, LPCWSTR lpClassName, LPCWSTR lpWndName,
        DWORD dwStyle, int x, int y, int nWidth, int nHeight, HWND hWndParent,
        HMENU hMenu, HINSTANCE hInstance, void *lpParam = nullptr);
    void Create(const CREATESTRUCTW &cs);
    bool Destroy() noexcept;

    LRESULT SendMessage(UINT msg, WPARAM w = 0, LPARAM l = 0);

    void Update();
    bool Show(int nWinMode);
    void Redraw(const RECT *rect = 0, HRGN hrgn = 0,
                        UINT flags = RDW_INVALIDATE | RDW_UPDATENOW);

    void GetRect(RECT &r) const;
    RECT GetRect() const;
    void GetClientRect(RECT &r) const
    RECT GetClientRect() const;

    void SetText(LPCWSTR st);
    void SetText(const char *st);
    int GetText(LPWSTR st, int nMax) const;

    void SetPos(HWND hWndAfter, int x, int y, int w, int h, UINT uFlags);
    void SetPos(int x, int y, int w, int h);
    void SetSize(int w, int h);
    void SetClientAreaSize(int w, int h);
    void MoveTo(int x, int y);
    void MoveToCenter();

    HWND Handle() const;
    void Handle(HWND hwnd);
    operator HWND() const;
};

Thin wrapper for Win32 API HWND.

Window() = default

explicit Window(HWND hwnd)

static void Register(WNDCLASSEXW wcl)

void Create(DWORD dwExStyle, LPCWSTR lpClassName, LPCWSTR lpWndName,
    DWORD dwStyle, int x, int y, int nWidth, int nHeight, HWND hWndParent,
    HMENU hMenu, HINSTANCE hInstance, void *lpParam = nullptr)

void Create(const CREATESTRUCTW &cs)

bool Destroy() noexcept

LRESULT SendMessage(UINT msg, WPARAM w = 0, LPARAM l = 0)

void Update()

bool Show(int nWinMode)

void Redraw(const RECT *rect = 0, HRGN hrgn = 0,
        UINT flags = RDW_INVALIDATE | RDW_UPDATENOW)

void GetRect(RECT &r) const

RECT GetRect() const

void GetClientRect(RECT &r) const

RECT GetClientRect() const

void SetText(LPCWSTR st)

void SetText(const char *st)

int GetText(LPWSTR st, int nMax) const

void SetPos(HWND hWndAfter, int x, int y, int w, int h, UINT uFlags)

void SetPos(int x, int y, int w, int h)

void SetSize(int w, int h)

void SetClientAreaSize(int w, int h)

void MoveTo(int x, int y)

void MoveToCenter()

HWND Handle() const

operator HWND() const

void Handle(HWND hwnd)

// Skeleton Win32 API application
#include<__vic/windows/window.h>
#include<windows.h>
#include<exception>

extern "C" LRESULT CALLBACK WindowFunc(
    HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
    switch(msg)
    {
        case WM_DESTROY:
            PostQuitMessage(0); break;
        default:
            return DefWindowProc(hwnd, msg, wParam, lParam);
    }
    return 0;
}
WPARAM skeleton_win32_app(int nWinMode)
{
    using __vic::windows::Window;
    static wchar_t szWinClassName[] = L"TestAppClass";

     Window wnd;
     HINSTANCE hInstance = ::GetModuleHandle(0);
     HICON hIcon = LoadIcon(NULL, IDI_APPLICATION);
     Window::Register(Window::Class(hInstance, szWinClassName, WindowFunc)
        .Icon(hIcon)
        .SmallIcon(hIcon)
        .Cursor(LoadCursor(0, IDC_ARROW))
        .Background((HBRUSH) GetStockObject(GRAY_BRUSH))
    );
    wnd.Create(Window::CreateParams(hInstance,
        szWinClassName, L"Skeleton Win32 application"));
    wnd.Show(nWinMode);
    wnd.Update();
    return __vic::windows::MessageLoop();
}
int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR lpszArgs, int nWinMode)
{
    try
    {
        return skeleton_win32_app(nWinMode);
    }
    catch(const std::exception &ex)
    {
        __vic::windows::MsgBox(ex.what(),
            "Application error", MB_OK | MB_ICONERROR);
    }
    return 1;
}

2.57.2windows::Window::Class

struct windows::Window::Class : WNDCLASSEXW
{
    Class(HMODULE hInst, LPCWSTR name, WNDPROC wndProc)
    {
        cbSize = sizeof(WNDCLASSEXW);
        style = 0;
        lpfnWndProc = wndProc;
        cbClsExtra = cbWndExtra = 0;
        hInstance = hInst;
        hIcon = 0;
        hCursor = ::LoadCursorW(0, IDC_ARROW);
        hbrBackground = 0;
        lpszMenuName = 0;
        lpszClassName = name;
        hIconSm = 0;
    }
    Class &Style(UINT v) { style = v; return *this; }
    Class &ClsExtra(int v) { cbClsExtra = v; return *this; }
    Class &WndExtra(int v) { cbWndExtra = v; return *this; }
    Class &Instance(HINSTANCE v) { hInstance = v; return *this; }
    Class &Icon(HICON v) { hIcon = v; return *this; }
    Class &Cursor(HCURSOR v) { hCursor = v; return *this; }
    Class &Background(HBRUSH v) { hbrBackground = v; return *this; }
    Class &MenuName(LPCWSTR v) { lpszMenuName = v; return *this; }
    Class &SmallIcon(HICON v) { hIconSm = v; return *this; }
};

Wrapper for WNDCLASSEXW.

using __vic::windows::Windows;

Window::Register(Window::Class(hInstance, WndClassName, wndProc)
    .Icon(hIcon)
    .SmallIcon(hIcon)
    .Cursor(::LoadCursor(nullptr, IDC_ARROW))
    .Background((HBRUSH) ::GetStockObject(LTGRAY_BRUSH))
);

2.57.3windows::Window::CreateParams

struct windows::Window::CreateParams : CREATESTRUCTW
{
    CreateParams(HMODULE hInst, LPCWSTR lpClsName, LPCWSTR lpWndName = nullptr)
    {
        lpCreateParams = 0;
        hInstance = hInst;
        hMenu = 0;
        hwndParent = HWND_DESKTOP;
        cy = cx = y = x = CW_USEDEFAULT;
        style = WS_OVERLAPPEDWINDOW;
        lpszName = lpWndName;
        lpszClass = lpClsName;
        dwExStyle = 0;
    }
    CreateParams &ExtraParam(void *v) { lpCreateParams = v; return *this; }
    CreateParams &Instance(HINSTANCE v) { hInstance = v; return *this; }
    CreateParams &Menu(HMENU v) { hMenu = v; return *this; }
    CreateParams &Parent(HWND v) { hwndParent = v; return *this; }
    CreateParams &Position(int X, int Y) { x = X; y = Y; return *this; }
    CreateParams &Dimension(int w, int h) { cx = w; cy = h; return *this; }
    CreateParams &Style(DWORD v) { style = v; return *this; }
    CreateParams &ExStyle(DWORD v) { dwExStyle = v; return *this; }
};

Wrapper for CREATESTRUCTW.

using __vic::windows::Windows;

Windows wnd;
wnd.Create(Window::CreateParams(hInstance, className, title).Position(x, y));

2.57.4windows::MsgBox()

int windows::MsgBox(HWND hwnd,
    const wchar_t *msg, const wchar_t *title = L"", int t = MB_OK);
int windows::MsgBox(
    const wchar_t *msg, const wchar_t *title = L"", int t = MB_OK);
int windows::MsgBox(HWND hwnd,
    const char *msg, const char *title = "", int t = MB_OK);
int windows::MsgBox(
    const char *msg, const char *title = "", int t = MB_OK)

Calls ::MessageBoxW() and returns the returned value. hwnd parameter is NULL (HWND_DESKTOP) when not specified. char-functions convert strings from UTF-8 to UTF-16.

2.57.5windows::MessageLoop()

WPARAM windows::MessageLoop(HWND hwnd = nullptr);

Calls ::GetMessage() while it returs nonzero (until WM_QUIT is read). Then calls ::TranslateMessage() and ::DispatchMessage() with the message. Returns MSG::wParam.

2.57.6windows::ProcessMessages()

bool windows::ProcessMessages(HWND hwnd = nullptr);

Like windows::MessageLoop() but returns when message queue is empty. Returns true if can be called again and false if WM_QUIT message was read.

3S-readers

template<class T>
interface sreader
{
    sreader(sreader &&o); or sreader(const sreader &o);
    sreader_result<T> auto operator()(); // throws on errors
};

sreader is a concept used by the library algorithms to read logical sequence of elements of type T element by element. It is a generalization and rework of the input iterator concept. In particular it handles streams, NULL-terminated strings and other sequences where end-iterator is meaningless or expensive to obtain better. At the same time, a traditional [begin,end) pair of iterators is just a particular case and fully and well handled by __vic::iterator_sreader adapter.

"sreader" is pronounced as "S-reader" where S stands for "Sequential", "Sequence" or "Stream".

When the particular class meets the requirements of this concept for some T it is said to model the sreader<T> concept.

Each sreader object has to be move- or copy-constructible.

sreader_result<T> auto operator()()

Values returned by sreaders (sreader_result) provide the following interface:

template<class T>
interface sreader_result
{
    explicit operator bool() const;
    T value() const;
};

An sreader read result contains a status of the read operation (success/failure) and the value read if the read was successful. The instances are (trivially) copy-constructible and copy-assignable.

sreader result types provide structured bindings support in the following form:

auto [value, ok] = reader();

Since C++98 lacks auto type specifiers, usage of different result types is impractical. In this language mode sreaders return sread_result type (or a type implicitly convertible to it).

explicit operator bool() const

T value() const

// Basic usage (C++11+)
while(auto res = reader())
{
    // Use res.value() ...
}

// Using structured bindings (C++17+)
for(;;)
{
    auto [value, ok] = reader();
    if(!ok) break;
    // Use value ...
}

// C++26+
while(auto [value, _] = reader())
{
    // Use value ...
}

// Legacy C++98
while(__VIC_SREAD_RESULT(T) res = reader())
{
    // Use res.value() of type T ...
}

3.1__vic/sreaders/defs.h

3.1.1sreader [C++20]

template<class R, class T>
concept sreader =
    std::movable<R> &&
    requires(R r) {
        {r()} -> sreader_result<T>;
    };

A C++ concept for sreaders.

3.1.2byte_sreader [C++20]

template<class R, class T>
concept byte_sreader = sreader<R, T> && is_byte<T>::value;

A C++ concept for sreaders that read bytes.

3.1.3sreader_result [C++20]

template<class R, class T>
concept sreader_result =
    std::semiregular<R> &&
    requires(R r) {
        bool{r};
        {r.value()} -> std::same_as<T>;
    };

A C++ concept for sreader results.

3.1.4sreader_value_t

template<class SReaderResult>
struct sreader_value
{
    typename type;
};

template<class SReaderResult>
using sreader_value_t = typename sreader_value<SReaderResult>::type;

A metafunction returning the type returned by the value() member-function of the specified SReaderResult.

__vic::sreader_value<__vic::sread_result<int> >::type value; // int value;

3.1.5uchar_value()

template<class ByteSReaderResult>
unsigned char uchar_value(ByteSReaderResult r);

Returns the resulting byte value – r.value() – as an unsigned char.

This function is defined only if is_byte<sreader_value_t<ByteSReaderResult>>::value == true.

3.2__vic/sreaders/result.h

3.2.1sread_result

template<class T>
class sread_result
{
public:
    sread_result();
    sread_result(sread_eof_t);
    sread_result(T v);

    explicit operator bool() const;
    T value() const;
};

template<>
class sread_result<unsigned char>
{
public:
    // All the members from the non-specialized version...

    // + Implicit converters:
    sread_result(sread_result<char> r);
    sread_result(sread_result<char8_t> r);
    sread_result(sread_result<std::byte> r);
};
unsigned char uchar_value(sread_result<unsigned char> r);

#if __cplusplus >= 201103L // C++11
#define __VIC_SREAD_RESULT(T) auto
#else // C++98
#define __VIC_SREAD_RESULT(T) ::__vic::sread_result<T>
#endif

A concrete type (template) that models sreader_result [C++20].

The sread_result<unsigned char> specialization is compatible (implicitly convertible) with any byte result type representation including:

• char
• unsigned char
• std::byte [C++17]
• char8_t [C++20]

__vic::sread_result<char> char_reader();

__vic::sread_result<unsigned char> res = char_reader(); // OK

The __VIC_SREAD_RESULT(T) macro is used in a code that is required to be C++98-compable to specify the return type instead of auto:

__VIC_SREAD_RESULT(char) result = chars_reader();

sread_result()

sread_result(sread_eof_t)

sread_result(T v)

explicit operator bool() const

T value() const

unsigned char uchar_value(sread_result<unsigned char> r)

3.2.2sread_eof

struct sread_eof_t;
inline constexpr sread_eof_t sread_eof;

The special value used to (implicitly) construct an unsuccessfull sread_result of any value type.

3.3Concrete sreaders

3.3.1iterator_sreader

#include<__vic/sreaders/iterator.h>

template<class InputIterator,
         class T = typename std::iterator_traits<InputIterator>::value_type>
class iterator_sreader
{
public:
    iterator_sreader(InputIterator begin, InputIterator end);
    sread_result<T> operator()();
    InputIterator position() const;
};

template<class InputIterator> iterator_sreader<InputIterator>
make_iterator_sreader(InputIterator begin, InputIterator end);

template<class T, class InputIterator> iterator_sreader<InputIterator,T>
make_iterator_sreader_for(InputIterator begin, InputIterator end);

An adapter for a traditional [begin,end) pair of iterators.

Additional position() function returns the current iterator position.

Can be created using constructor or one of make_... functions.

3.3.2iterator_sreader_n

#include<__vic/sreaders/iterator.h>

template<class InputIterator,
         class T = typename std::iterator_traits<InputIterator>::value_type>
class iterator_sreader_n
{
public:
    iterator_sreader_n(InputIterator begin, size_t n);
    sread_result<T> operator()();
    InputIterator position() const;
};

template<class InputIterator> iterator_sreader_n<InputIterator>
make_iterator_sreader_n(InputIterator begin, size_t n);

template<class T, class InputIterator> iterator_sreader_n<InputIterator,T>
make_iterator_sreader_n_for(InputIterator begin, size_t n);

An adapter for iterator + elements counter.

Additional position() function returns the current iterator position.

Can be created using constructor or one of make_... functions.

3.3.3container_sreader

#include<__vic/sreaders/container.h>

template<class Cont, class T = typename Cont::value_type>
class container_sreader
{
public:
    explicit container_sreader(const Cont &c);
    sread_result<T> operator()();
    typename Cont::const_iterator position() const;
};

template<class Cont>
container_sreader<Cont> make_scontainer_sreader(const Cont &c);

template<class T, class Cont>
container_sreader<Cont,T> make_container_sreader_for(const Cont &c);

An adapter for STL-style container classes with begin() and end() members.

Additional position() function returns the current iterator position.

Can be created using constructor or one of make_... functions.

3.3.4cstring_sreader

#include<__vic/sreaders/cstring.h>

template<class charT>
class basic_cstring_sreader
{
public:
    explicit basic_cstring_sreader(const charT *s);
    sread_result<charT> operator()();
    const charT *position() const;
};
using cstring_sreader = basic_cstring_sreader<char>;

template<class charT>
basic_cstring_sreader<charT> make_cstring_sreader(const charT *s);

An adapter for NULL-terminated C-style strings.

Additional position() function returns the current pointer position.

Can be created using constructor or make_... function.

3.3.5string_sreader

#include<__vic/sreaders/string.h>

template<class charT>
class basic_string_sreader
{
public:
    template<class Tr, class Al>
    explicit basic_string_sreader(const std::basic_string<charT,Tr,Al> &s);
    sread_result<charT> operator()();
    const charT *position() const;
};
using string_sreader = basic_string_sreader<char>;

template<class charT, class Tr, class Al>
basic_string_sreader<charT>
    make_string_sreader(const std::basic_string<charT,Tr,Al> &s);

An adapter for std::basic_string.

Additional position() function returns the current pointer position.

Can be created using constructor or make_... function.

3.3.6cstream_sreader

#include<__vic/sreaders/cstream.h>

class cstream_sreader
{
public:
    explicit cstream_sreader(std::FILE *fp);
    sread_result<char> operator()() { return __vic::read(fp); }
};

cstream_sreader make_cstream_sreader(std::FILE *fp);

Models sreader<char> for std::FILE.

Can be created using constructor or make_... function.

4S-writers

template<class T>
class swriter
{
public:
    swriter(swriter &&o); or swriter(const swriter &o);
    void operator()(T v); // throws on errors
};

swriter is a concept used by the library algorithms to write logical sequence of elements of type T element by element. It is a generalization and rework of the OutputIterator concept. In particular it handles streams and other output sequences where end-iterator is meaningless or expensive to obtain better. At the same time, a traditional output iterators are just a particular case and fully and well handled by __vic::iterator_swriter adapter.

"swriter" is pronounced as "S-write" where S stands for "Sequential", "Sequence" or "Stream".

When the particular class meets the requirements of this concept for some T it is said to model the swriter<T> concept.

Each instance of the class has to be move- or copy-constructible.

void operator()(T v)

4.1__vic/swriters/defs.h

4.1.1swriter [C++20]

template<class W, class T>
concept swriter =
    std::movable<W> &&
    requires(W w, const T v) {
        w(v);
    };

A C++ concept for swriters.

4.2Concrete swriters

4.2.1null_swriter

#include<__vic/swriters/null.h>

class null_swriter
{
public:
    template<class T> void operator()(T v) {}
};

null_swriter make_null_swriter();

Fake writer that accepts any value and does nothing with it (like UNIX /dev/null).

4.2.2push_back_swriter

#include<__vic/swriters/push_back.h>

template<class Cont, class T = typename Cont::value_type>
class push_back_swriter
{
public:
    explicit push_back_swriter(Cont &c);
    void operator()(T v) { c->push_back(v); }
};

template<class Cont>
push_back_swriter<Cont> make_push_back_swriter(Cont &c);

template<class T, class Cont>
push_back_swriter<Cont,T> make_push_back_swriter_for(Cont &c);

An adapter. Uses push_back() member function to write elements. Can be created using constructor or one of make_... functions.

4.2.3iterator_swriter

#include<__vic/swriters/iterator.h>

template<class OutputIterator,
         class T = typename std::iterator_traits<OutputIterator>::value_type>
class iterator_swriter
{
public:
    explicit iterator_swriter(OutputIterator it);
    void operator()(T v);
};

template<class OutputIterator>
iterator_swriter<OutputIterator> make_iterator_swriter(OutputIterator it);

template<class T, class OutputIterator>
iterator_swriter<OutputIterator,T> make_iterator_swriter_for(OutputIterator it);

Output iterator writer. Can be created using constructor or one of make_... functions.

4.2.4string_swriter

#include<__vic/swriters/string.h>

template<
    class charT,
    class Tr = std::char_traits<charT>,
    class Al = std::allocator<charT>
>
class basic_string_swriter
{
public:
    explicit basic_string_swriter(std::basic_string<charT,Tr,Al> &s);
    void operator()(charT ch);
};

using string_swriter = basic_string_swriter<char>;

template<class charT, class Tr, class Al>
basic_string_swriter<charT,Tr,Al>
    make_string_swriter(std::basic_string<charT,Tr,Al> &s);

An adapter for std::basic_string. Can be created using constructor or make_... function.

4.2.5cstream_swriter

#include<__vic/swriters/cstream.h>

class cstream_swriter
{
public:
    explicit cstream_swriter(std::FILE *fp);
    void operator()(char ch) { __vic::write(fp, ch); }
};

cstream_swriter make_cstream_swriter(std::FILE *fp);

Models swriter<char> for std::FILE. Can be created using constructor or make_... function.

5Config library [C++11]

The library provides tools for parsing and reading configuration files. The tools are:

• A base class of configuration file parsers – config::parser [C++11], and
• An extensible set of configuration parameter parsers for different types – config::value [C++11].

5.1File format description

Configuration file is a text file with a set of named parameters and their values. Parameters can be:

1. Ordinary atomic or
2. Complex (compound).

Also, from the multiplicity point of view, they (both atomic and complex) can be:

1. Solitary (scalar) or
2. Multiple (list).

Each parameter has a name and a value. Atomic parameters are defined like this:

name: value

Lists consist of a set of values of the same type. Two equivalent notation can be used to define them. Use any of them you find more convenient.

Notation 1:

list_name: value1
list_name: value2
list_name: value3

Notation 2:

list_name {
value1
value2
value3
}

As you can see, the first notation is the same as that used for the scalar types. The only difference is that a scalar parameter gets only the last value, while a list gets all of them.

Both notations can be combined. For example, if you want the value }, it can be added using the first notation with a colon. The rest can be added using braces:

chars {
$
#
{
}

chars: }

A snippet like this creates a list of 4 elements: "$", "#", "{", "}".

Multiline values can be specified the following syntax:

name <<EOF
string 1
string 2
...
EOF

Where EOF is any sequence of Latin letters. The syntax and processing logic are the same as for the Bourne Shell "here-document" construct.

Complex parameters consist of a set of subparameters. For example:

complex_param (
    scalar_subparam: value
    list_subparam {
        value1
        value2
    }
    complex_subparam (
        ...
    )
)

As mentioned above, complex parameters can also be lists. The second list notation (see above) for complex parameters looks like this:

complex_list_param {
    (
        subparam: value1
        ...
    )
    (
        subparam: value2
        ...
    )
}

The first list notation for complex parameters is allowed as well.

Lines starting with the '#' character are treated as comments and are ignored by the parser.

If different files contain the same subset of parameters and their values, this common part can be moved to a separate file and then simply included in them. The following syntax is used:

...
<common.cfg>

param: value
...

common.cfg here is the name of the included file. The set of parameters from it is included in the current configuration file.

5.2Representation in code

The configuration in the code is represented as a struct with a set of fields corresponding to the configuration parameters. The names do not have to be the same as in the file. On instantiation of such struct, each field must get some default value.

A complex parameter is also a struct and can be treated as a configuration. In fact, the only difference is that they do not occupy the entire file, only a fragment between the parens.

The base class config::parser [C++11] is created to fill in such structs. To create your own parser, you derive a class from the base parser and then describe the set of parameters in the constructor. There are 2 ways to describe an atomic parameter: either using the __VIC_REGISTER_CONFIG_PARAM()/__VIC_REGISTER_CONFIG_PARAM_VP() macros, or using the register_param() member function defined in config::parser. The first method is more convenient if the parameter name is the same in both the struct and the file – you do not have to specify it twice. Complex parameters are described using either the __VIC_REGISTER_COMPLEX_CONFIG_PARAM() macro, or the register_complex_param() member function.

Here is an example. Suppose your code contains a structure with configuration parameters, like this:

struct myconfig
{
    myconfig() = default; // sets the parameters to their default values

    int                      int_param = 0;
    std::string              str_param{"default"};
    std::vector<std::string> list_param;
};

Let's assume that all the parameters except str_param have the same name in the file, and str_param is called "string" in the file. Now let's define a parser for the structure:

struct myconfig_parser : public __vic::config::parser
{
    explicit myconfig_parser(myconfig &cfg)
    {
        __VIC_REGISTER_CONFIG_PARAM(cfg, int_param);
        register_param(cfg.str_param, "string_param");
        __VIC_REGISTER_CONFIG_PARAM(cfg, list_param);
    }
};

The final step is to create an instance of the parser and apply it to the file using the parse() function:

myconfig cfg;
myconfig_parser parser(cfg);
parser.parse("conf/my.cfg");

Now we have the cfg structure filled with values from the file.

For each complex parameter you have to define the corresponding config::parser and register it using register_complex_param().

5.3Implemetation details and additional features

The type of a configuration parameter is determined by its type in the code, and its value is validated during parsing. The library has built-in support for some types:

• int, short, long, long long, signed char,
• unsigned, unsigned short, unsigned long, unsigned long long, unsigned char,
• std::string, __vic::string_buffer,
• bool (possible values in the file: 0, 1, true, false, yes, no).

By including additional headers, you can also add support for:

• std::optional (__vic/config/values/std/optional.h) [C++17].
• __vic::ipv4_addr (__vic/config/values/ipv4_addr.h).

And also lists with elements of the types mentioned above:

• std::vector (__vic/config/values/std/vector.h),
• std::list (__vic/config/values/std/list.h),
• std::forward_list (__vic/config/values/std/forward_list.h) [C++11].

If you are using an unsupported type for your parameter, you can add such support yourself. All you need to do is specialize the config::value<> template for your type in the following form:

namespace __vic { namespace config {
/////////////////////////////////////////////////////////////////////////////
template<> struct value<T>
{
    static bool parse(const std::string &s, T &res)
    {
        // TODO: parse s
    }
};
/////////////////////////////////////////////////////////////////////////////
}}

Where T is your type. The string representation of the value from the file is passed to the parse() function. It must parse it, convert to a value of the type T, and assign the value to the reference specified as the second parameter of the function. If the function fails to convert the value, it must return false.

Example for type bool:

bool __vic::config::value<bool>::parse(const std::string &v, bool &res)
{
    if(v == "1" || __vic::ascii::equal_icase(v, "true")
                || __vic::ascii::equal_icase(v, "yes"))
        res = true;
    else if(v == "0" || __vic::ascii::equal_icase(v, "false")
                     || __vic::ascii::equal_icase(v, "no"))
        res = false;
    else
        return false; // error
    return true; // OK
}

In general, a value parser doesn't have to be a specialization of config::value. There are situations when 2 parameters have the same type, but different representation in the file, so they need to be parsed differently. And the library provides such capabilities.

For example, we want to specify size in the configuration file in megabytes and gigabytes, for which we are going to use the suffixes M and G:

max_log_file_size: 2M

Obviously, if we just specify the type as unsigned and register the parameter in the constructor of the file parser, the config::value<unsigned> parser will be used and it will fail when a letter is encountered. The solution is to create your own value parser, like this:

struct file_size_value
{
    static bool parse(const std::string &st, unsigned &res)
    {
        // parse the string and save the result
    }
};

Now we need to tell the file parser to use this value parser for the parameter. It can be done like this:

register_param<file_size_value>(cfg.max_log_file_size, "max_log_file_size");
// or
__VIC_REGISTER_CONFIG_PARAM_VP(cfg, max_log_file_size, file_size_value);

That's it. Now the parameter will be parsed correctly.

The template argument for the register_param<> function template can be either a class or a class template with one type-parameter. In the latter case, the configuration parameter type will be used as a template argument for the type-parameter.

If the new parameter type is a list of values, you also need to define a specialization for the config::list_traits [C++11] template. Here is an example of adding a new container for lists of values – let's allow std::set to be used.

template<class T>
struct list_traits<std::set<T>>
{
    using value_type = T;
    static void push(std::set<T> &c, T &&v) { c.insert(std::move(v)); }
};

Now all parameters of type std::set<T> will be automatically treated as lists.

5.4__vic/config/parser.h [C++11]

5.4.1config::parser [C++11]

class config::parser
{
public:
    class error : public std::exception {};
    class source_error : public error
    {
    public:
        unsigned line() const;
    };
    class duplicate_param : public std::exception {};

    parser(const parser & ) = delete;
    parser &operator=(const parser & ) = delete;

    void parse(const char *file_path);
    void parse(const std::string &file_path);
protected:
    parser();
    ~parser();

    template<class T>
    void register_param(T &v, const char *name);

    template<template<class > class ValueParser, class T>
    void register_param(T &v, const char *name);

    template<class ValueParser, class T>
    void register_param(T &v, const char *name);

    template<class Parser, class T>
    void register_complex_param(T &v, const char *name);

#define __VIC_REGISTER_CONFIG_PARAM(c,p) this->register_param((c).p, #p)
#define __VIC_REGISTER_CONFIG_PARAM_VP(c,p,vp) \
    this->register_param<vp>((c).p, #p)
#define __VIC_REGISTER_COMPLEX_CONFIG_PARAM(c,p,cp) \
    this->register_complex_param<cp>((c).p, #p)
};

Base class for parsers of config files and complex parameters.

class error

class source_error

class duplicate_param

void parse(const char *file_path)

void parse(const std::string &file_path)

template<class ValueParser, class T>
void register_param(T &v, const char *name)

template<template<class > class ValueParser, class T>
void register_param(T &v, const char *name)

template<class T>
void register_param(T &v, const char *name)

__VIC_REGISTER_CONFIG_PARAM(cfg, param)

__VIC_REGISTER_CONFIG_PARAM_VP(cfg, papam, ValueParser)

template<class Parser, class T>
void register_complex_param(T &v, const char *name)

__VIC_REGISTER_COMPLEX_CONFIG_PARAM(cfg, param, Parser)

5.5__vic/config/value.h [C++11]

5.5.1config::value [C++11]

template<class T>
class config::value
{
public:
    static bool parse(const std::string &s, T &res);
};

template<> class config::value<int>;
template<> class config::value<short>;
template<> class config::value<long>;
template<> class config::value<long long>;
template<> class config::value<signed char>;

template<> class config::value<unsigned>;
template<> class config::value<unsigned short>;
template<> class config::value<unsigned long>;
template<> class config::value<unsigned long long>;
template<> class config::value<unsigned char>;

template<> class config::value<bool>;

template<> class config::value<std::string>;
template<> class config::value<__vic::string_buffer>;

Value parser for values of T type, used by default (unless specified explicitly). Parses the input string s. If successful, stores the result in res and returns true. You can create specializations for your own types.

All user-defined value parsers must have the same interface and behaviour.

5.5.2config::list_traits [C++11]

template<class List>
struct config::list_traits
{
    using value_type = list-element-type;
    static void push(List &list, value_type &&v);
};

Specializing this template for some List type makes the library treat parameters of that type as a list.

typename value_type

static void push(List &list, value_type &&v)

5.6Additional value parsers

5.6.1config::value<std::optional<T>> [C++17]

#include<__vic/config/values/std/optional.h>

template<class T>
class config::value<std::optional<T>>;

5.6.2config::value<__vic::ipv4_addr>

#include<mfisoft/config/values/ip_addr.h>

template<> class config::value<__vic::ipv4_addr>;

5.6.3config::complex_value<std::optional<T>> [C++17]

#include<__vic/config/values/std/optional.h>

template<class T, class Parser>
class config::complex_value<std::optional<T>, Parser, false>;

5.6.4config::list_traits<std::vector<T>>

#include<__vic/config/values/std/vector.h>

template<class T>
struct config::list_traits<std::vector<T>>;

5.6.5config::list_traits<std::list<T>>

#include<__vic/config/values/std/list.h>

template<class T>
struct config::list_traits<std::list<T>>;

5.6.6config::list_traits<std::forward_list<T>> [C++11]

#include<__vic/config/values/std/forward_list.h>

template<class T>
struct config::list_traits<std::forward_list<T>>;

5.6.7config::bytes_value_parser

#include<__vic/config/values/bytes.h>

template<class TUInt>
class config::bytes_value_parser;

Parser of parameters specifying the size in bytes. Allows values like "2K", which means 2 kilobytes. The following suffixes are supported: K – kilo, M – mega, G – giga. All the suffixes are powers of 2 (1K = 1024).

6Build and install

To build the library you need one of supported C++ compilers and GNU Make utility version 3.82 or higher available in your command line environment (cmd).

Currently supported compilers are:

• GNU C++ v 4.7+ (MinGW) [gcc]
• Clang v 5+ with MinGW [clang]
• Clang v 5+ with Visual C++ [clang-cl]
• Visual C++ v 15.8+ (Visual Studio 2017) [msvc]
• Visual C++ v 7.1+ (Visual Studio 2003) [msvc] is supported but you may need to edit makefiles because of unsupported compiler options

Go to src subdirectory and write:

C:\> gmake

The library file will be built for you.

C++17 is used by default but you can choose another language standard version using std option. E.g. to build the library in C++98 mode write:

C:\> gmake std=98

Available values include: 98, 11, 14, 17, 20 and 23.

Also you can choose the used compiler manually:

C:\> gmake compiler=gcc

Alternatively NMAKE utility can be used with Visual C++ and clang-cl instead of gmake:

C:\> nmake -f Makefile.nmake compiler=msvc

Finally, to use the library you just need to copy the library file and contents of include subdirectory to some place where compiler/linker can find it.