Data Classes

Bytes

The Bytes class is a wrapper around std::vector<std::byte>, supporting additional methods to convert data from and to byte sequences in different formats.

class Bytes

A sequence of bytes.

Tested:: BytesTest

Convert from Hexadecimal String

Convert a string of hex characters into a sequence of bytes.

Spaces are ignored and the text is parsed case-insensitive. In case of an error, an empty sequence is returned.

static Bytes fromHex(std::string_view hex) noexcept

Parameters:: hex – The string with the hex characters.
Returns:: The sequence of bytes or an empty sequence on error.

static Bytes fromHex(const char *hex) noexcept

Parameters:: hex – The string with the hex characters.
Returns:: The sequence of bytes or an empty sequence on error.

static Bytes fromHex(const String &hex) noexcept

Parameters:: hex – The string with the hex characters.
Returns:: The sequence of bytes or an empty sequence on error.

static Bytes fromHex(std::u8string_view hex) noexcept

Parameters:: hex – The string with the hex characters.
Returns:: The sequence of bytes or an empty sequence on error.

static Bytes fromHex(const char8_t *hex) noexcept

Parameters:: hex – The string with the hex characters.
Returns:: The sequence of bytes or an empty sequence on error.

Public Types

using ByteVector = std::vector<std::byte>: A vector of bytes.

Public Functions

Bytes() = default: Create an empty sequence of bytes.

inline explicit constexpr Bytes(ByteVector data) noexcept: Create a sequence of bytes from a vector of bytes.

inline explicit Bytes(const std::span<std::byte> data) noexcept: Create a sequence of bytes from a span of bytes.

String toHex() const noexcept

Convert this sequence of bytes to a string of hex characters.

Returns:: The string with the hex characters.

inline void append(const Bytes &bytes) noexcept

Append another byte-sequence to this one.

Parameters:: bytes – A byte sequence.

Public Static Functions

template<typename T> static inline Bytes from(std::initializer_list<T> list) noexcept

Converts a list of 1-byte integers into a sequence of bytes.

Parameters:: list – The list of ints.
Returns:: The sequence of bytes.

template<typename T> static inline Bytes convertFrom(std::initializer_list<T> list) noexcept

Converts a list of integers into a sequence of bytes, potentially losing the higher bytes.

Parameters:: list – The list of ints.
Returns:: The sequence of bytes.

template<std::input_iterator It> static inline Bytes from(It begin, It end)

Converts a list of 1-byte integers into a sequence of bytes.

Parameters:

begin – The begin iterator.
end – The end iterator.

Returns:

The sequence of bytes.

template<std::input_iterator It> static inline Bytes convertFrom(It begin, It end)

Converts a list of integers into a sequence of bytes, potentially losing the higher bytes.

Parameters:

begin – The begin iterator.
end – The end iterator.

Returns:

The sequence of bytes.

Date

class Date

A date value with year, month and day parts.

Tested:: DateTest

Public Functions

Date() = default

Create an undefined date.

Default constructor.

Date(int year, int month, int day)

Creates a new date.

Parameters:

year – The year in the range 1-9999.
month – The month in the range 1-12.
day – The day in the range 1-31.

Throws:

std::invalid_argument – if any of the parameters is out of the valid range or the date is not valid.

~Date() = default: Default destructor.

Date(const Date&) = default: Default copy constructor.

Date &operator=(const Date&) = default: Default copy assignment.

inline bool isUndefined() const noexcept

Test if this is an undefined date.

Returns:: true if the date is undefined.

int year() const noexcept

The year of the date.

Returns:: The year in the range 1-9999, or, zero for undefined dates.

int month() const noexcept

The month of the date.

Returns:: The month in the range 1-12, or, zero for undefined dates.

int day() const noexcept

The day of the date.

Returns:: The day in the range 1-31, or, zero for undefined dates.

inline int64_t toDaysSinceEpoch() const noexcept

Convert this date into days since the epoch.

Epoch is the fictive date 0000-01-01.

Returns:: The days since the fictive (invalid) date 0000-01-01. Returns zero for undefined dates.

