The Lector library's namespace. More...

Classes
struct	AreUnique
	Data structure that validates at compilation time that a specified variadic list of types are unique. Base data structure that contains an empty list of types and returns true.

struct	AreUnique< FirstType, RemainingTypes... >
	Data structure that validates at compilation time that a specified variadic list of types are unique. Recursively compares a first type against the remaining variadic list of types.

class	Arguments
	A collection of command line arguments that can be parsed from argc and argv. More...

struct	Configuration
	Configuration of the help information of a collection of command line arguments. More...

struct	FindArgumentByLabel
	Type trait used to extract a command line argument from a collection of command line arguments, using only its Label.

struct	FindArgumentByLabel< Label, FirstArgument, RemainingArgumentTypes... >
	Type trait specialization used to extract a command line argument from a collection of command line arguments, using its Label and the types of the remaining command line arguments in the collection.

struct	FindArgumentHelper
	Helper to provide short-circuit evaluation for lector::FindArgumentByLabel.

struct	FindArgumentHelper< Label, false, FirstArgument, RemainingArgumentTypes... >
	False branch of the short-circuit evaluation helper. The command line argument has not yet been found and the remaining command line arguments should be searched.

struct	FindArgumentHelper< Label, true, FirstArgument, RemainingArgumentTypes... >
	True branch of the short-circuit evaluation helper. The command line argument has been found and will now be returned; the remaining command line arguments do not need to be searched.

class	RepeatableArgument
	A repeatable command line argument. More...

class	SingularArgument
	A singular command line argument. More...

Typedefs
template<typename Type >
using	Name = std::pair< Type, std::string_view >
	The canonical printed name for a value of a specified type.

template<typename Type >
using	Spelling = std::pair< std::string_view, Type >
	A possible spelling for a value of a specified type.

Enumerations
enum class	Arity : std::int8_t { Unknown = 0 , Singular = 1 , Repeatable = 2 }
	Arity of a command line argument. More...

enum class	Form : std::int8_t { Unknown = 0 , Positional = 1 , Named = 2 }
	Form of a command line argument. More...

enum class	Importance : std::int8_t { Unknown = 0 , Optional = 1 , Required = 2 }
	Importance of a command line argument. More...

Functions
std::pair< std::size_t, std::size_t >	byte_interval (const std::string_view text, const std::size_t code_point_index)
	Finds the exact byte [begin, end) index interval in a string of text where a specified code point resides.

std::size_t	code_points (const std::string_view text)
	Counts and returns the number of UTF-8 code points in a string of text. The number of UTF-8 code points is a useful approximation of the number of graphemes in the string, where ASCII characters and multi-byte UTF-8 characters are each counted as one unit of length.

std::string	collate_and_centre_align_with_left_bias (const std::string_view first_column_text, const std::size_t first_column_width, const std::string_view second_column_text, const std::size_t second_column_width)
	Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are centre-aligned and spaced a short distance apart. If the total required centre-aligning padding is odd, the text is biased by one space towards the left.

std::string	collate_and_centre_align_with_right_bias (const std::string_view first_column_text, const std::size_t first_column_width, const std::string_view second_column_text, const std::size_t second_column_width)
	Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are centre-aligned and spaced a short distance apart. If the total required centre-aligning padding is odd, the text is biased by one space towards the right.

std::string	collate_and_left_align (const std::string_view first_column_text, const std::size_t first_column_width, const std::string_view second_column_text, const std::size_t second_column_width)
	Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are left-aligned and spaced a short distance apart.

std::string	collate_and_right_align (const std::string_view first_column_text, const std::size_t first_column_width, const std::string_view second_column_text, const std::size_t second_column_width)
	Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are right-aligned and spaced a short distance apart.

bool	contains_whitespace (const std::string_view text)
	Checks whether a string of text contains any whitespace characters.

bool	is_leading_byte (const char character)
	Returns whether a given character is the leading byte of a UTF-8 character. All UTF-8 characters measure either one, two, three, or four bytes. UTF-8 characters that measure only one byte are the ASCII characters. UTF-8 character that measure two, three, or four bytes are multi-byte characters and consist of a leading byte with a specific binary pattern and one or more continuation bytes of the binary pattern 10xxxxxx.

std::string	join_and_centre_align_with_left_bias (const std::vector< std::string > &lines)
	Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines centre-aligned. If the total required centre-aligning padding is odd, the text is biased by one space towards the left.

std::string	join_and_centre_align_with_right_bias (const std::vector< std::string > &lines)
	Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines centre-aligned. If the total required centre-aligning padding is odd, the text is biased by one space towards the right.

std::string	join_and_left_align (const std::vector< std::string > &lines)
	Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines left-aligned.

std::string	join_and_right_align (const std::vector< std::string > &lines)
	Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines right-aligned.

