icarus::KeyValuesData::Item Struct Reference

Representation of a single item of data: a key and several values. More...

#include <KeyValuesData.h>

Inheritance diagram for icarus::KeyValuesData::Item:

Public Types
using	pair_t = std::pair< std::string, std::vector< std::string >>
template<typename T >
using	UseBase = icarus::details::KeyValuesConverter< icarus::details::BaseWrapper< T >>
	Alias for numerical base conversion. More...

Public Member Functions
	Item (std::string key)
	Constructs a new item assigning it a key (which should not be changed). More...
bool	operator< (Item const &other) const noexcept
	Lexicographic order by key (case-sensitive). More...
std::size_t	nValues () const noexcept
	Returns the number of values currently present. More...
Query interface
template<typename T , typename Conv >
T	getAs (std::size_t index, Conv converter) const
	Returns the requested value, converted into type T More...
template<typename T >
T	getAs (std::size_t index) const
	Returns the requested value, converted into type T More...
template<typename T , bool IgnoreFormatErrors = false, typename Conv >
std::optional< T >	getOptionalAs (std::size_t index, Conv converter) const
	Returns the requested value, converted into type T More...
template<typename T , bool IgnoreFormatErrors = false>
std::optional< T >	getOptionalAs (std::size_t index) const
	Returns the requested value, converted into type T More...
template<typename T >
T	getNumber (std::size_t index, unsigned int base) const
	Returns the requested value, converted into a number of type T More...
template<typename T >
T	getNumber (std::size_t index) const
template<typename T >
std::optional< T >	getOptionalNumber (std::size_t index, unsigned int base) const
	Returns the requested value, converted into a number of type T More...
template<typename T >
std::optional< T >	getOptionalNumber (std::size_t index) const
template<typename T , typename Conv = details::KeyValuesConverter<T>>
std::vector< T >	getVector (Conv converter={}) const
	Returns all the values, each converted into type T More...
template<typename T , typename Conv = details::KeyValuesConverter<T>>
std::vector< T >	getSizedVector (Conv converter=Conv{}) const
	Returns all the values, each converted into type T More...

Private Member Functions
template<typename T , typename Iter , typename Conv >
std::vector< T >	convertVector (Iter begin, Iter end, Conv converter) const
template<typename T >
std::optional< T >	convertStringInto (std::string const &valueStr) const
	Conversion functions. More...

Detailed Description

Representation of a single item of data: a key and several values.

Values can be added directly accessing the values data member, or with addValue() method call.

Access to the values happens by index, with nValues() indices starting from 0 available. Direct access to values() is expected, and additional shortcuts are available:

• getAs(), getOptionalAs() to convert to an arbitrary type; the standard conversion uses from_chars(), and specialization is possible
• getNumber(), getOptionalNumber() to convert to a number
• getVector() to convert to a vector of values (each like in getAs())
• getSizedVector() to convert to a vector of values; the first value is the size of the actual values.

Definition at line 193 of file KeyValuesData.h.

Member Typedef Documentation

using icarus::KeyValuesData::Item::pair_t = std::pair<std::string, std::vector<std::string>>

Definition at line 195 of file KeyValuesData.h.

template<typename T >

using icarus::KeyValuesData::Item::UseBase = icarus::details::KeyValuesConverter<icarus::details::BaseWrapper<T>>

Alias for numerical base conversion.

Template Parameters

T	type of the number to be converted

Example of usage:

auto const i16
  = item.getAs<int>(0U, icarus::KeyValuesData::Item::UseBase<int>{ 16 });

converts the first value of item into an integer (int) with base 16.

Definition at line 210 of file KeyValuesData.h.

Constructor & Destructor Documentation

icarus::KeyValuesData::Item::Item ( std::string  key )

inline

Constructs a new item assigning it a key (which should not be changed).

Definition at line 216 of file KeyValuesData.h.

: pair_t{ std::move(key), {} } {}

Member Function Documentation

template<typename T >

std::optional<T> icarus::KeyValuesData::Item::convertStringInto ( std::string const &  valueStr ) const

inlineprivate

Conversion functions.

Definition at line 481 of file KeyValuesData.h.

      { return icarus::details::KeyValuesConverter<T>{}(valueStr); }

template<typename T , typename Iter , typename Conv >

std::vector< T > icarus::KeyValuesData::Item::convertVector ( Iter  begin, Iter  end, Conv  converter  ) const

private