String toText() const noexcept

Convert this date into text.

Uses the ISO format yyyy-mm-dd.

Returns:: The formatted date or an empty string for undefined dates.

Public Static Functions

static bool isValid(int year, int month, int day) noexcept

Test if the given values are valid.

Parameters:

year – The year in the range 1-9999.
month – The month in the range 1-12.
day – The day in the range 1-31.

Returns:

true if the values describe a valid date, otherwise false.

DateTime

class DateTime

A date-time value, with a date, time and time-offset part.

@important As this date-time class is meant to be converted into a full features date-time instance, for time-comparison, local-time is assumed to be UTC. As querying the current offset for a local-time is omitted, as this would add unnecessary complexity to this data class. Date-times with different offsets are properly compared, with the offset applied to the compared point-in-time.

Tested:: DateTimeTest

Public Functions

DateTime() = default: Create an undefined date-time value.

template<typename FwdDate, typename FwdTime> inline DateTime(FwdDate &&date, FwdTime &&time)

Create a new date-time value.

Template Parameters:

FwdDate – A date type that can be forwarded to the internal Date constructor.
FwdTime – A time type that can be forwarded to the internal Time constructor.

Parameters:

date – The date component.
time – The time component.

~DateTime() = default: Default destructor.

DateTime(const DateTime&) = default: Default copy constructor.

DateTime &operator=(const DateTime &other) = default: Default copy assignment.

inline bool isUndefined() const noexcept

Test if this date/time is undefined.

Returns:: true if this date-time is undefined.

inline const Date &date() const noexcept

Access the date part.

Returns:: The date part.

inline const Time &time() const noexcept

Access the time part.

Returns:: The time part.

String toText() const noexcept

Convert this date-time into text.

Uses the ISO format yyyy-mm-dd hh:mm:ss.zzz, with these rules:

If there is a second fraction, only the minimum required digits for the fractions are displayed.
For UTC times, the suffix z is added.
For times with offset, the offset with hours and minutes +02:00 is added.
Local times have no suffix.

Returns:: The formatted date-time or an empty string for undefined date-times.

Float

using erbsland::conf::Float = double

Floating-point type used throughout the parser.

Tested:: FloatTest

Integer

using erbsland::conf::Integer = int64_t

Signed integer type used throughout the parser.

Tested:: IntegerTest

Time

class Time

A time value with nanosecond precision and optional offset.

Tested:: TimeTest

Note

About the implementation of the comparison operators: Comparison of two times, without date and/or mixed offsets is very limited and usually makes no sense, as for a proper comparison of a point-in-time the date for the given time is required as well. Therefore, as this time class is a minimal data class, for time-comparison, local-time is assumed to be UTC.

Public Functions

Time() = default: Create an undefined time.

Time(int hour, int minute, int second, int nanosecond, TimeOffset offset)

Creates a new time from the given elements.

Parameters:

hour – The hour in the range 0-23.
minute – The minute in the range 0-59.
second – The second in the range 0-59.
nanosecond – The second fraction in the range 0-999’999’999
offset – The time offset.

Throws:

std::invalid_argument – if any of the parameters is out of the valid range.

Time(int64_t nanoseconds, TimeOffset offset)

Create a time from nanoseconds.

Parameters:

nanoseconds – The time in nanoseconds since midnight in the range 0-5’183’999’999’999’999.
offset – The time offset.

Throws:

std::invalid_argument – in case the nanoseconds exceed 24h or is negative.

~Time() = default: Default destructor.

Time(const Time&) = default: Default copy constructor.

Time &operator=(const Time&) = default: Default copy assignment.

inline bool isUndefined() const noexcept

Test if this time is undefined (created with the default constructor).

Returns:: true if this time is undefined.

int hour() const noexcept: The hour part of this time (0-23).

int minute() const noexcept: The minute part of this time (0-59).

int second() const noexcept: The second part of this time (0-59).

std::chrono::nanoseconds secondFraction() const noexcept: The second fractions in nanoseconds (0-999’999’999)