std::size_t	longest_word_length (const std::string_view text)
	Computes and returns the length of the longest word in a string of text. The length of a word is measured by its number of UTF-8 code points.

std::string	pad_left (const std::string_view text, const std::size_t length)
	Pads a string of text from the left with spaces to reach a specified length. If the string of text is longer than the specified length, it is unchanged.

std::string	pad_right (const std::string_view text, const std::size_t length)
	Pads a string of text from the right with spaces to reach a specified length. If the string of text is longer than the specified length, it is unchanged.

template<>
std::optional< bool >	parse (const std::string_view text)
	Parses a string of text into a boolean value. For example, the string of text "true" returns the boolean value true.

template<>
std::optional< std::uint8_t >	parse (const std::string_view text)
	Parses a string of text into an 8-bit natural number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::uint16_t >	parse (const std::string_view text)
	Parses a string of text into a 16-bit natural number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::uint32_t >	parse (const std::string_view text)
	Parses a string of text into a 32-bit natural number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::uint64_t >	parse (const std::string_view text)
	Parses a string of text into a 64-bit natural number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::int8_t >	parse (const std::string_view text)
	Parses a string of text into an 8-bit integer number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::int16_t >	parse (const std::string_view text)
	Parses a string of text into a 16-bit integer number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::int32_t >	parse (const std::string_view text)
	Parses a string of text into a 32-bit integer number. For example, the string of text "42" returns the number 42.

template<>
std::optional< std::int64_t >	parse (const std::string_view text)
	Parses a string of text into a 64-bit integer number. For example, the string of text "42" returns the number 42.

template<>
std::optional< float >	parse (const std::string_view text)
	Parses a string of text into a single-precision floating-point number. For example, the string of text "3.14" returns the number 3.14.

template<>
std::optional< double >	parse (const std::string_view text)
	Parses a string of text into a double-precision floating-point number. For example, the string of text "3.14" returns the number 3.14.

template<>
std::optional< long double >	parse (const std::string_view text)
	Parses a string of text into an extended-precision floating-point number. For example, the string of text "3.14" returns the number 3.14.

template<>
std::optional< std::string >	parse (const std::string_view text)
	Parses a string view into a string of text.

template<>
std::optional< std::string_view >	parse (const std::string_view text)
	Returns a string of text as-is.

template<>
std::optional< std::filesystem::path >	parse (const std::string_view text)
	Parses a string of text into a filesystem path.

template<typename Type >
std::optional< Type >	parse (std::string_view text)
	Parses a string of text into a value of a specific type. If the type is an enumeration type, it must define a specialization of the lector::Spellings constant for its type.

template<typename EnumerationType >
constexpr std::optional< EnumerationType >	parse_enumeration (const std::string_view text)
	Parses a string of text into an enumeration value. The enumeration type must define a specialization of the lector::Spellings constant for its type.

template<>
std::string	print (const bool &value)
	Prints a boolean value as a string of text.

template<>
std::string	print (const double &value)
	Prints a double-precision floating-point number as a string of text.

template<>
std::string	print (const float &value)
	Prints a single-precision floating-point number as a string of text.

template<>
std::string	print (const long double &value)
	Prints an extended-precision floating-point number as a string of text.

template<>
std::string	print (const std::filesystem::path &value)
	Prints a filesystem path as a string of text.

template<>
std::string	print (const std::int16_t &value)
	Prints a 16-bit integer number as a string of text.

template<>
std::string	print (const std::int32_t &value)
	Prints a 32-bit integer number as a string of text.

template<>
std::string	print (const std::int64_t &value)
	Prints a 64-bit integer number as a string of text.

template<>
std::string	print (const std::int8_t &value)
	Prints an 8-bit integer number as a string of text.

template<>
std::string	print (const std::string &value)
	Returns a string of text as-is.

template<>
std::string	print (const std::string_view &value)
	Prints a string view as a string of text.

template<>
std::string	print (const std::uint16_t &value)
	Prints a 16-bit natural number as a string of text.

template<>
std::string	print (const std::uint32_t &value)
	Prints a 32-bit natural number as a string of text.

template<>
std::string	print (const std::uint64_t &value)
	Prints a 64-bit natural number as a string of text.

template<>
std::string	print (const std::uint8_t &value)
	Prints an 8-bit natural number as a string of text.

template<typename Type >
std::string	print (const Type &value)
	Prints a value of a specific type as a string of text.

template<typename EnumerationType >
constexpr std::string_view	print_enumeration (const EnumerationType value)
	Prints a value of a specified enumeration type as a string of text. The enumeration type must define a specialization of the lector::Names constant for its type.

