Type classification and string conversion. More...

#include <cerrno>
import cli11:string_tools;
import std;

Classes
struct	cli::is_member_type_t< T >
	Maps a type to the one used to store it in a member set. More...
struct	cli::is_member_type_t< const char * >
	Stores string literals as std::string. More...
struct	cli::detail::element_type< T >
	The type a pointer-like type points at, or the type itself. More...
struct	cli::detail::element_type< T >
	Unwraps pointer-like types. More...
struct	cli::detail::element_value_type< T >
	The value_type of a container, seen through any pointer. More...
struct	cli::detail::pair_adaptor< T >
	Uniform access to the halves of a container's element. More...
struct	cli::detail::pair_adaptor< T >
	Adapts containers whose elements really are pairs. More...
struct	cli::detail::type_count_base< T >
	How many values a type consumes, ignoring nesting. More...
struct	cli::detail::type_count_base< T >
	Scalars consume one value. More...
struct	cli::detail::wrapped_type< T, def_t >
	The type inside a wrapper, or a supplied default. More...
struct	cli::detail::wrapped_type< T, def_t >
	Unwraps types with a nested value_type. More...
struct	cli::detail::type_count< T >
	How many values a type consumes, counting nested elements. More...
struct	cli::detail::type_count< T >
	Plain scalars consume one value. More...
struct	cli::detail::subtype_count< T >
	Value count of a nested type, treating containers as unbounded. More...
struct	cli::detail::type_count_min< T >
	The minimum number of values a type will accept. More...
struct	cli::detail::type_count_min< T >
	Plain scalars require their full count. More...
struct	cli::detail::subtype_count_min< T >
	Minimum value count of a nested type. More...
struct	cli::detail::expected_count< T >
	How many separate command-line appearances a type expects. More...
struct	cli::detail::expected_count< T >
	Plain types expect a single appearance. More...
struct	cli::detail::classify_object< T >
	Sorts a type into an object_category_t. More...
struct	cli::detail::classify_object< T >

Concepts
concept	cli::bool_like
	Matches exactly bool, excluding types merely convertible to it.
concept	cli::shared_ptr_like
	Matches std::shared_ptr, with or without top-level const.
concept	cli::copyable_ptr
	Matches pointer-like types that can be copied freely.
concept	cli::adl_detail::lexical_castable
	Matches types with a lexical_cast overload findable by ADL.
concept	cli::detail::pair_valued
	Matches containers whose elements are pair-like.
concept	cli::detail::direct_constructible
	Matches types brace-constructible from `C` without narrowing.
concept	cli::detail::ostreamable
	Matches types that can be written to an output stream.
concept	cli::detail::istreamable
	Matches types that can be read from an input stream.
concept	cli::detail::complex_like
	Matches complex-number-like types, by their accessors.
concept	cli::detail::mutable_container
	Matches containers that can be cleared and inserted into.
concept	cli::detail::readable_container
	Matches anything that can be iterated over.
concept	cli::detail::wrapper_like
	Matches types with a nested value_type, such as std::optional.
concept	cli::detail::tuple_like
	Matches types usable with std::tuple_size, excluding complex numbers.
concept	cli::detail::string_convertible
	Matches types implicitly convertible to std::string.
concept	cli::detail::string_buildable
	Matches types a std::string can be constructed from.
concept	cli::detail::plain_object
	Matches types with no string conversion and no stream insertion.
concept	cli::detail::wide_string_guard
	Excludes wide-string conversions when classifying narrow strings.
concept	cli::detail::narrow_string_guard
	Excludes narrow-string conversions when classifying wide strings.
concept	cli::detail::uncommon
	Matches types none of the ordinary categories claim.
concept	cli::detail::char_value_like
	Matches types classified as a single character.
concept	cli::detail::integral_value_like
	Matches types classified as a signed integer.
concept	cli::detail::unsigned_integral_like
	Matches types classified as an unsigned integer.
concept	cli::detail::enumeration_like
	Matches types classified as an enumeration.
concept	cli::detail::boolean_value_like
	Matches types classified as a boolean.
concept	cli::detail::floating_point_like
	Matches types classified as floating point.
concept	cli::detail::number_constructible_like
	Matches types constructible from either int or double.
concept	cli::detail::double_constructible_like
	Matches types constructible from double only.
concept	cli::detail::integer_constructible_like
	Matches types constructible from int only.
concept	cli::detail::string_assignable_like
	Matches types assignable from std::string.
concept	cli::detail::string_constructible_like
	Matches types constructible from std::string.
concept	cli::detail::wstring_assignable_like
	Matches types assignable from std::wstring.
concept	cli::detail::wstring_constructible_like
	Matches types constructible from std::wstring.
concept	cli::detail::other_like
	Matches types that fell through every other classification.
concept	cli::detail::wrapper_value_like
	Matches types classified as a wrapper around a nested type.
concept	cli::detail::complex_number_like
	Matches types classified as a complex number.
concept	cli::detail::tuple_value_like
	Matches types classified as a tuple.
concept	cli::detail::container_value_like
	Matches types classified as a container.
concept	cli::detail::text_like
	Matches every string-like category, plus object_category_t::other.
