util::MultipleChoiceSelection< typename > Class Template Reference

Helper to select one among multiple choices via strings. More...

#include <MultipleChoiceSelection.h>

Inheritance diagram for util::MultipleChoiceSelection< typename >:

Public Types
using	Choices_t = Choices
	Type of the underlying choice. More...
using	Option_t = details::MultipleChoiceSelectionOption_t< Choices_t >

Public Member Functions
	MultipleChoiceSelection ()=default
template<typename... Options>
	MultipleChoiceSelection (std::initializer_list< Option_t > options)
	Constructor: adds the specified options. More...
template<typename... Aliases>
auto	addOption (Choices_t value, std::string label, Aliases...aliases) -> Option_t const &
template<typename... Aliases>
auto	addAlias (Choices_t value, Aliases...aliases) -> std::enable_if_t< details::AllConvertibleToStrings_v< Aliases...>, Option_t const & >
template<typename... Aliases>
auto	addAlias (Option_t const &option, Aliases...aliases) -> std::enable_if_t< details::AllConvertibleToStrings_v< Aliases...>, Option_t const & >
template<typename... Aliases>
auto	recordLabels (std::size_t index, std::string alias, Aliases...moreAliases) -> std::enable_if_t< details::AllConvertibleToStrings_v< Aliases...>>
Option management
std::size_t	size () const
	Returns the number of available options. More...
bool	empty () const
	Returns whether there is no available option. More...
template<typename... Aliases>
Option_t const &	addOption (Choices_t value, std::string label, Aliases...aliases)
	Adds a new option to the selector. More...
template<typename... Aliases>
std::enable_if_t < details::AllConvertibleToStrings_v < Aliases...>, Option_t const & >	addAlias (Choices_t value, Aliases...aliases)
	Adds aliases to an existing option. More...
template<typename... Aliases>
std::enable_if_t < details::AllConvertibleToStrings_v < Aliases...>, Option_t const & >	addAlias (Option_t const &option, Aliases...aliases)
	Adds labels to an existing option. More...
bool	hasOption (Choices_t value) const
	Returns whether the selector has an option with the specified value. More...
bool	hasOption (std::string const &label) const
	Returns whether the selector has an option with the specified label. More...
bool	hasOption (Option_t const &option) const
	Returns if the specified option is present in the selector (by value). More...
Option access
Option_t const &	get (Choices_t value) const
	Returns the specified option. More...
Option_t const &	get (std::string const &label) const
	Returns the option with the specified label. More...
Option_t const &	parse (std::string const &label) const
	Returns the option matching the specified label. More...
Presentation and dumping
— BEGIN -------------------------------------------------------------—
std::string	optionListString (std::string const &sep=", ") const
	Returns a string with the (main) name of all options. More...
std::string	optionListDump (std::string const &indent, std::string const &firstIndent) const
	Returns a string with all the options, one per line. More...
std::string	optionListDump (std::string const &indent="") const
	Returns a string with all the options, one per line. More...

Private Types
using	Selector_t = MultipleChoiceSelection< Choices >
	This type. More...
using	OptionList_t = std::vector< Option_t >
	Type of collection of options. More...
using	OptionLabelMap_t = std::map< std::string, std::size_t, details::SorterFrom< details::CaseInsensitiveComparer > >
	Type of label index (associative container: label to option index). More...

Private Member Functions
Option_t const &	addOption (Option_t &&option)
	Moves the specified option into the list of registered options. More...
void	recordLabel (std::string &&label, std::size_t index)
template<typename... Aliases>
std::enable_if_t < details::AllConvertibleToStrings_v < Aliases...> >	recordLabels (std::size_t index, std::string alias, Aliases...moreAliases)
void	unregisterLabel (std::string const &label)
	Removes the specified label from the register. More...
Option_t &	get (Choices_t value)
OptionList_t::const_iterator	findOption (Choices_t value) const
	Returns an iterator to the option with label, or npos if none. More...
OptionList_t::iterator	findOption (Choices_t value)
	Returns an iterator to the option with label, or npos if none. More...
std::size_t	findOptionIndex (Choices_t value) const
	Returns the index of the option with label, or npos if none. More...
std::size_t	findOptionIndex (std::string const &label) const
	Returns the index of the option with label, or npos if none. More...