const TimeOffset &offset() const noexcept: The offset for this time.

std::chrono::nanoseconds toNanoseconds() const noexcept: Convert this time into nanoseconds since midnight.

String toText() const noexcept

Convert this time into text.

Uses the ISO format hh:mm:ss.zzz. Adds the minimum number of second fractions. Always adds the offset or “z” for UTC times, unless this is a local time.

Returns:: The formatted time or an empty string for undefined times.

TimeDelta

class TimeDelta

A combined time delta value.

Tested:: TimeDeltaTest

Note

Months and years are incompatible units because they do not map exactly to seconds. When converting time deltas that include months and years, a month counts as 2,628,000 seconds (30.44 days) and a year as 31,557,600 seconds (365.25 days). Therefore, you should carefully examine the delta before converting it to seconds. If you alter a date using this time delta, it is best to add years and months first before adding other units.

Public Types

using Count = int64_t: The integer type used to represent time quantities.

Public Functions

inline TimeDelta(TimeUnit unit, Count count) noexcept: Create a time delta with a single unit.

TimeDelta() = default: Default constructor.

~TimeDelta() = default: Default destructor.

TimeDelta(const TimeDelta&) = default: Default copy constructor.

TimeDelta &operator=(const TimeDelta&) = default: Default copy assignment.

inline bool operator==(const TimeDelta &other) const noexcept

Compare two time deltas for near-equality.

This comparison allows for small rounding differences in fractional seconds.

Parameters:: other – The other time delta to compare.
Returns:: true if the deltas differ by less than one nanosecond in seconds.

inline bool operator!=(const TimeDelta &other) const noexcept

Compare two time deltas for inequality.

Parameters:: other – The other time delta to compare.
Returns:: true if the time deltas differ, false otherwise.

inline bool operator<(const TimeDelta &other) const noexcept

Compare two time deltas for less-than.

Parameters:: other – The other time delta to compare.
Returns:: true if this time delta is less than the other, false otherwise.

inline bool operator<=(const TimeDelta &other) const noexcept

Compare two time deltas for less-or-equal.

Parameters:: other – The other time delta to compare.
Returns:: true if this time delta is less than or equal to the other, false otherwise.

inline bool operator>(const TimeDelta &other) const noexcept

Compare two time deltas for greater-than.

Parameters:: other – The other time delta to compare.
Returns:: true if this time delta is greater than the other, false otherwise.

inline bool operator>=(const TimeDelta &other) const noexcept

Compare two time deltas for greater-or-equal.

Parameters:: other – The other time delta to compare.
Returns:: true if this time delta is greater than or equal to the other, false otherwise.

TimeDelta operator+(const TimeDelta &other) const noexcept

Add two time deltas.

Parameters:: other – The time delta to add.
Returns:: The sum of the two time deltas.

TimeDelta operator-(const TimeDelta &other) const noexcept

Subtract one time delta from another.

Parameters:: other – The time delta to subtract.
Returns:: The difference of the two time deltas.

TimeDelta &operator+=(const TimeDelta &other) noexcept

Add a time delta to this time delta.

Parameters:: other – The time delta to add.
Returns:: Reference to this time delta.

TimeDelta &operator-=(const TimeDelta &other) noexcept

Subtract a time delta from this time delta.

Parameters:: other – The time delta to subtract.
Returns:: Reference to this time delta.

inline bool isZero() const noexcept: Test if this time delta is zero.

inline bool empty() const noexcept

Test if this time delta is empty.

This is the case if the time delta is default constructed and contains no counts.

inline bool hasMultipleCounts() const noexcept: Test if this time delta combines multiple counts.

template<TimeUnit::Enum tUnit> inline Count count() const noexcept

Get the count for a specific time unit.

Template Parameters:: tUnit – The time unit enum value.
Returns:: The count for the specified unit, or zero if not set.

inline Count count(TimeUnit unit) const noexcept

Get the count for a specific time unit.

Parameters:: unit – The time unit.
Returns:: The count for the specified unit, or zero if not set.