concept	cli::detail::string_like_category
	Matches the four string-like categories as a group.

Enumerations
enum class	cli::detail::object_category_t : std::uint8_t { char_value = 1 , integral_value = 2 , unsigned_integral = 4 , enumeration = 6 , boolean_value = 8 , floating_point = 10 , number_constructible = 12 , double_constructible = 14 , integer_constructible = 16 , string_assignable = 23 , string_constructible = 24 , wstring_assignable = 25 , wstring_constructible = 26 , other = 45 , wrapper_value = 50 , complex_number = 60 , tuple_value = 70 , container_value = 80 }
	The classification buckets a type can fall into. More...

Functions
template<istreamable T>
auto	cli::detail::from_stream (const std::string &istring, T &obj) -> bool
	Reads a value from a string using its stream extraction operator.
template<typename T> requires (!istreamable<T>)
auto	cli::detail::from_stream (const std::string &, T &) -> bool
	Fallback for types with no stream extraction operator.
template<string_convertible T>
auto	cli::detail::to_string (T &&value) -> decltype(std::forward< T >(value))
	Renders a value already convertible to a string.
template<typename T> requires (string_buildable<T> && !string_convertible<T>)
auto	cli::detail::to_string (T &&value) -> std::string
	Renders a value a string can be built from.
template<typename T> requires (!string_convertible<T> && !string_buildable<T> && ostreamable<T>)
auto	cli::detail::to_string (T &&value) -> std::string
	Renders a value through its stream insertion operator.
template<typename T> requires (plain_object<T> && tuple_like<T> && type_count_base_v<T> == 1)
auto	cli::detail::to_string (T &&value) -> std::string
	Renders a single-element tuple as its one element.
template<typename T> requires (plain_object<T> && tuple_like<T> && type_count_base_v<T> >= 2)
auto	cli::detail::to_string (T &&value) -> std::string
	Renders a multi-element tuple as a bracketed list.
template<typename T> requires (plain_object<T> && !readable_container<std::remove_const_t<T>> && !tuple_like<T>)
auto	cli::detail::to_string (T &&) -> std::string
	Renders anything with no usable representation as an empty string.
template<typename T> requires (plain_object<T> && readable_container<T> && !tuple_like<T>)
auto	cli::detail::to_string (T &&variable) -> std::string
	Renders a container as a bracketed, comma-separated list.
template<typename T, std::size_t I> requires (I == type_count_base_v<T>)
auto	cli::detail::tuple_value_string (T &&) -> std::string
	Terminates the tuple rendering recursion.
template<typename T, std::size_t I> requires (I < type_count_base_v<T>)
auto	cli::detail::tuple_value_string (T &&value) -> std::string
	Renders tuple elements from index `I` onward.
template<typename lhs_t, typename rhs_t, typename T> requires std::same_as<lhs_t, rhs_t>
auto	cli::detail::checked_to_string (T &&value) -> decltype(to_string(std::forward< T >(value)))
	Renders a value only when two types agree.
template<typename lhs_t, typename rhs_t, typename T> requires (!std::same_as<lhs_t, rhs_t>)
auto	cli::detail::checked_to_string (T &&) -> std::string
	Renders nothing when the two types differ.
template<typename T> requires std::is_arithmetic_v<T>
auto	cli::detail::value_string (const T &value) -> std::string
	Renders an arithmetic value.
template<typename T> requires std::is_enum_v<T>
auto	cli::detail::value_string (const T &value) -> std::string
	Renders an enumerator as its underlying integer.
template<typename T> requires (!std::is_enum_v<T> && !std::is_arithmetic_v<T>)
auto	cli::detail::value_string (const T &value) -> decltype(to_string(value))
	Renders any other value through to_string.
template<typename T, std::size_t I> requires (I == type_count_base_v<T>)
constexpr auto	cli::detail::tuple_type_size () -> int
	Terminates the tuple size recursion.
template<typename T, std::size_t I> requires (I < type_count_base_v<T>)
constexpr auto	cli::detail::tuple_type_size () -> int
	Sums the value counts of tuple elements from index `I` onward.
template<typename T, std::size_t I> requires (I == type_count_base_v<T>)
constexpr auto	cli::detail::tuple_type_size_min () -> int
	Terminates the minimum tuple size recursion.
template<typename T, std::size_t I> requires (I < type_count_base_v<T>)
constexpr auto	cli::detail::tuple_type_size_min () -> int
	Sums the minimum counts of tuple elements from index `I` onward.
template<char_value_like T>
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for a character option.
template<typename T> requires (integral_value_like<T> \|\| integer_constructible_like<T>)
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for a signed integer option.
template<unsigned_integral_like T>
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for an unsigned integer option.
template<typename T> requires (floating_point_like<T> \|\| number_constructible_like<T> \|\| double_constructible_like<T>)
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for a floating-point option.
template<enumeration_like T>
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for an enumeration option.
template<boolean_value_like T>
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for a boolean option.
template<complex_number_like T>
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for a complex-number option.
template<text_like T>
constexpr auto	cli::detail::type_name () -> const char *
	Returns the name shown for a textual option.