Private Attributes
OptionList_t	fOptions
	The list of registered objects. More...
OptionLabelMap_t	fLabelToOptionIndex
	Map from labels to option index in fOptions. More...

Static Private Attributes
static constexpr auto	npos = std::numeric_limits<std::size_t>::max()
	Special value. More...

Detailed Description

template<typename>
class util::MultipleChoiceSelection< typename >

Helper to select one among multiple choices via strings.

Template Parameters

Choices

type describing the choices

Note

If the type to describe the choice is a string, its value still need to be explicitly added as an option label.

Definition at line 204 of file MultipleChoiceSelection.h.

Member Typedef Documentation

template<typename >

using util::MultipleChoiceSelection< typename >::Choices_t = Choices

Type of the underlying choice.

Definition at line 222 of file MultipleChoiceSelection.h.

template<typename >

using util::MultipleChoiceSelection< typename >::Option_t = details::MultipleChoiceSelectionOption_t<Choices_t>

Definition at line 224 of file MultipleChoiceSelection.h.

template<typename >

using util::MultipleChoiceSelection< typename >::OptionLabelMap_t = std::map< std::string, std::size_t, details::SorterFrom<details::CaseInsensitiveComparer> >

private

Type of label index (associative container: label to option index).

Definition at line 388 of file MultipleChoiceSelection.h.

template<typename >

using util::MultipleChoiceSelection< typename >::OptionList_t = std::vector<Option_t>

private

Type of collection of options.

— END ------------------------------------------------------------——

Definition at line 382 of file MultipleChoiceSelection.h.

template<typename >

using util::MultipleChoiceSelection< typename >::Selector_t = MultipleChoiceSelection<Choices>

private

This type.

Definition at line 217 of file MultipleChoiceSelection.h.

Constructor & Destructor Documentation

template<typename >

util::MultipleChoiceSelection< typename >::MultipleChoiceSelection ( )

default

Default constructor: flags are set to DefaultFlags, options may be added later.

template<typename Choices >

template<typename... Options>

util::MultipleChoiceSelection< Choices >::MultipleChoiceSelection

(

std::initializer_list< Option_t >

options

)

Constructor: adds the specified options.

Template Parameters

Options

a number of Option_t objects

Parameters

options

a list of options to add to the selector

All specified options are added as with addOption().

Definition at line 806 of file MultipleChoiceSelection.h.

{
  for (Option_t option: options) addOption(std::move(option));
} // util::MultipleChoiceSelection<>::MultipleChoiceSelection()

Member Function Documentation

template<typename >

template<typename... Aliases>

std::enable_if_t<details::AllConvertibleToStrings_v<Aliases...>, Option_t const&> util::MultipleChoiceSelection< typename >::addAlias	(	Choices_t	value,
		Aliases...	aliases
	)

Adds aliases to an existing option.

Template Parameters

Args	any number of std::string

Parameters

value	the value of the option to assign labels to
aliases	the additional alias(es) to assign to this option

Returns

the option being changed

Exceptions

UnknownOptionError

if no option with value is registered yet

template<typename >

template<typename... Aliases>

std::enable_if_t<details::AllConvertibleToStrings_v<Aliases...>, Option_t const&> util::MultipleChoiceSelection< typename >::addAlias	(	Option_t const &	option,
		Aliases...	aliases
	)

Adds labels to an existing option.

Template Parameters

Aliases

any number of std::string

Parameters

option	the option to assign labels to
aliases	the additional alias(es) to assign to this option

Returns

the option being changed

Exceptions

UnknownOptionError

if no option with value is registered yet

The option with the same value as the option argument is assigned the specified aliases.

template<typename >

template<typename... Aliases>

auto util::MultipleChoiceSelection< typename >::addAlias	(	Choices_t	value,
		Aliases...	aliases
	)		-> std::enable_if_t <details::AllConvertibleToStrings_v<Aliases...>, Option_t const&>

Definition at line 838 of file MultipleChoiceSelection.h.

{
  std::size_t const index = findOptionIndex(value);
  if (index >= fOptions.size())
    throw UnknownOptionError(Option_t::value_as_string(value, ""));
  recordLabels(index, aliases...);
  return fOptions[index].addAlias(std::move(aliases)...);
} // util::MultipleChoiceSelection<>::addAlias()

template<typename >

template<typename... Aliases>