std::string	quote (const std::string_view text)
	Encloses a string of text in quotes. Either single or double quotes are used depending on which type of quote is not present in the string of text, with double quotes preferred if neither type of quote is present. If the string of text already begins and ends with either single or double quotes, no additional quotes are added. If the string of text is empty, an empty string is returned.

std::string	quote_if_contains_whitespace (const std::string_view text)
	Encloses a string of text in quotes if it contains any whitespace. Either single or double quotes are used depending on which type of quote is not present in the string of text, with double quotes preferred if neither type of quote is present. If the string of text already begins and ends with either single or double quotes, no additional quotes are added. If the string of text is empty, an empty string is returned.

std::vector< std::string_view >	tokenize (const std::string_view text)
	Tokenizes a string of text into a vector of strings of text, where each string in the vector corresponds to a word in the original string. Words are defined as sequences of non-whitespace characters, and whitespace characters are used as delimiters. The function does not modify the original string and returns views into it, so the original string must remain valid for the lifetime of the returned vector.

std::vector< std::string >	wrap (const std::string_view text, const std::size_t line_length)
	Wraps a string of text to a line length and returns the result as a sequence of strings of text where each string in the sequence represents one line of text.

std::string	wrap_and_centre_align_with_left_bias (const std::string_view text, const std::size_t line_length)
	Centre-aligns and wraps a string of text to a line length. If the total required centre-aligning padding is odd, the text is biased by one space towards the left.

std::string	wrap_and_centre_align_with_right_bias (const std::string_view text, const std::size_t line_length)
	Centre-aligns and wraps a string of text to a line length. If the total required centre-aligning padding is odd, the text is biased by one space towards the right.

std::string	wrap_and_left_align (const std::string_view text, const std::size_t line_length)
	Left-aligns and wraps a string of text to a line length.

std::string	wrap_and_right_align (const std::string_view text, const std::size_t line_length)
	Right-aligns and wraps a string of text to a line length.

Variables
template<typename Type >
constexpr std::array< lector::Name< Type >, 0UL >	Names {}
	Map of canonical printed names to their corresponding values of a specified type.

template<typename Type >
constexpr std::array< lector::Spelling< Type >, 0UL >	Spellings {}
	Map of spellings to their corresponding values of a specified type.

Detailed Description

The Lector library's namespace.

Typedef Documentation

◆ Name

template<typename Type >

using lector::Name = typedef std::pair<Type, std::string_view>

The canonical printed name for a value of a specified type.

Template Parameters

Type	The type of the value.

◆ Spelling

template<typename Type >

using lector::Spelling = typedef std::pair<std::string_view, Type>

A possible spelling for a value of a specified type.

Template Parameters

Type	The type of the value.

Enumeration Type Documentation

◆ Arity

enum class lector::Arity : std::int8_t

strong

Arity of a command line argument.

Enumerator
Unknown	Unknown, unspecified, or invalid command line argument arity.
Singular	The command line argument has singular arity; it can only appear once on the command line.
Repeatable	The command line argument has repeatable arity; it can appear multiple times on the command line. If the argument is a named repeatable argument, each appearance must include both its key and its value. If the argument is a positional repeatable argument, its multiple values must appear in an uninterrupted sequence.

◆ Form

enum class lector::Form : std::int8_t

strong

Form of a command line argument.

Enumerator
Unknown	Unknown, unspecified, or invalid command line argument form.
Positional	The command line argument is a positional argument; it does not define any keys and must be specified in a specific order on the command line.
Named	The command line argument is a named argument; it defines one or more keys and is specified on the command line by one of its keys. Named arguments can be specified in any order on the command line.

◆ Importance

enum class lector::Importance : std::int8_t

strong

Importance of a command line argument.

Enumerator
Unknown	Unknown, unspecified, or invalid command line argument importance.
Optional	The command line argument is optional; it may or may not be provided by the user.
Required	The command line argument is required; it must be provided by the user.

Function Documentation

◆ byte_interval()

std::pair< std::size_t, std::size_t > lector::byte_interval	(	const std::string_view	text,
		const std::size_t	code_point_index
	)

Finds the exact byte [begin, end) index interval in a string of text where a specified code point resides.

Parameters

[in]	text	The string of text to parse.
[in]	code_point_index	The index of the code point in the string of text.

Returns: A pair that contains the begin and end byte indices of the specified code point. The end index is the classical C++ "one past the end" index. If the specified code point index is out of bounds, both returned indices are set to one past the end index of the string, which is the size of the string.

◆ code_points()

std::size_t lector::code_points ( const std::string_view text )

Counts and returns the number of UTF-8 code points in a string of text. The number of UTF-8 code points is a useful approximation of the number of graphemes in the string, where ASCII characters and multi-byte UTF-8 characters are each counted as one unit of length.

Parameters

[in] text The string of text whose UTF-8 code points are to be counted.