template<typename T> requires (tuple_value_like<T> && type_count_base_v<T> >= 2)
auto	cli::detail::type_name () -> std::string
	Returns the bracketed name shown for a multi-element tuple option.
template<typename T> requires (container_value_like<T> \|\| wrapper_value_like<T>)
auto	cli::detail::type_name () -> std::string
	Returns the name of the element type of a container or wrapper.
template<typename T> requires (tuple_value_like<T> && type_count_base_v<T> == 1)
auto	cli::detail::type_name () -> std::string
	Returns the name of a single-element tuple's one element.
template<typename T, std::size_t I> requires (I == type_count_base_v<T>)
auto	cli::detail::tuple_name () -> std::string
	Terminates the tuple name recursion.
template<typename T, std::size_t I> requires (I < type_count_base_v<T>)
auto	cli::detail::tuple_name () -> std::string
	Renders the names of tuple elements from index `I` onward.
template<typename T> requires std::is_unsigned_v<T>
auto	cli::detail::integral_conversion (const std::string &input, T &output) noexcept -> bool
	Parses an unsigned integer, accepting several notations.
template<typename T> requires std::is_signed_v<T>
auto	cli::detail::integral_conversion (const std::string &input, T &output) noexcept -> bool
	Parses a signed integer, accepting several notations.
auto	cli::detail::to_flag_value (std::string val) noexcept -> std::int64_t
	Interprets a string as a tri-state flag value.
auto	cli::detail::sum_string_vector (const std::vector< std::string > &values) -> std::string
	Sums a list of values, falling back to concatenation.
Single-value conversion
lexical_cast turns one command-line token into one value. There is an overload per object_category_t; exactly one is viable for any given type.
template<typename T> requires (integral_value_like<T> \|\| unsigned_integral_like<T>)
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to an integer.
template<char_value_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to a character, accepting a numeric code point.
template<boolean_value_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to a boolean.
template<floating_point_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to a floating-point value.
template<complex_number_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token such as "3+4i" to a complex number.
template<string_assignable_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Assigns a token directly to a string-assignable type.
template<string_constructible_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Constructs a string-constructible type from a token.
template<wstring_assignable_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Widens a token and assigns it.
template<wstring_constructible_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Widens a token and constructs from it.
template<enumeration_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to an enumerator via its underlying type.
template<typename T> requires (wrapper_value_like<T> && std::is_assignable_v<T &, typename T::value_type>)
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token into a wrapper by assigning the inner value.
template<typename T> requires (wrapper_value_like<T> && !std::is_assignable_v<T &, typename T::value_type> && std::is_assignable_v<T &, T>)
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token into a wrapper by rebuilding the wrapper.
template<number_constructible_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to a type constructible from int or double.
template<integer_constructible_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to a type constructible from int.
template<double_constructible_like T>
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to a type constructible from double.
template<typename T> requires (other_like<T> && std::is_assignable_v<T &, int>)
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to an unclassified type assignable from int.
template<typename T> requires (other_like<T> && !std::is_assignable_v<T &, int> && istreamable<T>)
auto	cli::detail::lexical_cast (const std::string &input, T &output) -> bool
	Converts a token to an unclassified type using its >> operator.
template<typename T> requires (other_like<T> && !std::is_assignable_v<T &, int> && !istreamable<T> && !adl_detail::lexical_castable<T>)
auto	cli::detail::lexical_cast (const std::string &, T &) -> bool
	Rejects types with no available conversion.
Assignment
lexical_assign converts a token to convert_to_t and then gets that value into an assign_to_t, which is not always the same type.
template<typename assign_to_t, typename convert_to_t> requires (std::same_as<assign_to_t, convert_to_t> && string_like_category<assign_to_t>)
auto	cli::detail::lexical_assign (const std::string &input, assign_to_t &output) -> bool
	Assigns a token to a string-like destination.
template<typename assign_to_t, typename convert_to_t> requires (std::same_as<assign_to_t, convert_to_t> && std::is_assignable_v<assign_to_t &, assign_to_t> && !string_like_category <assign_to_t>)
auto	cli::detail::lexical_assign (const std::string &input, assign_to_t &output) -> bool
	Assigns a token to a self-assignable destination.
template<typename assign_to_t, typename convert_to_t> requires (std::same_as<assign_to_t, convert_to_t> && !std::is_assignable_v<assign_to_t &, assign_to_t> && wrapper_value_like <assign_to_t>)
auto	cli::detail::lexical_assign (const std::string &input, assign_to_t &output) -> bool
	Assigns a token to a wrapper that is not self-assignable.
template<typename assign_to_t, typename convert_to_t> requires (std::same_as<assign_to_t, convert_to_t> && !std::is_assignable_v<assign_to_t &, assign_to_t> && !wrapper_value_like <assign_to_t> && std::is_assignable_v<assign_to_t &, int>)
auto	cli::detail::lexical_assign (const std::string &input, assign_to_t &output) -> bool
	Assigns a token to a destination reachable only through int.
template<typename assign_to_t, typename convert_to_t> requires (!std::same_as<assign_to_t, convert_to_t> && std::is_assignable_v<assign_to_t &, convert_to_t &>)
auto	cli::detail::lexical_assign (const std::string &input, assign_to_t &output) -> bool
	Converts through an intermediate type, then assigns.
