Value

Interface

class Value : public std::enable_shared_from_this<Value>

The base class and interface for all values.

Tested:

ValueTest

Subclassed by erbsland::conf::Document

Access as Typed Value

These methods return the contained value if it has the requested type. Otherwise, a default-constructed value of the corresponding type is returned, or in case of the ...OrThrow variants, an Error (TypeMismatch) is thrown.

No type conversion or coercion is performed.

For example:

• asInteger() returns the stored Integer if this value is of type Integer, or Integer{} otherwise.

• asText() returns the stored String only if this value is of type Text, not if it’s e.g. an Integer.

To obtain a textual representation of any supported type (e.g. Integer → "42"), use toTextRepresentation().

virtual Integer asInteger() const noexcept = 0

Access as integer.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Integer asIntegerOrThrow() const = 0

Access as integer.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual bool asBoolean() const noexcept = 0

Access as boolean.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual bool asBooleanOrThrow() const = 0

Access as boolean.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual Float asFloat() const noexcept = 0

Access as a floating-point value.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Float asFloatOrThrow() const = 0

Access as a floating-point value.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual String asText() const noexcept = 0

Access as text.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual String asTextOrThrow() const = 0

Access as text.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual Date asDate() const noexcept = 0

Access as a Date instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Date asDateOrThrow() const = 0

Access as a Date instance.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual Time asTime() const noexcept = 0

Access as a Time instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Time asTimeOrThrow() const = 0

Access as a Time instance.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual DateTime asDateTime() const noexcept = 0

Access as a DateTime instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual DateTime asDateTimeOrThrow() const = 0

Access as a DateTime instance.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual Bytes asBytes() const noexcept = 0

Access as a Bytes array.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual Bytes asBytesOrThrow() const = 0

Access as a Bytes array.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual TimeDelta asTimeDelta() const noexcept = 0

Access as a TimeDelta instance.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual TimeDelta asTimeDeltaOrThrow() const = 0

Access as a TimeDelta instance.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual RegEx asRegEx() const noexcept = 0

Access as a regular expression text.

Returns:

The value of the requested type, or if this value has a different type, a default value.

virtual RegEx asRegExOrThrow() const = 0

Access as a regular expression text.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

The value of the requested type.

virtual ValueList asValueList() const noexcept = 0

Access as a value list. @important This call does not convert a single value into a list with one element. Use the getList() methods if you like to have this behavior.

Returns:

A value list, or an empty list if this is no value list.

virtual ValueList asValueListOrThrow() const = 0

Access as a value list. @important This call does not convert a single value into a list with one element. Use the getList() methods if you like to have this behavior.

Throws:

Error – (TypeMismatch) if the value is of another type.

Returns:

A value list.

template<typename T>
inline T asType() const noexcept

This is a convenience method, accessed this value as one of the supported types. It is implemented calling the various to<Type>() methods.

@important

• There are overloads for all integers, converting the signed 64-bit integer into the desired type.

• There are overloads for all float types, converting a double into a float if necessary.

• If the value exceeds the range of the target type:

  • for asType() saturation logic is used - returning the max/min possible value for the chosen type.

  • for asTypeOrThrow() a TypeMismatch exception is thrown.

• The overload for ValueList works exactly like asValueList() and therefore does not convert a single value into a list with one element. Use the getList() methods for this behavior.

Template Parameters:

T – The type to access this value as.

Returns:

The value or a default value.

template<typename T>
inline T asTypeOrThrow() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Get a Value of a Given Type

Tries to get a value at the given name-path with a given type.

• If the name path is not valid,

• or if there is no value at the name-path

• or the value does not have the expected type,

• a default value passed as defaultValue parameter is returned.

• … or, an exception is thrown for the ...OrThrow methods.

If types are converted, the same logic as described in asType() or asTypeOrThrow() applies.