auto util::MultipleChoiceSelection< typename >::addAlias	(	Option_t const &	option,
		Aliases...	aliases
	)		-> std::enable_if_t <details::AllConvertibleToStrings_v<Aliases...>, Option_t const&>

Definition at line 854 of file MultipleChoiceSelection.h.

{
  return addAlias(option.value(), std::move(aliases)...);
} // util::MultipleChoiceSelection<>::addAlias()

template<typename >

template<typename... Aliases>

Option_t const& util::MultipleChoiceSelection< typename >::addOption	(	Choices_t	value,
		std::string	label,
		Aliases...	aliases
	)

Adds a new option to the selector.

Template Parameters

Aliases

any number of std::string

Parameters

value	the value of the new option
label	the first label to associate to the option
aliases	additional aliases for this option

Returns

the newly created option

Exceptions

OptionAlreadyExistsError

if there is already an option with value

See Also

addAlias()

An option must always have a label; aliases are instead optional. There must be no existing option with the specified value, otherwise an exception will be thrown with the label of the existing option. To add aliases to an existing option, use addAlias() instead. Currently, it is not possible to change a label after having added it.

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::addOption ( Option_t &&  option )

private

Moves the specified option into the list of registered options.

Parameters

option

the option to move

Returns

the newly added option

Exceptions

OptionAlreadyExistsError

if there is already an option with the same value or any of the labels; in that case, label() method of the exception will report the offending label of option or its name if it is the value to be duplicated

Definition at line 966 of file MultipleChoiceSelection.h.

{
  std::size_t const newOptionIndex = size();
  
  fOptions.push_back(std::move(option));
  Option_t const& newOption = fOptions.back();
  auto const& labels = newOption.labels();
  for (auto iLabel = labels.begin(); iLabel != labels.end(); ++iLabel) {
    try {
      recordLabel(std::string{ *iLabel }, newOptionIndex);
    }
    catch (OptionAlreadyExistsError const&) {
      // we attempt to offer a strong guarantee here,
      // that the object is restored in the state it was before the call
      
      // remove the new entries from the index
      // (*iLabel was not inserted, and all labels before it were new)
      for (auto iNewLabel = labels.begin(); iNewLabel != iLabel; ++iNewLabel)
        unregisterLabel(*iNewLabel);
      
      // remove the new option from the list
      fOptions.pop_back();
      
      // let the caller handle the rest
      throw;
    } // try ... catch
  } // for labels
  
  return newOption;
} // util::MultipleChoiceSelection<>::addOption()

template<typename >

template<typename... Aliases>

auto util::MultipleChoiceSelection< typename >::addOption	(	Choices_t	value,
		std::string	label,
		Aliases...	aliases
	)		-> Option_t const&

Definition at line 828 of file MultipleChoiceSelection.h.

{
  return addOption({ value, std::move(label), std::move(aliases)... });
} // util::MultipleChoiceSelection<>::addOption()

template<typename Choices >

bool util::MultipleChoiceSelection< Choices >::empty

(

)

const

Returns whether there is no available option.

Definition at line 820 of file MultipleChoiceSelection.h.

  { return fOptions.empty(); }

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::findOption ( Choices_t  value ) const

private

Returns an iterator to the option with label, or npos if none.

Definition at line 1052 of file MultipleChoiceSelection.h.

{
  auto const matchValue
    = [value](Option_t const& option){ return option.value() == value; };
  return std::find_if(fOptions.begin(), fOptions.end(), matchValue);
} // util::MultipleChoiceSelection<>::findOption(value) const

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::findOption ( Choices_t  value )

private

Returns an iterator to the option with label, or npos if none.

Definition at line 1063 of file MultipleChoiceSelection.h.

{
  auto const matchValue
    = [value](Option_t const& option){ return option.value() == value; };
  return std::find_if(fOptions.begin(), fOptions.end(), matchValue);
} // util::MultipleChoiceSelection<>::findOption(value)

template<typename Choices >

std::size_t util::MultipleChoiceSelection< Choices >::findOptionIndex ( Choices_t  value ) const

private

Returns the index of the option with label, or npos if none.

Definition at line 1075 of file MultipleChoiceSelection.h.

{
  auto const d = static_cast<std::size_t>
    (std::distance(fOptions.begin(), findOption(value)));
  return (d >= size())? npos: d;
} // util::MultipleChoiceSelection<>::findOptionIndex(value) const