Definition at line 778 of file KeyValuesData.h.

{
  std::vector<T> data;
  data.reserve(std::distance(begin, end));
  Iter it = begin;
  while (it != end) {
    std::string const& valueStr = *it;
    if (std::optional const number = converter(valueStr))
      data.push_back(*number);
    else {
      throw ConversionFailed::makeFor<T>
        (key(), std::distance(begin, it), valueStr);
    }
    ++it;
  } // while
  return data;
} // icarus::KeyValuesData::Item::convertVector()

template<typename T , typename Conv >

T icarus::KeyValuesData::Item::getAs	(	std::size_t	index,
		Conv	converter
	)		const

Returns the requested value, converted into type T

Template Parameters

T	type to convert the value into
Conv	type of a functor for conversion of the value into type T

Parameters

index	the index of the requested value
converter	a functor for conversion of the value into type T

Returns

the requested value as an object of type T

Exceptions

ValueNotAvailable	if no value is available with that index
ConversionFailed	if the value could not be converted to type T

Conversion is performed via converter object, functor taking a string and returning an object of type std::optional<T>. The functor can decline the conversion by returning an empty std::optional, or directly throw an exception on error.

Definition at line 678 of file KeyValuesData.h.

{
  
  if (index >= values().size()) throw ValueNotAvailable(key(), index);
  
  auto const& valueStr = values()[index];
  auto const number = converter(valueStr);
  return number? *number: throw ConversionFailed::makeFor<T>(key(), valueStr);
  
} // icarus::KeyValuesData::Item::getAs<>()

template<typename T >

T icarus::KeyValuesData::Item::getAs

(

std::size_t

index

)

const

Returns the requested value, converted into type T

Template Parameters

T	type to convert the value into

Parameters

index

the index of the requested value

Returns

the requested value as an object of type T

Exceptions

ValueNotAvailable	if no value is available with that index
ConversionFailed	if the value could not be converted to type T

Conversion is performed via an helper class icarus::details::KeyValuesConverter which can be specialized if needed, and that uses from_chars() for conversion.

Definition at line 692 of file KeyValuesData.h.

  { return getAs<T>(index, details::KeyValuesConverter<T>{}); }

template<typename T >

T icarus::KeyValuesData::Item::getNumber	(	std::size_t	index,
		unsigned int	base
	)		const

Returns the requested value, converted into a number of type T

Template Parameters

T	type of number to convert the value into

Parameters

index	the index of the requested value
base	(default: 10) numerical base of the input number

Returns

the requested value as a number of type T

Exceptions

ValueNotAvailable	if no value is available with that index
ConversionFailed	if the value could not be converted to type T

See getAs() for details.

Note that the number must have no base prefix (e.g. "F5" for hexadecimal rather than "0xF5").

Definition at line 724 of file KeyValuesData.h.

  { return getAs<T>(index, UseBase<T>{ base }); }

template<typename T >

T icarus::KeyValuesData::Item::getNumber

(

std::size_t

index

)

const

Definition at line 730 of file KeyValuesData.h.

  { return getAs<T>(index, details::KeyValuesConverter<T>{}); }

template<typename T , bool IgnoreFormatErrors, typename Conv >

std::optional< T > icarus::KeyValuesData::Item::getOptionalAs	(	std::size_t	index,
		Conv	converter
	)		const

Returns the requested value, converted into type T

Template Parameters

T	type to convert the value into
IgnoreFormatErrors	(default: true) how to treat conversion errors
Conv	type of a functor for conversion of the value into type T

Parameters

index	the index of the requested value
converter	a functor for conversion of the value into type T

Returns

the requested value, or an empty optional on failure

Exceptions

ConversionFailed

if the value could not be converted to type T

Conversion is performed via converter object, functor taking a string and returning an object of type std::optional<T>. The functor can decline the conversion by returning an empty std::optional, or directly throw an exception on error.

If no value is available for the specified index, an empty optional is returned.

An exception is thrown on conversion failures unless IgnoreFormatErrors is true, in which case an empty optional is also returned.

Definition at line 699 of file KeyValuesData.h.

{
  if (index < values().size()) return std::nullopt;

  auto const& valueStr = values()[index];
  auto const number = converter(valueStr);
  return (number || IgnoreFormatErrors)
    ? number: throw ConversionFailed::makeFor<T>(key(), valueStr);

} // icarus::KeyValuesData::Item::getOptionalAs()