template<typename assign_to_t, typename convert_to_t> requires (!std::same_as<assign_to_t, convert_to_t> && !std::is_assignable_v<assign_to_t &, convert_to_t &> && std::is_move_assignable_v<assign_to_t>)
auto	cli::detail::lexical_assign (const std::string &input, assign_to_t &output) -> bool
	Converts through an intermediate type, then constructs.
List conversion
lexical_conversion turns a whole list of tokens into one value, distributing them across tuple elements or container entries as needed.
template<typename assign_to_t, typename convert_to_t> requires (classify_object_v<convert_to_t> <= object_category_t::other && classify_object_v<assign_to_t> <= object_category_t::wrapper_value)
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a single-value type from the first token.
template<typename assign_to_t, typename convert_to_t> requires ((type_count_v<assign_to_t> <= 2) && expected_count_v<assign_to_t> == 1 && tuple_like<convert_to_t> && type_count_base_v <convert_to_t> == 2)
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a two-element tuple from up to two tokens.
template<typename assign_to_t, typename convert_to_t> requires (mutable_container<assign_to_t> && mutable_container<convert_to_t> && type_count_v<convert_to_t> == 1)
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a container of single-value elements.
template<typename assign_to_t, typename convert_to_t> requires complex_like<convert_to_t>
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a complex number from one or two tokens.
template<typename assign_to_t, typename convert_to_t> requires (mutable_container<assign_to_t> && (expected_count_v<convert_to_t> == 1) && (type_count_v<convert_to_t> == 1))
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Fills a container, one element per token.
template<typename assign_to_t, typename convert_to_t> requires (mutable_container<assign_to_t> && mutable_container<convert_to_t> && type_count_base_v<convert_to_t> == 2)
auto	cli::detail::lexical_conversion (std::vector< std::string > strings, assign_to_t &output) -> bool
	Converts a container of pairs, consuming tokens two at a time.
template<typename assign_to_t, typename convert_to_t> requires (mutable_container<assign_to_t> && mutable_container<convert_to_t> && type_count_base_v<convert_to_t> != 2 && ((type_count_v<convert_to_t> > 2) \|\| (type_count_v<convert_to_t> > type_count_base_v<convert_to_t>)))
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a container whose elements consume several tokens each.
template<typename assign_to_t, typename convert_to_t> requires (tuple_like<assign_to_t> && tuple_like<convert_to_t> && (type_count_base_v<convert_to_t> != type_count_v<convert_to_t> \|\| type_count_v<convert_to_t> > 2))
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a tuple whose elements are themselves compound.
template<typename assign_to_t, typename convert_to_t> requires (!tuple_like<assign_to_t> && !mutable_container<assign_to_t> && !wrapper_value_like<convert_to_t> && (mutable_container <convert_to_t> \|\| type_count_v<convert_to_t> > 2))
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts a compound source into a scalar destination.
template<typename assign_to_t, typename convert_to_t, std::size_t I> requires (I >= type_count_base_v<assign_to_t>)
auto	cli::detail::tuple_conversion (const std::vector< std::string > &, assign_to_t &) -> bool
	Terminates the tuple conversion recursion.
template<typename assign_to_t, typename convert_to_t> requires (!mutable_container<convert_to_t> && type_count_v<convert_to_t> == 1)
auto	cli::detail::tuple_type_conversion (std::vector< std::string > &strings, assign_to_t &output) -> bool
	Consumes one token for a single-value tuple element.
template<typename assign_to_t, typename convert_to_t> requires (!mutable_container<convert_to_t> && (type_count_v<convert_to_t> > 1) && type_count_v<convert_to_t> == type_count_min_v <convert_to_t>)
auto	cli::detail::tuple_type_conversion (std::vector< std::string > &strings, assign_to_t &output) -> bool
	Consumes a fixed number of tokens for a compound tuple element.
template<typename assign_to_t, typename convert_to_t> requires (mutable_container<convert_to_t> \|\| type_count_v<convert_to_t> != type_count_min_v<convert_to_t>)
auto	cli::detail::tuple_type_conversion (std::vector< std::string > &strings, assign_to_t &output) -> bool
	Consumes a variable number of tokens, stopping at a separator.
template<typename assign_to_t, typename convert_to_t, std::size_t I> requires (I < type_count_base_v<assign_to_t>)
auto	cli::detail::tuple_conversion (std::vector< std::string > strings, assign_to_t &output) -> bool
	Fills tuple element `I`, then recurses to the next.
template<typename assign_to_t, typename convert_to_t> requires (wrapper_value_like<convert_to_t> && std::is_assignable_v<convert_to_t &, convert_to_t>)
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts into a wrapper that can be rebuilt wholesale.
template<typename assign_to_t, typename convert_to_t> requires (wrapper_value_like<convert_to_t> && !std::is_assignable_v<assign_to_t &, convert_to_t>)
auto	cli::detail::lexical_conversion (const std::vector< std::string > &strings, assign_to_t &output) -> bool
	Converts into the value held by a wrapper.