template<typename Choices >

std::size_t util::MultipleChoiceSelection< Choices >::findOptionIndex ( std::string const &  label ) const

private

Returns the index of the option with label, or npos if none.

Definition at line 1086 of file MultipleChoiceSelection.h.

{
  auto const iOption = fLabelToOptionIndex.find(label);
  return (iOption == fLabelToOptionIndex.end())? npos: iOption->second;
} // util::MultipleChoiceSelection<>::findOptionIndex(string) const

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::get

(

Choices_t

value

)

const

Returns the specified option.

Parameters

value

value of the requested option

Returns

the requested option

Exceptions

UnknownOptionError

if there is no available option with value (the string of the exception is empty)

Definition at line 886 of file MultipleChoiceSelection.h.

{
  auto const iOption = findOption(value);
  if (iOption == fOptions.end())
    throw UnknownOptionError(Option_t::value_as_string(value).value_or(""));
  return *iOption;
} // util::MultipleChoiceSelection<>::get(value)

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::get

(

std::string const &

label

)

const

Returns the option with the specified label.

Parameters

label

label of the requested option

Returns

the requested option

Exceptions

UnknownOptionError

if there is no available option with label (the string of the exception shows label value)

Definition at line 898 of file MultipleChoiceSelection.h.

{
  auto const iLabelIndexPair = fLabelToOptionIndex.find(label);
  if (iLabelIndexPair == fLabelToOptionIndex.end()) {
    throw UnknownOptionError(label);
  }
  assert(iLabelIndexPair->second < fOptions.size());
  return fOptions[iLabelIndexPair->second];
} // util::MultipleChoiceSelection<>::get(string)

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::get ( Choices_t  value )

private

Retrieves the option with the specified value.

Exceptions

UnknownOptionError

if there is no available option with value

Definition at line 1095 of file MultipleChoiceSelection.h.

                                                                           {
  auto const iOption = findOption(value);
  if (iOption == fOptions.end()) {
    throw UnknownOptionError(Option_t::value_as_string(value).value_or(""));
  }
  return *iOption;
} // util::MultipleChoiceSelection<>::get()

template<typename Choices >

bool util::MultipleChoiceSelection< Choices >::hasOption

(

Choices_t

value

)

const

Returns whether the selector has an option with the specified value.

Definition at line 864 of file MultipleChoiceSelection.h.

  { return findOption(value) != fOptions.end(); }

template<typename Choices >

bool util::MultipleChoiceSelection< Choices >::hasOption

(

std::string const &

label

)

const

Returns whether the selector has an option with the specified label.

Definition at line 871 of file MultipleChoiceSelection.h.

{
  return fLabelToOptionIndex.find(label) != fLabelToOptionIndex.end();
} // util::MultipleChoiceSelection<>::hasOption(string)

template<typename Choices >

bool util::MultipleChoiceSelection< Choices >::hasOption

(

Option_t const &

option

)

const

Returns if the specified option is present in the selector (by value).

Definition at line 880 of file MultipleChoiceSelection.h.

  { return hasOption(option.value()); }

template<typename Choices >

std::string util::MultipleChoiceSelection< Choices >::optionListDump	(	std::string const &	indent,
		std::string const &	firstIndent
	)		const

Returns a string with all the options, one per line.

Definition at line 943 of file MultipleChoiceSelection.h.

{
  using namespace std::string_literals;

  auto iOption = fOptions.begin();
  auto const oend = fOptions.end();

  if (iOption == oend) return firstIndent + "<no options>\n"s;

  std::string s { firstIndent };
  s += iOption->dump();
  s += '\n';
  while (++iOption != oend) {
    s += indent;
    s += iOption->dump();
    s += '\n';
  } // while
  return s;
} // util::MultipleChoiceSelection<>::optionListDump()

template<typename >

std::string util::MultipleChoiceSelection< typename >::optionListDump ( std::string const &  indent = "" ) const

inline

Returns a string with all the options, one per line.

Definition at line 372 of file MultipleChoiceSelection.h.

    { return optionListDump(indent, indent); }

template<typename Choices >

std::string util::MultipleChoiceSelection< Choices >::optionListString

(

std::string const &

sep = ", "

)

const