Returns: The number of UTF-8 code points in the string of text.

◆ collate_and_centre_align_with_left_bias()

std::string lector::collate_and_centre_align_with_left_bias	(	const std::string_view	first_column_text,
		const std::size_t	first_column_width,
		const std::string_view	second_column_text,
		const std::size_t	second_column_width
	)

Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are centre-aligned and spaced a short distance apart. If the total required centre-aligning padding is odd, the text is biased by one space towards the left.

Parameters

[in]	first_column_text	The string of text for the first column.
[in]	first_column_width	The desired width of the first column. Very long words whose length exceeds this width are hyphenated.
[in]	second_column_text	The string of text for the second column.
[in]	second_column_width	The desired width of the second column. Very long words whose length exceeds this width are hyphenated.

Returns: The string that contains the collated text.

Exceptions

std::invalid_argument if either desired column width is zero.

◆ collate_and_centre_align_with_right_bias()

std::string lector::collate_and_centre_align_with_right_bias	(	const std::string_view	first_column_text,
		const std::size_t	first_column_width,
		const std::string_view	second_column_text,
		const std::size_t	second_column_width
	)

Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are centre-aligned and spaced a short distance apart. If the total required centre-aligning padding is odd, the text is biased by one space towards the right.

Parameters

[in]	first_column_text	The string of text for the first column.
[in]	first_column_width	The desired width of the first column. Very long words whose length exceeds this width are hyphenated.
[in]	second_column_text	The string of text for the second column.
[in]	second_column_width	The desired width of the second column. Very long words whose length exceeds this width are hyphenated.

Returns: The string that contains the collated text.

Exceptions

std::invalid_argument if either desired column width is zero.

◆ collate_and_left_align()

std::string lector::collate_and_left_align	(	const std::string_view	first_column_text,
		const std::size_t	first_column_width,
		const std::string_view	second_column_text,
		const std::size_t	second_column_width
	)

Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are left-aligned and spaced a short distance apart.

Parameters

[in]	first_column_text	The string of text for the first column.
[in]	first_column_width	The desired width of the first column. Very long words whose length exceeds this width are hyphenated.
[in]	second_column_text	The string of text for the second column.
[in]	second_column_width	The desired width of the second column. Very long words whose length exceeds this width are hyphenated.

Returns: The string that contains the collated text.

Exceptions

std::invalid_argument if either desired column width is zero.

◆ collate_and_right_align()

std::string lector::collate_and_right_align	(	const std::string_view	first_column_text,
		const std::size_t	first_column_width,
		const std::string_view	second_column_text,
		const std::size_t	second_column_width
	)

Collates two strings of text, each representing a column, into a single string that contains newline-separated lines of text, with the lines formatted such that the two columns are right-aligned and spaced a short distance apart.

Parameters

[in]	first_column_text	The string of text for the first column.
[in]	first_column_width	The desired width of the first column. Very long words whose length exceeds this width are hyphenated.
[in]	second_column_text	The string of text for the second column.
[in]	second_column_width	The desired width of the second column. Very long words whose length exceeds this width are hyphenated.

Returns: The string that contains the collated text.

Exceptions

std::invalid_argument if either desired column width is zero.

◆ contains_whitespace()

bool lector::contains_whitespace ( const std::string_view text )

Checks whether a string of text contains any whitespace characters.

Parameters

[in] text The string of text to examine.

Returns: true if the string of text contains any whitespace, or false otherwise.

◆ is_leading_byte()

bool lector::is_leading_byte ( const char character )

Returns whether a given character is the leading byte of a UTF-8 character. All UTF-8 characters measure either one, two, three, or four bytes. UTF-8 characters that measure only one byte are the ASCII characters. UTF-8 character that measure two, three, or four bytes are multi-byte characters and consist of a leading byte with a specific binary pattern and one or more continuation bytes of the binary pattern 10xxxxxx.

One-byte UTF-8 characters are the ASCII characters. Their first bit is 0 and their binary pattern is therefore 0xxxxxxx.
Two-byte UTF-8 characters have a leading byte with the binary pattern 110xxxxx and one continuation byte with the binary pattern 10xxxxxx. Together, the two bytes therefore have the binary pattern 110xxxxx 10xxxxxx.
Three-byte UTF-8 characters have a leading byte with the binary pattern 1110xxxx and two continuation bytes with the binary pattern 10xxxxxx. Together, the three bytes therefore have the binary pattern 1110xxxx 10xxxxxx 10xxxxxx.
Four-byte UTF-8 characters have a leading byte with the binary pattern 11110xxx and three continuation bytes with the binary pattern 10xxxxxx. Together, the four bytes therefore have the binary pattern 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx.
Parameters

[in] character The character to check.

Returns
True if the character is a leading byte; false if the character is a continuation byte.