Variables
template<typename T>
constexpr int	cli::detail::type_count_base_v = type_count_base<T>::value
	Convenience accessor for type_count_base.
template<typename T>
constexpr int	cli::detail::type_count_v = type_count<T>::value
	Convenience accessor for type_count.
template<typename T>
constexpr int	cli::detail::type_count_min_v = type_count_min<T>::value
	Convenience accessor for type_count_min.
template<typename T>
constexpr int	cli::detail::expected_count_v = expected_count<T>::value
	Convenience accessor for expected_count.
template<typename T>
constexpr object_category_t	cli::detail::classify_object_v = classify_object<T>::value
	Convenience accessor for classify_object.

Detailed Description

Type classification and string conversion.

This is the engine that lets add_option accept an arbitrary variable and work out how to fill it from the command line. It answers three questions about a type:

What is it? cli::detail::object_category_t and cli::detail::classify_object sort every type into one of eighteen buckets: integral, container, tuple, wrapper, and so on.
How many values does it need? cli::detail::type_count and its relatives compute how many command-line tokens a type consumes.
How do I fill it? cli::detail::lexical_cast converts one token, cli::detail::lexical_conversion converts a whole list.

Dispatch is by concept. Each category has a matching concept, so an overload reads as template <char_value_like T> auto lexical_cast(...) rather than carrying its condition in a defaulted template parameter.

Enumeration Type Documentation

◆ object_category_t

enum class cli::detail::object_category_t : std::uint8_t

exportstrong

The classification buckets a type can fall into.

The numeric values are not arbitrary: several checks compare ranges, so the string-like categories sit contiguously between object_category_t::string_assignable and object_category_t::other.

Enumerator
char_value	A single character.
integral_value	A signed integer.
unsigned_integral	An unsigned integer.
enumeration	An enumeration.
boolean_value	A boolean.
floating_point	A floating-point number.
number_constructible	Constructible from either int or double.
double_constructible	Constructible from double only.
integer_constructible	Constructible from int only.
string_assignable	Assignable from std::string.
string_constructible	Constructible from std::string.
wstring_assignable	Assignable from std::wstring.
wstring_constructible	Constructible from std::wstring.
other	Anything else with a stream operator.
wrapper_value	Holds a nested value_type.
complex_number	A complex number.
tuple_value	A tuple or pair.
container_value	A sequence or associative container.

Function Documentation

◆ checked_to_string() [1/2]

template<typename lhs_t, typename rhs_t, typename T>
requires (!std::same_as<lhs_t, rhs_t>)

auto cli::detail::checked_to_string ( T && ) -> std::string

export

Renders nothing when the two types differ.

Returns: An empty string.

◆ checked_to_string() [2/2]

template<typename lhs_t, typename rhs_t, typename T>
requires std::same_as<lhs_t, rhs_t>

auto cli::detail::checked_to_string ( T && value ) -> decltype(to_string(std::forward< T >(value)))

export

Renders a value only when two types agree.

Used where a default is only meaningful if the assigned and converted types are the same.

Parameters

value The value to render.

Returns: The rendered value.

◆ from_stream() [1/2]

template<typename T>
requires (!istreamable<T>)

auto cli::detail::from_stream	(	const std::string &	,
		T &	) -> bool

export

Fallback for types with no stream extraction operator.

Returns: Always false.

◆ from_stream() [2/2]

template<istreamable T>

auto cli::detail::from_stream	(	const std::string &	istring,
		T &	obj ) -> bool

export

Reads a value from a string using its stream extraction operator.

Parameters

[in]	istring	The text to read.
[out]	obj	The value to fill.

Returns: true if the whole string was consumed without error.

◆ integral_conversion() [1/2]

template<typename T>
requires std::is_signed_v<T>

auto cli::detail::integral_conversion	(	const std::string &	input,
		T &	output ) -> bool

exportnoexcept

Parses a signed integer, accepting several notations.

Understands decimal, 0x hexadecimal, 0o octal, 0b binary, the word true, digit-group separators, and surrounding whitespace.

Parameters

[in]	input	The text to parse.
[out]	output	The value to fill.

Returns: true if the whole string parsed and the value fits in T.

◆ integral_conversion() [2/2]

template<typename T>
requires std::is_unsigned_v<T>

auto cli::detail::integral_conversion	(	const std::string &	input,
		T &	output ) -> bool

exportnoexcept

Parses an unsigned integer, accepting several notations.

Understands decimal, 0x hexadecimal, 0o octal, and 0b binary, plus digit-group separators and surrounding whitespace.

Parameters

[in]	input	The text to parse.
[out]	output	The value to fill.

Returns: true if the whole string parsed and the value fits in T.

◆ lexical_assign() [1/6]

template<typename assign_to_t, typename convert_to_t>
requires (!std::same_as<assign_to_t, convert_to_t> && !std::is_assignable_v<assign_to_t &, convert_to_t &> &&
std::is_move_assignable_v<assign_to_t>)

auto cli::detail::lexical_assign	(	const std::string &	input,
		assign_to_t &	output ) -> bool

export

Converts through an intermediate type, then constructs.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_assign() [2/6]