template<typename T>
inline T get(const NamePathLike &namePath, T defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

the requested value or defaultValue.

template<typename T>
inline T getOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

Integer getInteger(const NamePathLike &namePath, Integer defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Integer getIntegerOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

bool getBoolean(const NamePathLike &namePath, bool defaultValue = false) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

bool getBooleanOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

Float getFloat(const NamePathLike &namePath, Float defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Float getFloatOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

String getText(const NamePathLike &namePath, const String &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

String getTextOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

Date getDate(const NamePathLike &namePath, const Date &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Date getDateOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

Time getTime(const NamePathLike &namePath, const Time &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Time getTimeOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

DateTime getDateTime(const NamePathLike &namePath, const DateTime &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

DateTime getDateTimeOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

Bytes getBytes(const NamePathLike &namePath, const Bytes &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

Bytes getBytesOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

TimeDelta getTimeDelta(const NamePathLike &namePath, const TimeDelta &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

TimeDelta getTimeDeltaOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

RegEx getRegEx(const NamePathLike &namePath, const RegEx &defaultValue = {}) const noexcept

Parameters:

• namePath – The name path, name or index to resolve, relative to this value.

• defaultValue – The default value returned if the value can’t be resolved.

Returns:

The value or defaultValue if there is no matching value at namePath.

RegEx getRegExOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

ValueList getValueList(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The value list or an empty list if there is no matching value at namePath.

ValueList getValueListOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – If the value does not exist or has the wrong type.

Returns:

The requested value.

Get Uniform Value Lists

• Tries to get uniform lists that consist of values of the same type.

• If there is a single value at the name path, a list with one element is returned.

template<typename T>
std::vector<T> getList(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name-path, name or index of the value list.

Returns:

A list with values of this type, or an empty list on any problem.

template<typename T>
std::vector<T> getListOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name-path, name or index of the value list.

Throws:

Error – In case of any type mismatch or syntax error in the name path.

Returns:

A list with values of this type.

Get a Section-Map or Section-List

Tries to get a section map or section list at the given path. If the path does not exist (or contains syntax errors), either a nullptr is returned, or an exception is thrown (...OrThrow() methods).

ValuePtr getSectionWithNames(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The section map/list or nullptr.

ValuePtr getSectionWithNamesOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – if the name path has syntax errors, or if there is no matching section at the value-path.

Returns:

The section map or section list.

ValuePtr getSectionWithTexts(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The section map/list or nullptr.

ValuePtr getSectionWithTextsOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – if the name path has syntax errors, or if there is no matching section at the value-path.

Returns:

The section map or section list.

ValuePtr getSectionList(const NamePathLike &namePath) const noexcept

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Returns:

The section map/list or nullptr.

ValuePtr getSectionListOrThrow(const NamePathLike &namePath) const

Parameters:

namePath – The name path, name or index to resolve, relative to this value.

Throws:

Error – if the name path has syntax errors, or if there is no matching section at the value-path.

Returns:

The section map or section list.

Tests for a Value Type

Test if a value is of a certain type.

inline bool isInteger() const noexcept

Returns:

true if the value has the tested type.

inline bool isBoolean() const noexcept

Returns:

true if the value has the tested type.

inline bool isFloat() const noexcept

Returns:

true if the value has the tested type.

inline bool isText() const noexcept

Returns:

true if the value has the tested type.

inline bool isDate() const noexcept

Returns:

true if the value has the tested type.

inline bool isTime() const noexcept

Returns:

true if the value has the tested type.

inline bool isDateTime() const noexcept

Returns:

true if the value has the tested type.

inline bool isBytes() const noexcept

Returns:

true if the value has the tested type.

inline bool isTimeDelta() const noexcept

Returns:

true if the value has the tested type.

inline bool isRegEx() const noexcept

Returns:

true if the value has the tested type.

inline bool isValueList() const noexcept

Returns:

true if the value has the tested type.

inline bool isDocument() const noexcept

Returns:

true if the value has the tested type.

inline bool isRoot() const noexcept

Returns:

true if the value has the tested type.

inline bool isSectionWithNames() const noexcept

Returns:

true if the value has the tested type.

inline bool isSectionWithTexts() const noexcept

Returns:

true if the value has the tested type.

inline bool isSectionList() const noexcept

Returns:

true if the value has the tested type.

inline bool isList() const noexcept

Test if this value is a list.

Tests if this value is a list, like a section list or value list with child-elements that can be iterated in a sequence.

Returns:

true if this value is a list.

inline bool isMap() const noexcept

Test if this value is a name-value map.

Tests if this value is a name-value map, like a section with names, section with texts, intermediate section or a document.

Public Functions

virtual ~Value() = default

Default destructor.

virtual Name name() const noexcept = 0

The name.

virtual NamePath namePath() const noexcept = 0

The name path.

virtual bool hasParent() const noexcept = 0

Test if this value has a parent.

virtual ValuePtr parent() const noexcept = 0

The parent.

virtual ValueType type() const noexcept = 0

The type of this value.

virtual bool hasLocation() const noexcept = 0

Test if this value has location info.

virtual Location location() const noexcept = 0

Get the location info for this value.

virtual void setLocation(const Location &newLocation) noexcept = 0

Set the location info for this value.

virtual std::size_t size() const noexcept = 0

Get the number of children.

virtual bool hasValue(const NamePathLike &namePath) const noexcept = 0

Test if there is a child-value with the given index, name or name-path.

Parameters:

namePath – A name-path, name or index.

Returns:

true if there is a value (and the name-path is valid).

virtual ValuePtr value(const NamePathLike &namePath) const noexcept = 0

Get the child-value at the specified index, name or name-path.

If no value is found at the given location, or the name-path contains syntax errors, the method returns a nullptr.

Parameters:

namePath – A name-path, name or index.

Returns:

The child value.

virtual ValuePtr valueOrThrow(const NamePathLike &namePath) const = 0

Get the child-value at the specified index, name or name-path.

If no value is found at the given location, or the name-path contains syntax errors, an Error exception is thrown.

Parameters:

namePath – A name-path, name or index.

Throws:

Error – (NotFound, Syntax) if the value does not exist or the name-path contains syntax errors.

Returns:

The child value.

virtual ValueIterator begin() const noexcept = 0

Get an iterator to the first child value.

Returns:

The value iterator.

virtual ValueIterator end() const noexcept = 0

Get an iterator to the end of the child values.

Returns:

The value iterator.

virtual String toTextRepresentation() const noexcept = 0

Convert this value to its text representation.

Converts the types: Text, Integer, Float, Boolean, Date, Time, Date-Time, Bytes, TimeDelta, RegEx. Sections and lists result in an empty string.

Returns:

A string with the text or text representation.

String toTestText(TestFormat format = {}) const noexcept

Convert this value to its test adapter representation.

This is used by the test adapter to verify the value, as described in the language documentation.

The general format is <Type>(<value>), where <Type> is one of the standardized type names and <value> the value representation as specified. For example, an integer value 5, is converted into the text Integer(5). No additional info is added to sections.

Parameters:

format – The format of the output.

Returns:

The value in its test outcome representation.

String toTestValueTree(TestFormat format = {}) const noexcept

Convert this value into a visual value tree.

This method is useful for testing to get a visual representation of a parsed document, or a branch of the document.

Parameters:

format – The format of the output.

Returns:

A text with a visual tree representation of this value.

bool empty() const noexcept

Test if this container is empty.

Returns:

true if the container is empty.

ValuePtr firstValue() const noexcept

Get the first value of a container.

Returns:

The first value or a nullptr.

ValuePtr lastValue() const noexcept

Get the last value of a container.

Returns:

The last value or a nullptr.

class ValueType

The type of value.

Tested:

ValueTypeTest

Construction and Assignment

constexpr ValueType() = default

Create an undefined value type.

inline constexpr ValueType(const Enum value) noexcept

Create a new value type.

Parameters:

value – The enum value.

~ValueType() = default

Default destructor.

ValueType(const ValueType&) = default

Default copy constructor.

ValueType &operator=(const ValueType&) = default

Default copy assignment.

Operators

inline ValueType &operator=(const Enum value) noexcept

Assign an enum.

inline constexpr operator Enum() const noexcept

Cast back to the enum value.

Tests

inline constexpr bool isUndefined() const noexcept

Test if the type is undefined.

inline constexpr bool isMap() const noexcept

Test if this is any kind of value map (a section or document).

inline constexpr bool isList() const noexcept

Test if this is any kind of list (section list or value list).

inline constexpr bool isSingle() const noexcept

Test if this is a single value.

Public Types

enum Enum

The enum for this type.

Values:

enumerator Undefined

Undefined type.

enumerator Integer

An integer value.

enumerator Boolean

A boolean value.

enumerator Float

A floating-point value.

enumerator Text

A text value.

enumerator Date

A date value.

enumerator Time

A time value.

enumerator DateTime

A date-time value.

enumerator Bytes

Binary data.

enumerator TimeDelta

A time delta value.

enumerator RegEx

A regular expression value.

enumerator ValueList

A list of values.

enumerator SectionList

A list of sections.

enumerator IntermediateSection

An intermediate section.

enumerator SectionWithNames

A section with names.

enumerator SectionWithTexts

A section with texts.

enumerator Document

The document.

Public Functions

const String &toText() const noexcept

Convert this type into text.

inline constexpr Enum raw() const noexcept

Access the underlying enum value.

Public Static Functions

template<typename T>
static inline constexpr ValueType from() noexcept

Get a value type for a single value, native type.

Please note that this method does not support sections or value lists.

static inline const std::array<ValueType, 17> &all() noexcept

Get an array with all value types.

using erbsland::conf::ValuePtr = std::shared_ptr<Value>

using erbsland::conf::ConstValuePtr = std::shared_ptr<const Value>

using erbsland::conf::ValueList = std::vector<ConstValuePtr>

class ValueIterator

Const iterator for the Value class.

This is a simple wrapper around the iterator of the internally used container.

Tested:

Tested via Value class.

Construction and Assignment

inline explicit constexpr ValueIterator(WrappedIterator it)

Create an iterator wrapping the given internal iterator.

Parameters:

it – The iterator to wrap.

ValueIterator() = default

Default constructor.

~ValueIterator() = default

Default destructor.

ValueIterator(const ValueIterator&) = default

Default copy constructor.

ValueIterator(ValueIterator&&) noexcept = default

Default move constructor.

ValueIterator &operator=(const ValueIterator&) = default

Default copy assignment.

ValueIterator &operator=(ValueIterator&&) noexcept = default

Default move assignment.

Operators

reference operator*() const noexcept

Dereference operator.

Returns:

A shared pointer to the current value.

pointer operator->() const noexcept

Member access operator.

Returns:

A pointer to the current value.

ValueIterator &operator++() noexcept

Prefix increment. Advances the iterator to the next element.

ValueIterator operator++(int) noexcept

Postfix increment. Advances the iterator and returns the previous state.

bool operator==(const ValueIterator &other) const noexcept

Equality comparison.

Parameters:

other – The other iterator for comparison.

bool operator!=(const ValueIterator &other) const noexcept

Inequality comparison.

Parameters:

other – The other iterator for comparison.