◆ join_and_centre_align_with_left_bias()

std::string lector::join_and_centre_align_with_left_bias ( const std::vector< std::string > & lines )

Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines centre-aligned. If the total required centre-aligning padding is odd, the text is biased by one space towards the left.

Parameters

[in] lines Vector of strings to be joined and centre-aligned.

Returns: The joined and centre-aligned string of text.

◆ join_and_centre_align_with_right_bias()

std::string lector::join_and_centre_align_with_right_bias ( const std::vector< std::string > & lines )

Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines centre-aligned. If the total required centre-aligning padding is odd, the text is biased by one space towards the right.

Parameters

[in] lines Vector of strings to be joined and centre-aligned.

Returns: The joined and centre-aligned string of text.

◆ join_and_left_align()

std::string lector::join_and_left_align ( const std::vector< std::string > & lines )

Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines left-aligned.

Parameters

[in] lines Vector of strings to be joined and left-aligned.

Returns: The joined and left-aligned string of text.

◆ join_and_right_align()

std::string lector::join_and_right_align ( const std::vector< std::string > & lines )

Joins a vector of strings where each string corresponds to a line of text into a single string of text, with newline characters inserted between the lines, and the lines right-aligned.

Parameters

[in] lines Vector of strings to be joined and right-aligned.

Returns: The joined and right-aligned string of text.

◆ longest_word_length()

std::size_t lector::longest_word_length ( const std::string_view text )

Computes and returns the length of the longest word in a string of text. The length of a word is measured by its number of UTF-8 code points.

Parameters

[in] text The string of text whose longest word length is to be computed.

Returns: The length of the longest word in the string of text.

◆ pad_left()

std::string lector::pad_left	(	const std::string_view	text,
		const std::size_t	length
	)

Pads a string of text from the left with spaces to reach a specified length. If the string of text is longer than the specified length, it is unchanged.

Parameters

[in]	text	The string of text to pad from the left.
[in]	length	The desired length of the padded string.

Returns: The padded string of text.

◆ pad_right()

std::string lector::pad_right	(	const std::string_view	text,
		const std::size_t	length
	)

Pads a string of text from the right with spaces to reach a specified length. If the string of text is longer than the specified length, it is unchanged.

Parameters

[in]	text	The string of text to pad from the right.
[in]	length	The desired length of the padded string.

Returns: The padded string of text.

◆ parse() [1/16]

template<>

std::optional< bool > lector::parse ( const std::string_view text )

Parses a string of text into a boolean value. For example, the string of text "true" returns the boolean value true.

Parameters

[in] text The string of text to parse.

Returns: The parsed boolean value, or std::nullopt if the string of text could not be parsed into a valid boolean value.

◆ parse() [2/16]

template<>

std::optional< std::uint8_t > lector::parse ( const std::string_view text )

Parses a string of text into an 8-bit natural number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 8-bit natural number, or std::nullopt if the string of text could not be parsed into a valid 8-bit natural number.

◆ parse() [3/16]

template<>

std::optional< std::uint16_t > lector::parse ( const std::string_view text )

Parses a string of text into a 16-bit natural number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 16-bit natural number, or std::nullopt if the string of text could not be parsed into a valid 16-bit natural number.

◆ parse() [4/16]

template<>

std::optional< std::uint32_t > lector::parse ( const std::string_view text )

Parses a string of text into a 32-bit natural number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 32-bit natural number, or std::nullopt if the string of text could not be parsed into a valid 32-bit natural number.

◆ parse() [5/16]

template<>

std::optional< std::uint64_t > lector::parse ( const std::string_view text )

Parses a string of text into a 64-bit natural number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 64-bit natural number, or std::nullopt if the string of text could not be parsed into a valid 64-bit natural number.

◆ parse() [6/16]

template<>

std::optional< std::int8_t > lector::parse ( const std::string_view text )

Parses a string of text into an 8-bit integer number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 8-bit integer number, or std::nullopt if the string of text could not be parsed into a valid 8-bit integer number.

◆ parse() [7/16]

template<>

std::optional< std::int16_t > lector::parse ( const std::string_view text )

Parses a string of text into a 16-bit integer number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 16-bit integer number, or std::nullopt if the string of text could not be parsed into a valid 16-bit integer number.

◆ parse() [8/16]

template<>

std::optional< std::int32_t > lector::parse ( const std::string_view text )

Parses a string of text into a 32-bit integer number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 32-bit integer number, or std::nullopt if the string of text could not be parsed into a valid 32-bit integer number.

◆ parse() [9/16]

template<>

std::optional< std::int64_t > lector::parse ( const std::string_view text )

Parses a string of text into a 64-bit integer number. For example, the string of text "42" returns the number 42.

Parameters

[in] text The string of text to parse.