template<typename assign_to_t, typename convert_to_t>
requires (!std::same_as<assign_to_t, convert_to_t> && std::is_assignable_v<assign_to_t &, convert_to_t &>)

auto cli::detail::lexical_assign	(	const std::string &	input,
		assign_to_t &	output ) -> bool

export

Converts through an intermediate type, then assigns.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_assign() [3/6]

template<typename assign_to_t, typename convert_to_t>
requires (std::same_as<assign_to_t, convert_to_t> && !std::is_assignable_v<assign_to_t &, assign_to_t> && !wrapper_value_like
<assign_to_t> && std::is_assignable_v<assign_to_t &, int>)

auto cli::detail::lexical_assign	(	const std::string &	input,
		assign_to_t &	output ) -> bool

export

Assigns a token to a destination reachable only through int.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_assign() [4/6]

template<typename assign_to_t, typename convert_to_t>
requires (std::same_as<assign_to_t, convert_to_t> && !std::is_assignable_v<assign_to_t &, assign_to_t> && wrapper_value_like
<assign_to_t>)

auto cli::detail::lexical_assign	(	const std::string &	input,
		assign_to_t &	output ) -> bool

export

Assigns a token to a wrapper that is not self-assignable.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_assign() [5/6]

template<typename assign_to_t, typename convert_to_t>
requires (std::same_as<assign_to_t, convert_to_t> && std::is_assignable_v<assign_to_t &, assign_to_t> && !string_like_category
<assign_to_t>)

auto cli::detail::lexical_assign	(	const std::string &	input,
		assign_to_t &	output ) -> bool

export

Assigns a token to a self-assignable destination.

An empty token yields a value-initialised result rather than a parse failure.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_assign() [6/6]

template<typename assign_to_t, typename convert_to_t>
requires (std::same_as<assign_to_t, convert_to_t> && string_like_category<assign_to_t>)

auto cli::detail::lexical_assign	(	const std::string &	input,
		assign_to_t &	output ) -> bool

export

Assigns a token to a string-like destination.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [1/18]

template<typename T>
requires (other_like<T> && !std::is_assignable_v<T &, int> && !istreamable<T> && !adl_detail::lexical_castable<T>)

auto cli::detail::lexical_cast	(	const std::string &	,
		T &	) -> bool

export

Rejects types with no available conversion.

Instantiating this overload is always an error. It exists so that the failure is reported as one clear message rather than as an overload resolution failure.

Returns: Never returns; the assertion always fires.

◆ lexical_cast() [2/18]

template<typename T>
requires (other_like<T> && !std::is_assignable_v<T &, int> && istreamable<T>)

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to an unclassified type using its >> operator.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [3/18]

template<typename T>
requires (other_like<T> && std::is_assignable_v<T &, int>)

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to an unclassified type assignable from int.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [4/18]

template<double_constructible_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to a type constructible from double.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [5/18]

template<integer_constructible_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to a type constructible from int.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [6/18]

template<number_constructible_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to a type constructible from int or double.

The integer form is tried first, so an exact integer does not go through a floating-point round trip.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [7/18]

template<typename T>
requires (wrapper_value_like<T> && !std::is_assignable_v<T &, typename T::value_type> && std::is_assignable_v<T &, T>)

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token into a wrapper by rebuilding the wrapper.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [8/18]

template<typename T>
requires (wrapper_value_like<T> && std::is_assignable_v<T &, typename T::value_type>)

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token into a wrapper by assigning the inner value.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [9/18]

template<enumeration_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to an enumerator via its underlying type.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [10/18]

template<wstring_constructible_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Widens a token and constructs from it.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: Always true.

◆ lexical_cast() [11/18]

template<wstring_assignable_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Widens a token and assigns it.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: Always true.

◆ lexical_cast() [12/18]

template<string_constructible_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Constructs a string-constructible type from a token.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: Always true.

◆ lexical_cast() [13/18]

template<string_assignable_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Assigns a token directly to a string-assignable type.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: Always true.

◆ lexical_cast() [14/18]

template<complex_number_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token such as "3+4i" to a complex number.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [15/18]

template<floating_point_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to a floating-point value.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [16/18]

template<boolean_value_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to a boolean.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [17/18]

template<char_value_like T>

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to a character, accepting a numeric code point.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_cast() [18/18]

template<typename T>
requires (integral_value_like<T> || unsigned_integral_like<T>)

auto cli::detail::lexical_cast	(	const std::string &	input,
		T &	output ) -> bool

export

Converts a token to an integer.

Parameters

[in]	input	The token to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [1/11]

template<typename assign_to_t, typename convert_to_t>
requires (wrapper_value_like<convert_to_t> && !std::is_assignable_v<assign_to_t &, convert_to_t>)

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts into the value held by a wrapper.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [2/11]

template<typename assign_to_t, typename convert_to_t>
requires (wrapper_value_like<convert_to_t> && std::is_assignable_v<convert_to_t &, convert_to_t>)

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts into a wrapper that can be rebuilt wholesale.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [3/11]