template<typename T , bool IgnoreFormatErrors>

std::optional< T > icarus::KeyValuesData::Item::getOptionalAs

(

std::size_t

index

)

const

Returns the requested value, converted into type T

Template Parameters

T	type to convert the value into
IgnoreFormatErrors	(default: true) how to treat conversion errors

Parameters

index	the index of the requested value
ignoreFormatErrors	(default: false) ignore conversion errors

Returns

the requested value, or an empty optional on failure

Exceptions

ConversionFailed

if the value could not be converted to type T

Conversion is performed via converter object, functor taking a string and returning an object of type std::optional<T>. The functor can decline the conversion by returning an empty std::optional, or directly throw an exception on error.

If no value is available for the specified index, an empty optional is returned.

An exception is thrown on conversion failures unless IgnoreFormatErrors is true, in which case an empty optional is also returned.

Definition at line 714 of file KeyValuesData.h.

{
  return getOptionalAs<T, IgnoreFormatErrors>
    (index, details::KeyValuesConverter<T>{});
}

template<typename T >

std::optional< T > icarus::KeyValuesData::Item::getOptionalNumber	(	std::size_t	index,
		unsigned int	base
	)		const

Returns the requested value, converted into a number of type T

Template Parameters

T	type of number to convert the value into

Parameters

index	the index of the requested value
base	(default: 10) numerical base of the input number

Returns

the requested value, or an empty optional on failure

Exceptions

ConversionFailed

if the value could not be converted to type T

See getOptionalAs() for details.

Note that the number must have no base prefix (e.g. "F5" for hexadecimal rather than "0xF5").

Definition at line 737 of file KeyValuesData.h.

  { return getOptionalAs<T>(index, UseBase<T>{ base }); }

template<typename T >

std::optional< T > icarus::KeyValuesData::Item::getOptionalNumber

(

std::size_t

index

)

const

Definition at line 744 of file KeyValuesData.h.

  { return getOptionalAs<T>(index, details::KeyValuesConverter<T>{}); }

template<typename T , typename Conv >

std::vector< T > icarus::KeyValuesData::Item::getSizedVector

(

Conv

converter = Conv{}

)

const

Returns all the values, each converted into type T

Template Parameters

T	type to convert the value into
Conv	type of a functor for conversion of the value into type T

Parameters

converter

a functor for conversion of the value into type T

Returns

a vector with all the converted values

Exceptions

MissingSize	on any error converting the first value to a size
WrongSize	if the actual number of values does not match the size
ConversionFailed	if any value could not be converted to type T

The first value (mandatory) is converted to represent the size of the vector. That is used as verification when converting all the other elements: if there is the wrong number of elements, an exception is thrown.

Conversion of each element is performed by getAs<T, Conv>().

An exception is also thrown on conversion failure of any of the values.

Definition at line 761 of file KeyValuesData.h.

{
  
  if (values().empty()) throw MissingSize(key());
  
  std::size_t const n = getNumber<std::size_t>(0U);
  if (n != values().size() - 1)
    throw WrongSize(key(), n, values().size() - 1);
  
  return convertVector<T>
    (std::next(values().begin()), values().end(), std::move(converter));
} // icarus::KeyValuesData::Item::getSizedVector()

template<typename T , typename Conv >

std::vector< T > icarus::KeyValuesData::Item::getVector

(

Conv

converter = {}

)

const

Returns all the values, each converted into type T

Template Parameters

T	type to convert the value into
Conv	type of a functor for conversion of the value into type T

Parameters

converter

a functor for conversion of the value into type T

Returns

a vector with all the converted values

Exceptions

ConversionFailed

if any value could not be converted to type T

Conversion of each element is performed by getAs<T, Conv>().

An exception is thrown on any conversion failure.

Definition at line 751 of file KeyValuesData.h.

{
  return
    convertVector<T>(values().begin(), values().end(), std::move(converter));
}

std::size_t icarus::KeyValuesData::Item::nValues ( ) const

inlinenoexcept

Returns the number of values currently present.

Definition at line 277 of file KeyValuesData.h.

{ return values().size(); }

bool icarus::KeyValuesData::Item::operator< ( Item const &  other ) const

inlinenoexcept

Lexicographic order by key (case-sensitive).

Definition at line 469 of file KeyValuesData.h.

      { return key() < other.key(); }

---

The documentation for this struct was generated from the following file:

• KeyValuesData.h