Returns: The parsed 64-bit integer number, or std::nullopt if the string of text could not be parsed into a valid 64-bit integer number.

◆ parse() [10/16]

template<>

std::optional< float > lector::parse ( const std::string_view text )

Parses a string of text into a single-precision floating-point number. For example, the string of text "3.14" returns the number 3.14.

Parameters

[in] text The string of text to parse.

Returns: The parsed single-precision floating-point number, or std::nullopt if the string of text could not be parsed into a valid single-precision floating-point number.

◆ parse() [11/16]

template<>

std::optional< double > lector::parse ( const std::string_view text )

Parses a string of text into a double-precision floating-point number. For example, the string of text "3.14" returns the number 3.14.

Parameters

[in] text The string of text to parse.

Returns: The parsed double-precision floating-point number, or std::nullopt if the string of text could not be parsed into a valid double-precision floating-point number.

◆ parse() [12/16]

template<>

std::optional< long double > lector::parse ( const std::string_view text )

Parses a string of text into an extended-precision floating-point number. For example, the string of text "3.14" returns the number 3.14.

Parameters

[in] text The string of text to parse.

Returns: The parsed extended-precision floating-point number, or std::nullopt if the string of text could not be parsed into a valid extended-precision floating-point number.

◆ parse() [13/16]

template<>

std::optional< std::string > lector::parse ( const std::string_view text )

Parses a string view into a string of text.

Parameters

[in] text The string view to parse.

Returns: The parsed string.

◆ parse() [14/16]

template<>

std::optional< std::string_view > lector::parse ( const std::string_view text )

Returns a string of text as-is.

Parameters

[in] text The string of text.

Returns: The string of text.

◆ parse() [15/16]

template<>

std::optional< std::filesystem::path > lector::parse ( const std::string_view text )

Parses a string of text into a filesystem path.

Parameters

[in] text The string of text to parse.

Returns: The parsed filesystem path, or std::nullopt if the string of text could not be parsed into a valid filesystem path.

◆ parse() [16/16]

template<typename Type >

std::optional< Type > lector::parse ( std::string_view text )

Parses a string of text into a value of a specific type. If the type is an enumeration type, it must define a specialization of the lector::Spellings constant for its type.

Parses a string of text into a value of a specific type. If the type is an enumeration type, it must define a specialization of the lector::Spellings constant for its type; otherwise, the type must be streamable with the >> input stream operator.

Template Parameters

Type	The type of the value in which to parse the string of text.

Parameters

[in] text The string of text to parse.

Returns: The parsed value, or std::nullopt if the string of text could not be parsed into a valid value.

◆ parse_enumeration()

template<typename EnumerationType >

constexpr std::optional< EnumerationType > lector::parse_enumeration ( const std::string_view text )

constexpr

Parses a string of text into an enumeration value. The enumeration type must define a specialization of the lector::Spellings constant for its type.

Template Parameters

EnumerationType The enumeration type.

Parameters

[in] text The string of text to parse.

Returns: The parsed enumeration value, or std::nullopt if the string of text could not be parsed into a valid enumeration value.

◆ print() [1/16]

template<>

std::string lector::print ( const bool & value )

Prints a boolean value as a string of text.

Parameters

[in] value The boolean value to print.

Returns: The boolean value as a printed string of text.

◆ print() [2/16]

template<>

std::string lector::print ( const double & value )

Prints a double-precision floating-point number as a string of text.

Parameters

[in] value The double-precision floating-point number to print.

Returns: The double-precision floating-point number as a printed string of text.

◆ print() [3/16]

template<>

std::string lector::print ( const float & value )

Prints a single-precision floating-point number as a string of text.

Parameters

[in] value The single-precision floating-point number to print.

Returns: The single-precision floating-point number as a printed string of text.

◆ print() [4/16]

template<>

std::string lector::print ( const long double & value )

Prints an extended-precision floating-point number as a string of text.

Parameters

[in] value The extended-precision floating-point number to print.

Returns: The extended-precision floating-point number as a printed string of text.

◆ print() [5/16]

template<>

std::string lector::print ( const std::filesystem::path & value )

Prints a filesystem path as a string of text.

Parameters

[in] value The filesystem path to print.

Returns: The filesystem path as a printed string of text.

◆ print() [6/16]

template<>

std::string lector::print ( const std::int16_t & value )

Prints a 16-bit integer number as a string of text.

Parameters

[in] value The 16-bit integer number to print.

Returns: The 16-bit integer number as a printed string of text.

◆ print() [7/16]

template<>

std::string lector::print ( const std::int32_t & value )

Prints a 32-bit integer number as a string of text.

Parameters

[in] value The 32-bit integer number to print.

Returns: The 32-bit integer number as a printed string of text.

◆ print() [8/16]

template<>