template<typename assign_to_t, typename convert_to_t>
requires (mutable_container<assign_to_t> && mutable_container<convert_to_t> && type_count_base_v<convert_to_t> != 2 &&
((type_count_v<convert_to_t> > 2) || (type_count_v<convert_to_t> > type_count_base_v<convert_to_t>)))

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a container whose elements consume several tokens each.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The container to fill.

Returns: true on success.

◆ lexical_conversion() [4/11]

template<typename assign_to_t, typename convert_to_t>
requires (tuple_like<assign_to_t> && tuple_like<convert_to_t> && (type_count_base_v<convert_to_t> != type_count_v<convert_to_t> ||
type_count_v<convert_to_t> > 2))

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a tuple whose elements are themselves compound.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [5/11]

template<typename assign_to_t, typename convert_to_t>
requires (!tuple_like<assign_to_t> && !mutable_container<assign_to_t> && !wrapper_value_like<convert_to_t> && (mutable_container
<convert_to_t> || type_count_v<convert_to_t> > 2))

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a compound source into a scalar destination.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [6/11]

template<typename assign_to_t, typename convert_to_t>
requires (mutable_container<assign_to_t> && (expected_count_v<convert_to_t> == 1) && (type_count_v<convert_to_t> == 1))

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Fills a container, one element per token.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The container to fill.

Returns: true on success.

◆ lexical_conversion() [7/11]

template<typename assign_to_t, typename convert_to_t>
requires complex_like<convert_to_t>

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a complex number from one or two tokens.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [8/11]

template<typename assign_to_t, typename convert_to_t>
requires (mutable_container<assign_to_t> && mutable_container<convert_to_t> && type_count_v<convert_to_t> == 1)

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a container of single-value elements.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The container to fill.

Returns: true on success.

◆ lexical_conversion() [9/11]

template<typename assign_to_t, typename convert_to_t>
requires ((type_count_v<assign_to_t> <= 2) && expected_count_v<assign_to_t> == 1 && tuple_like<convert_to_t> && type_count_base_v
<convert_to_t> == 2)

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a two-element tuple from up to two tokens.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [10/11]

template<typename assign_to_t, typename convert_to_t>
requires (classify_object_v<convert_to_t> <= object_category_t::other && classify_object_v<assign_to_t>
<= object_category_t::wrapper_value)