Returns a string with the (main) name of all options.

Definition at line 922 of file MultipleChoiceSelection.h.

{
  using namespace std::string_literals;

  auto iOption = fOptions.begin();
  auto const oend = fOptions.end();

  if (iOption == oend) return "<no options>"s;

  std::string s { *iOption };
  while (++iOption != oend) {
    s += sep;
    s += *iOption;
  } // while
  return s;
} // util::MultipleChoiceSelection<>::optionListString()

template<typename Choices >

auto util::MultipleChoiceSelection< Choices >::parse

(

std::string const &

label

)

const

Returns the option matching the specified label.

Parameters

label

label of the requested option

Returns

the requested option

Exceptions

UnknownOptionError

if there is no available option with label (the string of the exception shows label value)

Definition at line 913 of file MultipleChoiceSelection.h.

{
  return get(label);
} // util::MultipleChoiceSelection<>::parse()

template<typename Choices >

void util::MultipleChoiceSelection< Choices >::recordLabel ( std::string &&  label, std::size_t  index  )

private

Associates label to the option at index.

Exceptions

OptionAlreadyExistsError

if there is already an option with label

Definition at line 1002 of file MultipleChoiceSelection.h.

{
  
  auto const iOption = fLabelToOptionIndex.lower_bound(label);
  
  // check for duplicate entries: if iOption is not `end()`, it points to an
  // element whose key is either greater or equal (equivalent) to `label`;
  // if the key is greater than `label`, we are good:
  // we check it by requiring that `label` is smaller than the key;
  // `key_compare(a, b)` comparison is equivalent to `a < b`,
  if ((iOption != fLabelToOptionIndex.end())
    && !OptionLabelMap_t::key_compare()(label, iOption->first))
  {
    throw OptionAlreadyExistsError(label); // maybe too terse?
  }
  
  // the actual recording, at last:
  fLabelToOptionIndex.emplace_hint(iOption, std::move(label), index);
  
} // util::MultipleChoiceSelection<>::recordLabel()

template<typename >

template<typename... Aliases>

std::enable_if_t<details::AllConvertibleToStrings_v<Aliases...> > util::MultipleChoiceSelection< typename >::recordLabels ( std::size_t  index, std::string  alias, Aliases...  moreAliases  )

private

Associates all labels to the option at index.

Exceptions

OptionAlreadyExistsError

if there is already an option with any of the aliases

template<typename >

template<typename... Aliases>

auto util::MultipleChoiceSelection< typename >::recordLabels	(	std::size_t	index,
		std::string	alias,
		Aliases...	moreAliases
	)		-> std::enable_if_t<details::AllConvertibleToStrings_v<Aliases...>>

Definition at line 1028 of file MultipleChoiceSelection.h.

{
  try {
    recordLabel(std::move(alias), index);
    if constexpr(sizeof...(moreAliases) > 0U)
      recordLabels(index, std::move(moreAliases)...);
  }
  catch (OptionAlreadyExistsError const&) {
    unregisterLabel(alias); // if recordLabel() call threw alias is still intact
    throw;
  }
} // util::MultipleChoiceSelection<>::recordLabels()

template<typename Choices >

std::size_t util::MultipleChoiceSelection< Choices >::size

(

)

const

Returns the number of available options.

Definition at line 814 of file MultipleChoiceSelection.h.

  { return fOptions.size(); }

template<typename Choices >

void util::MultipleChoiceSelection< Choices >::unregisterLabel ( std::string const &  label )

private

Removes the specified label from the register.

Definition at line 1046 of file MultipleChoiceSelection.h.

  { fLabelToOptionIndex.erase(label); }

Member Data Documentation

template<typename >

OptionLabelMap_t util::MultipleChoiceSelection< typename >::fLabelToOptionIndex

private

Map from labels to option index in fOptions.

Definition at line 394 of file MultipleChoiceSelection.h.

template<typename >

OptionList_t util::MultipleChoiceSelection< typename >::fOptions

private

The list of registered objects.

Definition at line 391 of file MultipleChoiceSelection.h.

template<typename >

constexpr auto util::MultipleChoiceSelection< typename >::npos = std::numeric_limits<std::size_t>::max()

staticprivate

Special value.

Definition at line 442 of file MultipleChoiceSelection.h.

---

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

• MultipleChoiceSelection.h