std::string lector::print ( const std::int64_t & value )

Prints a 64-bit integer number as a string of text.

Parameters

[in] value The 64-bit integer number to print.

Returns: The 64-bit integer number as a printed string of text.

◆ print() [9/16]

template<>

std::string lector::print ( const std::int8_t & value )

Prints an 8-bit integer number as a string of text.

Parameters

[in] value The 8-bit integer number to print.

Returns: The 8-bit integer number as a printed string of text.

◆ print() [10/16]

template<>

std::string lector::print ( const std::string & value )

Returns a string of text as-is.

Parameters

[in] value The string of text.

Returns: The string of text.

◆ print() [11/16]

template<>

std::string lector::print ( const std::string_view & value )

Prints a string view as a string of text.

Parameters

[in] value The string view to print.

Returns: The string view as a printed string of text.

◆ print() [12/16]

template<>

std::string lector::print ( const std::uint16_t & value )

Prints a 16-bit natural number as a string of text.

Parameters

[in] value The 16-bit natural number to print.

Returns: The 16-bit natural number as a printed string of text.

◆ print() [13/16]

template<>

std::string lector::print ( const std::uint32_t & value )

Prints a 32-bit natural number as a string of text.

Parameters

[in] value The 32-bit natural number to print.

Returns: The 32-bit natural number as a printed string of text.

◆ print() [14/16]

template<>

std::string lector::print ( const std::uint64_t & value )

Prints a 64-bit natural number as a string of text.

Parameters

[in] value The 64-bit natural number to print.

Returns: The 64-bit natural number as a printed string of text.

◆ print() [15/16]

template<>

std::string lector::print ( const std::uint8_t & value )

Prints an 8-bit natural number as a string of text.

Parameters

[in] value The 8-bit natural number to print.

Returns: The 8-bit natural number as a printed string of text.

◆ print() [16/16]

template<typename Type >

std::string lector::print ( const Type & value )

Prints a value of a specific type as a string of text.

Prints a value of a specific type as a string of text. If the type is an enumeration type, it must define a specialization of the lector::Names constant for its type; otherwise, the type must be streamable with the << output stream operator.

Template Parameters

Type	The type of the value to print.

Parameters

[in] value The value to print.

Returns: The value as a printed string of text.

◆ print_enumeration()

template<typename EnumerationType >

constexpr std::string_view lector::print_enumeration ( const EnumerationType value )

constexpr

Prints a value of a specified enumeration type as a string of text. The enumeration type must define a specialization of the lector::Names constant for its type.

Template Parameters

EnumerationType The enumeration type.

Parameters

[in] value The enumeration value to print.

Returns: The value as a printed string of text.

◆ quote()

std::string lector::quote ( const std::string_view text )

Encloses a string of text in quotes. Either single or double quotes are used depending on which type of quote is not present in the string of text, with double quotes preferred if neither type of quote is present. If the string of text already begins and ends with either single or double quotes, no additional quotes are added. If the string of text is empty, an empty string is returned.

Parameters

[in] text The string of text to enclose in quotes.

Returns: The string of text enclosed in quotes.

Exceptions

std::invalid_argument if the string of text contains both single and double quotes.

◆ quote_if_contains_whitespace()

std::string lector::quote_if_contains_whitespace ( const std::string_view text )

Encloses a string of text in quotes if it contains any whitespace. Either single or double quotes are used depending on which type of quote is not present in the string of text, with double quotes preferred if neither type of quote is present. If the string of text already begins and ends with either single or double quotes, no additional quotes are added. If the string of text is empty, an empty string is returned.

Parameters

[in] text The string of text to possibly enclose in quotes.

Returns: The string of text possibly enclosed in quotes.

Exceptions

std::invalid_argument if the string of text contains both single and double quotes.

◆ tokenize()

std::vector< std::string_view > lector::tokenize ( const std::string_view text )

Tokenizes a string of text into a vector of strings of text, where each string in the vector corresponds to a word in the original string. Words are defined as sequences of non-whitespace characters, and whitespace characters are used as delimiters. The function does not modify the original string and returns views into it, so the original string must remain valid for the lifetime of the returned vector.

Parameters

[in] text The string of text to be tokenized.

Returns: A vector of strings of text, each corresponding to a word in the original string.

◆ wrap()

std::vector< std::string > lector::wrap	(	const std::string_view	text,
		const std::size_t	line_length
	)

Wraps a string of text to a line length and returns the result as a sequence of strings of text where each string in the sequence represents one line of text.

Parameters

[in]	text	The string of text to wrap.
[in]	line_length	The desired line length to use when wrapping. Must be strictly greater than zero. Very long words whose lengths exceed this line length are hyphenated.

Returns: The sequence of strings of text that contains one string per line.

Exceptions