auto cli::detail::lexical_conversion	(	const std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Converts a single-value type from the first token.

Parameters

[in]	strings	The tokens to convert.
[out]	output	The value to fill.

Returns: true on success.

◆ lexical_conversion() [11/11]

template<typename assign_to_t, typename convert_to_t>
requires (mutable_container<assign_to_t> && mutable_container<convert_to_t> && type_count_base_v<convert_to_t> == 2)

auto cli::detail::lexical_conversion	(	std::vector< std::string >	strings,
		assign_to_t &	output ) -> bool

export

Converts a container of pairs, consuming tokens two at a time.

Parameters

[in]	strings	The tokens to convert; consumed as it goes.
[out]	output	The container to fill.

Returns: true on success.

◆ sum_string_vector()

auto cli::detail::sum_string_vector ( const std::vector< std::string > & values ) -> std::string

export

Sums a list of values, falling back to concatenation.

Each entry is read as a number, or failing that as a flag value. If any entry is neither, the entries are concatenated instead. This backs the sum multi-option policy, which has to work for both numbers and text.

Parameters

values The values to sum.

Returns: The sum rendered to sixteen significant digits, or the concatenation of every input.

◆ to_flag_value()

auto cli::detail::to_flag_value ( std::string val ) -> std::int64_t

exportnoexcept

Interprets a string as a tri-state flag value.

Accepts true/false, on/off, yes/no, enable/disable, single characters such as t, y, +, f, n, -, single digits, and plain integers.

Parameters

val	The text to interpret.

Returns: A positive value for true, negative for false. On failure, sets errno to EINVAL; callers must clear errno before calling.

◆ to_string() [1/7]

template<typename T>
requires (plain_object<T> && !readable_container<std::remove_const_t<T>> && !tuple_like<T>)

auto cli::detail::to_string ( T && ) -> std::string

export

Renders anything with no usable representation as an empty string.

Returns: An empty string.

◆ to_string() [2/7]

template<string_convertible T>

auto cli::detail::to_string ( T && value ) -> decltype(std::forward< T >(value))

export

Renders a value already convertible to a string.

Parameters

value The value to render.

Returns: The value, forwarded unchanged.

◆ to_string() [3/7]

template<typename T>
requires (plain_object<T> && tuple_like<T> && type_count_base_v<T> >= 2)

auto cli::detail::to_string ( T && value ) -> std::string

export

Renders a multi-element tuple as a bracketed list.

Parameters

value The tuple to render.

Returns: The rendered tuple.

◆ to_string() [4/7]

template<typename T>
requires (plain_object<T> && tuple_like<T> && type_count_base_v<T> == 1)

auto cli::detail::to_string ( T && value ) -> std::string

export

Renders a single-element tuple as its one element.

Parameters

value The tuple to render.

Returns: The rendered element.

◆ to_string() [5/7]

template<typename T>
requires (!string_convertible<T> && !string_buildable<T> && ostreamable<T>)

auto cli::detail::to_string ( T && value ) -> std::string

export

Renders a value through its stream insertion operator.

Parameters

value The value to render.

Returns: The rendered value.

◆ to_string() [6/7]

template<typename T>
requires (string_buildable<T> && !string_convertible<T>)

auto cli::detail::to_string ( T && value ) -> std::string

export

Renders a value a string can be built from.

Parameters

value The value to render.

Returns: The rendered value.

◆ to_string() [7/7]

template<typename T>
requires (plain_object<T> && readable_container<T> && !tuple_like<T>)

auto cli::detail::to_string ( T && variable ) -> std::string

export

Renders a container as a bracketed, comma-separated list.

Parameters

variable The container to render.

Returns: The rendered container, or "{}" if it is empty.

◆ tuple_conversion() [1/2]

template<typename assign_to_t, typename convert_to_t, std::size_t I>
requires (I >= type_count_base_v<assign_to_t>)

auto cli::detail::tuple_conversion	(	const std::vector< std::string > &	,
		assign_to_t &	) -> bool

export

Terminates the tuple conversion recursion.

Returns: Always true.

◆ tuple_conversion() [2/2]

template<typename assign_to_t, typename convert_to_t, std::size_t I>
requires (I < type_count_base_v<assign_to_t>)

auto cli::detail::tuple_conversion	(	std::vector< std::string >	strings,
		assign_to_t &	output ) -> bool

export

Fills tuple element I, then recurses to the next.

Parameters

[in]	strings	The remaining tokens.
[out]	output	The tuple to fill.

Returns: true on success.

◆ tuple_name() [1/2]

template<typename T, std::size_t I>
requires (I < type_count_base_v<T>)

auto cli::detail::tuple_name ( ) -> std::string

export

Renders the names of tuple elements from index I onward.

Returns: The rendered names, comma-separated.

◆ tuple_name() [2/2]

template<typename T, std::size_t I>
requires (I == type_count_base_v<T>)

auto cli::detail::tuple_name ( ) -> std::string

export

Terminates the tuple name recursion.

Returns: An empty string.

◆ tuple_type_conversion() [1/3]

template<typename assign_to_t, typename convert_to_t>
requires (mutable_container<convert_to_t> || type_count_v<convert_to_t> != type_count_min_v<convert_to_t>)

auto cli::detail::tuple_type_conversion	(	std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Consumes a variable number of tokens, stopping at a separator.

Parameters

[in,out]	strings	The remaining tokens; the consumed ones are removed.
[out]	output	The element to fill.

Returns: true on success.

◆ tuple_type_conversion() [2/3]

template<typename assign_to_t, typename convert_to_t>
requires (!mutable_container<convert_to_t> && (type_count_v<convert_to_t> > 1) && type_count_v<convert_to_t> == type_count_min_v
<convert_to_t>)

auto cli::detail::tuple_type_conversion	(	std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Consumes a fixed number of tokens for a compound tuple element.

Parameters

[in,out]	strings	The remaining tokens; the consumed ones are removed.
[out]	output	The element to fill.

Returns: true on success.

◆ tuple_type_conversion() [3/3]

template<typename assign_to_t, typename convert_to_t>
requires (!mutable_container<convert_to_t> && type_count_v<convert_to_t> == 1)

auto cli::detail::tuple_type_conversion	(	std::vector< std::string > &	strings,
		assign_to_t &	output ) -> bool

export

Consumes one token for a single-value tuple element.

Parameters

[in,out]	strings	The remaining tokens; the consumed one is removed.
[out]	output	The element to fill.

Returns: true on success.

◆ tuple_type_size() [1/2]

template<typename T, std::size_t I>
requires (I < type_count_base_v<T>)

auto cli::detail::tuple_type_size ( ) -> int

constexprexport

Sums the value counts of tuple elements from index I onward.

Returns: The summed count.

◆ tuple_type_size() [2/2]

template<typename T, std::size_t I>
requires (I == type_count_base_v<T>)

auto cli::detail::tuple_type_size ( ) -> int

constexprexport

Terminates the tuple size recursion.

Returns: Zero.

◆ tuple_type_size_min() [1/2]

template<typename T, std::size_t I>
requires (I < type_count_base_v<T>)

auto cli::detail::tuple_type_size_min ( ) -> int

constexprexport

Sums the minimum counts of tuple elements from index I onward.

Returns: The summed minimum count.

◆ tuple_type_size_min() [2/2]

template<typename T, std::size_t I>
requires (I == type_count_base_v<T>)

auto cli::detail::tuple_type_size_min ( ) -> int

constexprexport

Terminates the minimum tuple size recursion.

Returns: Zero.

◆ tuple_value_string() [1/2]

template<typename T, std::size_t I>
requires (I == type_count_base_v<T>)

auto cli::detail::tuple_value_string ( T && ) -> std::string

export

Terminates the tuple rendering recursion.

Returns: An empty string.

◆ tuple_value_string() [2/2]

template<typename T, std::size_t I>
requires (I < type_count_base_v<T>)

auto cli::detail::tuple_value_string ( T && value ) -> std::string

export

Renders tuple elements from index I onward.

Parameters

value The tuple to render.

Returns: The rendered elements, comma-separated.