template<TimeUnit::Enum tUnit> inline void setCount(Count count) noexcept

Set the count for a specific time unit.

Template Parameters:: tUnit – The time unit enum value.
Parameters:: count – The count to set for the unit.

inline void setCount(TimeUnit unit, Count count) noexcept

Set the count for a specific time unit.

Parameters:

unit – The time unit.
count – The count to set for the unit.

inline std::vector<TimeUnit> units() const noexcept: Get all times units that are defined for this delta.

inline Count nanoseconds() const noexcept

Get the nanosecond component of this time delta.

Returns:: The nanoseconds count.

inline void setNanoseconds(Count nanoseconds) noexcept

Set the nanosecond component of this time delta.

Parameters:: nanoseconds – The nanoseconds count to set.

inline Count microseconds() const noexcept

Get the microsecond component of this time delta.

Returns:: The microseconds count.

inline void setMicroseconds(Count microseconds) noexcept

Set the microsecond component of this time delta.

Parameters:: microseconds – The microseconds count to set.

inline Count milliseconds() const noexcept

Get the millisecond component of this time delta.

Returns:: The milliseconds count.

inline void setMilliseconds(Count milliseconds) noexcept

Set the millisecond component of this time delta.

Parameters:: milliseconds – The milliseconds count to set.

inline Count seconds() const noexcept

Get the second component of this time delta.

Returns:: The seconds count.

inline void setSeconds(Count seconds) noexcept

Set the second component of this time delta.

Parameters:: seconds – The seconds count to set.

inline Count minutes() const noexcept

Get the minute component of this time delta.

Returns:: The minutes count.

inline void setMinutes(Count minutes) noexcept

Set the minute component of this time delta.

Parameters:: minutes – The minutes count to set.

inline Count hours() const noexcept

Get the hour component of this time delta.

Returns:: The hours count.

inline void setHours(Count hours) noexcept

Set the hour component of this time delta.

Parameters:: hours – The hours count to set.

inline Count days() const noexcept

Get the day component of this time delta.

Returns:: The days count.

inline void setDays(Count days) noexcept

Set the day component of this time delta.

Parameters:: days – The days count to set.

inline Count weeks() const noexcept

Get the week component of this time delta.

Returns:: The weeks count.

inline void setWeeks(Count weeks) noexcept

Set the week component of this time delta.

Parameters:: weeks – The weeks count to set.

inline Count months() const noexcept

Get the month component of this time delta.

Returns:: The months count.

inline void setMonths(Count months) noexcept

Set the month component of this time delta.

Parameters:: months – The months count to set.

inline Count years() const noexcept

Get the year component of this time delta.

Returns:: The years count.

inline void setYears(Count years) noexcept

Set the year component of this time delta.

Parameters:: years – The years count to set.

inline bool isSecondBased() const noexcept

Test if this time delta is based on seconds.

This is true, if there are no months and years in the time-delta. Only if this function returns true, the method toSeconds() will return a precise conversion. If this method is false, the result of toSeconds() is an approximation.

Returns:: true if this time delta can be precisely converted into seconds.

double toSeconds() const noexcept

Converts this time delta into seconds.

This function may lose precision in the fractional seconds when very large values for days or weeks are used.

Returns:: The time delta in seconds, with fractions.

int64_t toNanoseconds() const

Tries to convert this time-delta to nano-seconds.

Throws:: std::domain_error – If the resulting nanoseconds value would exceed the 64-bit integer.
Returns:: The number of nanoseconds.

String toText() const: Convert this time delta into a text representation

Friends

friend TimeDelta operator-(const TimeDelta &other) noexcept

Unary minus for time delta.

Parameters:: other – The time delta to negate.
Returns:: The negated time delta.

class TimeUnit

A single time unit used in the configuration.

Tested:: TimeUnitTest

Construction and Assignment

inline constexpr TimeUnit(Enum value) noexcept

Create a new time unit.

Parameters:: value – The enum value.

TimeUnit() = default: Default constructor.

~TimeUnit() = default: Default destructor.

TimeUnit(const TimeUnit&) = default: Default copy constructor.