std::invalid_argument if the desired line length is zero.

◆ wrap_and_centre_align_with_left_bias()

std::string lector::wrap_and_centre_align_with_left_bias	(	const std::string_view	text,
		const std::size_t	line_length
	)

Centre-aligns and wraps a string of text to a line length. If the total required centre-aligning padding is odd, the text is biased by one space towards the left.

Parameters

[in]	text	The string of text to wrap and centre-align.
[in]	line_length	The desired line length to use when wrapping. Must be strictly greater than zero. Very long words whose lengths exceed this line length are hyphenated.

Returns: The wrapped and centre-aligned string of text.

Exceptions

std::invalid_argument if the desired line length is zero.

◆ wrap_and_centre_align_with_right_bias()

std::string lector::wrap_and_centre_align_with_right_bias	(	const std::string_view	text,
		const std::size_t	line_length
	)

Centre-aligns and wraps a string of text to a line length. If the total required centre-aligning padding is odd, the text is biased by one space towards the right.

Parameters

[in]	text	The string of text to wrap and centre-align.
[in]	line_length	The desired line length to use when wrapping. Must be strictly greater than zero. Very long words whose lengths exceed this line length are hyphenated.

Returns: The wrapped and centre-aligned string of text.

Exceptions

std::invalid_argument if the desired line length is zero.

◆ wrap_and_left_align()

std::string lector::wrap_and_left_align	(	const std::string_view	text,
		const std::size_t	line_length
	)

Left-aligns and wraps a string of text to a line length.

Parameters

[in]	text	The string of text to wrap and left-align.
[in]	line_length	The desired line length to use when wrapping. Must be strictly greater than zero. Very long words whose lengths exceed this line length are hyphenated.

Returns: The wrapped and left-aligned string of text.

Exceptions

std::invalid_argument if the desired line length is zero.

◆ wrap_and_right_align()

std::string lector::wrap_and_right_align	(	const std::string_view	text,
		const std::size_t	line_length
	)

Right-aligns and wraps a string of text to a line length.

Parameters

[in]	text	The string of text to wrap and right-align.
[in]	line_length	The desired line length to use when wrapping. Must be strictly greater than zero. Very long words whose lengths exceed this line length are hyphenated.

Returns: The wrapped and right-aligned string of text.

Exceptions

std::invalid_argument if the desired line length is zero.

Variable Documentation

◆ Names

template<typename Type >

constexpr std::array<lector::Name<Type>, 0UL> lector::Names {}

constexpr

Map of canonical printed names to their corresponding values of a specified type.

Template Parameters

Type	The type of the values.

◆ Spellings

template<typename Type >

constexpr std::array<lector::Spelling<Type>, 0UL> lector::Spellings {}

constexpr

Map of spellings to their corresponding values of a specified type.

Template Parameters

Type	The type of the values.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Name

◆ Spelling

Enumeration Type Documentation

◆ Arity

◆ Form

◆ Importance

Function Documentation

◆ byte_interval()

◆ code_points()

◆ collate_and_centre_align_with_left_bias()

◆ collate_and_centre_align_with_right_bias()

◆ collate_and_left_align()

◆ collate_and_right_align()

◆ contains_whitespace()

◆ is_leading_byte()

◆ join_and_centre_align_with_left_bias()

◆ join_and_centre_align_with_right_bias()

◆ join_and_left_align()

◆ join_and_right_align()

◆ longest_word_length()

◆ pad_left()

◆ pad_right()

◆ parse() [1/16]

◆ parse() [2/16]

◆ parse() [3/16]

◆ parse() [4/16]

◆ parse() [5/16]

◆ parse() [6/16]

◆ parse() [7/16]

◆ parse() [8/16]

◆ parse() [9/16]

◆ parse() [10/16]

◆ parse() [11/16]

◆ parse() [12/16]

◆ parse() [13/16]

◆ parse() [14/16]

◆ parse() [15/16]

◆ parse() [16/16]

◆ parse_enumeration()

◆ print() [1/16]

◆ print() [2/16]

◆ print() [3/16]

◆ print() [4/16]

◆ print() [5/16]

◆ print() [6/16]

◆ print() [7/16]

◆ print() [8/16]

◆ print() [9/16]

◆ print() [10/16]

◆ print() [11/16]

◆ print() [12/16]

◆ print() [13/16]

◆ print() [14/16]

◆ print() [15/16]

◆ print() [16/16]

◆ print_enumeration()

◆ quote()

◆ quote_if_contains_whitespace()

◆ tokenize()

◆ wrap()

◆ wrap_and_centre_align_with_left_bias()

◆ wrap_and_centre_align_with_right_bias()

◆ wrap_and_left_align()

◆ wrap_and_right_align()

Variable Documentation

◆ Names

◆ Spellings