TimeUnit &operator=(const TimeUnit&) = default: Default copy assignment.

Conversion

inline explicit constexpr operator Enum() const noexcept: Cast this into its enum value.

const String &toTextLong() const noexcept: Get this unit as a long text.

const String &toTextShort() const noexcept: Get this unit as a short text.

const String &toTextLowercaseSingular() const noexcept: Get this unit as a lowercase, singular text.

double secondFactor() const noexcept: Get the second factor of this unit.

int64_t nanosecondsFactor() const noexcept: Get the nanosecond factor of this unit.

Public Types

enum Enum

The enumeration.

Values:

enumerator Nanoseconds

enumerator Microseconds

enumerator Milliseconds

enumerator Seconds

enumerator Minutes

enumerator Hours

enumerator Days

enumerator Weeks

enumerator Months

enumerator Years

Public Static Functions

static inline const std::array<TimeUnit, 10> &all() noexcept: Get an array with all time units.

TimeOffset

class TimeOffset

A time offset.

Tested:: TimeOffsetTest

Public Types

enum class Precision : uint8_t

The precision used for the text format.

Values:

enumerator Automatic: Depends on if minutes, and seconds are zero.

enumerator Seconds: Format: [+-]hh:mm:ss.

enumerator Minutes: Format: [+-]hh:mm.

enumerator Hours: Format: [+-]hh.

Public Functions

TimeOffset() = default: Create local time.

inline explicit constexpr TimeOffset(std::chrono::seconds seconds)

Create a time offset from the given number of seconds.

Parameters:: seconds – The offset in seconds. Zero for UTC.
Throws:: std::out_of_range – if the offset is out of the valid range.

inline explicit constexpr TimeOffset(int32_t seconds)

Create a time offset from the given number of seconds.

Parameters:: seconds – The offset in seconds. Zero for UTC.
Throws:: std::out_of_range – if the offset is out of the valid range.

inline constexpr TimeOffset(bool isNegative, int hours, int minutes, int seconds)

Create a time offset from the given hours, minutes and seconds.

Parameters:

isNegative – If this is a negative offset.
hours – The hours in the range 0-23.
minutes – The minutes in the range 0-59.
seconds – The seconds in the range 0-59.

Throws:

std::out_of_range – if one of the values is out of the valid range.

~TimeOffset() = default: Default destructor.

TimeOffset(const TimeOffset&) = default: Default copy constructor.

TimeOffset &operator=(const TimeOffset&) = default: Default copy assignment.

bool isLocalTime() const noexcept: Test if this is a local time.

bool isUTC() const noexcept: Test if this is UTC (zero offset)

std::chrono::seconds totalSeconds() const noexcept

Get the offset as a positive or negative total number of seconds.

Returns:: The offset in seconds, and zero for UTC and local time.

bool isNegative() const noexcept

If this offset is negative.

Returns:: true if this is a negative offset, false for zero, local time and positive offsets.

int seconds() const noexcept

The second part of the offset.

Returns:: The second part of the offset, always in the positive range 0-59. Zero for local time.

int minutes() const noexcept

The minute part of the offset.

Returns:: The minute part of the offset, always in the positive range 0-59. Zero for local time.

int hours() const noexcept

The hour part of the offset.

Returns:: The hour part of the offset, always in the positive range 0-23. Zero for local time.

String toText(Precision precision = Precision::Automatic) const noexcept

Convert this offset into text.

Returns an empty text for local time. Returns “z” for UTC For precision set to Precision::Automatic, the minimal required elements are returned. if minutes and seconds are zero, only the hours are returned. If minutes are non-zero, the minutes are returned too and if seconds are not zero, the seconds are returned as well.

Precision::Hours: Returns an offset in the format “+01”.
Precision::Minutes: Returns an offset in the format “-01:23”.
Precision::Seconds: Returns an offset in the format “+01:14:35”.

Public Static Functions

static inline constexpr TimeOffset utc() noexcept

Create a UTC offset.

This static method is more expressive than an offset with zero seconds.