#include <string.hpp>

Public Types
using	string_type = typename traits::string_type

using	size_type = typename traits::size_type

using	char_type = typename traits::char_type

using	view_type = typename traits::view_type

using	int_type = typename traits::int_type

using	codepoint_type = typename traits::codepoint_type

template<typename... ParameterTypes>
using	FormatString = detail::BasicFormatString< char_type, std::type_identity_t< ParameterTypes >... >

Public Member Functions
template<StandardStringLike T>
constexpr auto	size (T &&value) -> size_type

template<typename IteratorType >
auto	decode_codepoint (IteratorType &it, const IteratorType &end) -> std::optional< codepoint_type >

template<char UnicodePrefix>
requires fly::UnicodePrefixCharacter< UnicodePrefix > auto	escape_all_codepoints (view_type value) -> std::optional< string_type >

template<char UnicodePrefix, typename IteratorType >
requires fly::UnicodePrefixCharacter< UnicodePrefix > auto	escape_codepoint (IteratorType &it, const IteratorType &end) -> std::optional< string_type >

template<typename IteratorType >
auto	unescape_codepoint (IteratorType &it, const IteratorType &end) -> std::optional< string_type >

template<typename... ParameterTypes>
auto	format (FormatString< ParameterTypes... > &&fmt, ParameterTypes &&...parameters) -> string_type

template<typename... Args>
auto	join (char_type separator, Args &&...args) -> string_type

Static Public Member Functions
template<StandardStringLike T>
static constexpr size_type	size (T &&value)

static constexpr bool	is_alpha (char_type ch)

static constexpr bool	is_upper (char_type ch)

static constexpr bool	is_lower (char_type ch)

static constexpr char_type	to_upper (char_type ch)

static constexpr char_type	to_lower (char_type ch)

static constexpr bool	is_digit (char_type ch)

static constexpr bool	is_x_digit (char_type ch)

static constexpr bool	is_space (char_type ch)

static std::vector< string_type >	split (view_type input, char_type delimiter)

static std::vector< string_type >	split (view_type input, char_type delimiter, size_type count)

static void	trim (string_type &target)

static void	replace_all (string_type &target, view_type search, char_type replace)

static void	replace_all (string_type &target, view_type search, view_type replace)

static void	remove_all (string_type &target, view_type search)

static bool	wildcard_match (view_type source, view_type search)

static bool	validate (view_type value)

template<typename IteratorType >
static std::optional< codepoint_type >	decode_codepoint (IteratorType &it, const IteratorType &end)

static std::optional< string_type >	encode_codepoint (codepoint_type codepoint)

template<char UnicodePrefix = 'U'>
requires static fly::UnicodePrefixCharacter< UnicodePrefix > std::optional< string_type >	escape_all_codepoints (view_type value)

template<char UnicodePrefix = 'U', typename IteratorType >
requires static fly::UnicodePrefixCharacter< UnicodePrefix > std::optional< string_type >	escape_codepoint (IteratorType &it, const IteratorType &end)

static std::optional< string_type >	unescape_all_codepoints (view_type value)

template<typename IteratorType >
static std::optional< string_type >	unescape_codepoint (IteratorType &it, const IteratorType &end)

static string_type	generate_random_string (size_type length)

template<typename... ParameterTypes>
static string_type	format (FormatString< ParameterTypes... > &&fmt, ParameterTypes &&...parameters)

template<typename OutputIterator , typename... ParameterTypes>
static void	format_to (OutputIterator output, FormatString< ParameterTypes... > &&fmt, ParameterTypes &&...parameters)

template<typename... Args>
static string_type	join (char_type separator, Args &&...args)

template<typename T >
static std::optional< T >	convert (const string_type &value)

Detailed Description

template<StandardCharacter CharType>
class fly::BasicString< CharType >

Static class to provide string utilities not provided by the STL.

Author: Timothy Flynn (trfly.nosp@m.nn89.nosp@m.@pm.m.nosp@m.e)

Version: March 21, 2019

Member Function Documentation

◆ convert()

template<StandardCharacter CharType>

template<typename T >

std::optional< T > fly::BasicString< CharType >::convert ( const string_type & value )

static

Convert a string to another type. The other type may be a string with a different Unicode encoding or a plain-old-data type, e.g. int or bool.

Template Parameters

T	The desired type.

Parameters

value The string to convert.

Returns: If successful, the string coverted to the specified type. Otherwise, an uninitialized value.

◆ decode_codepoint()

template<StandardCharacter CharType>

template<typename IteratorType >

static std::optional<codepoint_type> fly::BasicString< CharType >::decode_codepoint	(	IteratorType &	it,
		const IteratorType &	end
	)

static

Decode a single Unicode codepoint, starting at the character pointed to by the provided iterator. If successful, after invoking this method, that iterator will point at the first character after the Unicode codepoint in the source string.

Template Parameters

IteratorType The type of the encoded Unicode codepoint's iterator.

Parameters

it	Pointer to the beginning of the encoded Unicode codepoint.
end	Pointer to the end of the encoded Unicode codepoint.

Returns: If successful, the decoded Unicode codepoint. Otherwise, an uninitialized value.

◆ encode_codepoint()

template<StandardCharacter CharType>

auto fly::BasicString< CharType >::encode_codepoint ( codepoint_type codepoint )

inlinestatic

Encode a single Unicode codepoint.

Parameters

codepoint The Unicode codepoint to encode.

Returns: If successful, a string containing the encoded Unicode codepoint. Otherwise, an uninitialized value.

◆ escape_all_codepoints()

template<StandardCharacter CharType>

template<char UnicodePrefix = 'U'>

requires static fly::UnicodePrefixCharacter<UnicodePrefix> std::optional<string_type> fly::BasicString< CharType >::escape_all_codepoints ( view_type value )

static

Escape all Unicode codepoints in a string.

If the Unicode codepoint is an ASCII, non-control character (i.e. codepoints in the range [U+0020, U+007E]), that character is not escaped.

If the Unicode codepoint is non-ASCII or a control character (i.e. codepoints in the range [U+0000, U+001F] or [U+007F, U+10FFFF]), the codepoint is encoded as follows, taking into consideration the provided Unicode prefix character:

1. If the Unicode codepoint is in the range [U+0000, U+001F] or [U+007F, U+FFFF],
   regardless of the prefix character, the encoding will be of the form \unnnn.
2. If the codepoint is in the range [U+10000, U+10FFFF], and the prefix character is 'u',
   the encoding will be a surrogate pair of the form \unnnn\unnnn.
3. If the codepoint is in the range [U+10000, U+10FFFF], and the prefix character is 'U',
   the encoding will of the form \Unnnnnnnn.

Template Parameters

UnicodePrefix The Unicode prefix character ('u' or 'U').

Parameters

value The string to escape.

Returns: If successful, a copy of the source string with all Unicode codepoints escaped. Otherwise, an uninitialized value.

◆ escape_codepoint()

template<StandardCharacter CharType>

template<char UnicodePrefix = 'U', typename IteratorType >

requires static fly::UnicodePrefixCharacter<UnicodePrefix> std::optional<string_type> fly::BasicString< CharType >::escape_codepoint	(	IteratorType &	it,
		const IteratorType &	end
	)

static

Escape a single Unicode codepoint, starting at the character pointed to by the provided iterator. If successful, after invoking this method, that iterator will point at the first character after the Unicode codepoint in the source string.

If the Unicode codepoint is an ASCII, non-control character (i.e. codepoints in the range [U+0020, U+007E]), that character is not escaped.

If the Unicode codepoint is non-ASCII or a control character (i.e. codepoints in the range [U+0000, U+001F] or [U+007F, U+10FFFF]), the codepoint is encoded as follows, taking into consideration the provided Unicode prefix character:

1. If the Unicode codepoint is in the range [U+0000, U+001F] or [U+007F, U+FFFF],
   regardless of the prefix character, the encoding will be of the form \unnnn.
2. If the codepoint is in the range [U+10000, U+10FFFF], and the prefix character is 'u',
   the encoding will be a surrogate pair of the form \unnnn\unnnn.
3. If the codepoint is in the range [U+10000, U+10FFFF], and the prefix character is 'U',
   the encoding will of the form \Unnnnnnnn.

Template Parameters

UnicodePrefix	The Unicode prefix character ('u' or 'U').
IteratorType	The type of the encoded Unicode codepoint's iterator.

Parameters

it	Pointer to the beginning of the encoded Unicode codepoint.
end	Pointer to the end of the encoded Unicode codepoint.

Returns: If successful, a string containing the escaped Unicode codepoint. Otherwise, an uninitialized value.

◆ format()

template<StandardCharacter CharType>

template<typename... ParameterTypes>

static string_type fly::BasicString< CharType >::format	(	FormatString< ParameterTypes... > &&	fmt,
		ParameterTypes &&...	parameters
	)

static

Format a string with a set of format parameters, returning the formatted string. Based strongly upon: https://en.cppreference.com/w/cpp/utility/format/format.

A format string consists of:

1. Any character other than "{" or "}", which are copied unchanged to the output.
2. Escape sequences "{{" and "}}", which are replaced with "{" and "}" in the output.
3. Replacement fields.

Replacement fields may be of the form:

1. An introductory "{" character.
2. An optional non-negative position.
3. An optional colon ":" following by formatting options.
4. A final "}" character.

For a detailed description of replacement fields, see fly::detail::BasicFormatSpecifier.

This implementation differs from std::format in the following ways:

All standard string types are supported as format strings.
All standard string types are supported as format parameters, even if that type differs from the format string type. If the type differs, the format parameter is transcoded to the type of the format string.
This implementation is exceptionless. Any error encountered (such as failed transcoding in (2) above) results in the format parameter that caused the error to be dropped.
Locale-specific form is not supported. If the option appears in the format string, it will be parsed, but will be ignored.

The format string type is implicitly constructed from a C-string literal. Callers should only invoke this method accordingly:

fly::String::format("Format {:d}", 1);

On compilers that support immediate functions (consteval), the format string is validated at compile time against the types of the format parameters. If the format string is invalid, a compile error with a diagnostic message will be raised. On other compilers, the error message will be returned rather than a formatted string.

Replacement fields for user-defined types are parsed at runtime. To format a user-defined type, a fly::Formatter specialization must be defined, analagous to std::formatter. The specialization may extend a standard fly::Formatter, for example:

template <typename CharType>
struct fly::Formatter<MyType, CharType> : public fly::Formatter<int, CharType>
{
    template <typename FormatContext>
    void format(const MyType &value, FormatContext &context)
    {
        fly::Formatter<int, CharType>::format(value.as_int(), context);
    }
};

Or, the formatter may be defined without without inheritence:

template <typename CharType>
struct fly::Formatter<MyType, CharType>
{
    bool m_option {false};

    template <typename FormatParseContext>
    constexpr void parse(FormatParseContext &context)
    {
        if (context.lexer().consume_if(FLY_CHR(CharType, 'o')))
        {
            m_option = true;
        }
        if (!context.lexer().consume_if(FLY_CHR(CharType, '}')))
        {
            context.on_error("UserDefinedTypeWithParser error!");
        }
    }

    template <typename FormatContext>
    void format(const MyType &value, FormatContext &context)
    {
        fly::BasicString<CharType>::format_to(context.out(), "{}", value.as_int());
    }
};

The |parse| method is optional. If defined, it is provided a BasicFormatParseContext which contains a lexer that may be used to parse the format string. The position of the lexer will be one of the following within the replacement field:

1. The position immediately after the colon, if there is one.
2. Otherwise, the position immediately after the format parameter index, if there is one.
3. Otherwise, the position immeidately after the opening brace.

The |parse| method is expected to consume up to and including the closing "}" character. It must be declared constexpr, as it will be invoked at compile time to validate the replacement field. The parser may indicate any parsing errors through the parsing context; if an error occurs, the error is handled the same as any standard replacement field (see above). Even though the parser is invoked at compile time, the result of user-defined parsing cannot be stored generically. Thus, parsing is invoked again at runtime immediately before |format|.

Template Parameters

ParameterTypes Variadic format parameter types.

Parameters

fmt	The string to format.
parameters	The variadic list of format parameters to be formatted.

Returns: A string that has been formatted with the given format parameters.

◆ format_to()

template<StandardCharacter CharType>

template<typename OutputIterator , typename... ParameterTypes>

void fly::BasicString< CharType >::format_to	(	OutputIterator	output,
		FormatString< ParameterTypes... > &&	fmt,
		ParameterTypes &&...	parameters
	)

static

Format a string with a set of format parameters to an existing output iterator. Based strongly upon: https://en.cppreference.com/w/cpp/utility/format/format.

For a detailed description of string formatting, see fly::BasicString::format.

Template Parameters

OutputIterator	The type of the output iterator.
ParameterTypes	Variadic format parameter types.

Parameters

output	The output iterator to write to.
fmt	The string to format.
parameters	The variadic list of format parameters to be formatted.

Returns: A string that has been formatted with the given format parameters.

◆ generate_random_string()

template<StandardCharacter CharType>

auto fly::BasicString< CharType >::generate_random_string ( size_type length )

static

Generate a random string of the given length.

Parameters

length The length of the string to generate.

Returns: The generated string.

◆ is_alpha()

template<StandardCharacter CharType>

constexpr bool fly::BasicString< CharType >::is_alpha ( char_type ch )

staticconstexpr

Checks if the given character is an alphabetic character as classified by the default C locale.

The STL's std::isalpha and std::iswalpha require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to classify.

Returns: True if the character is an alphabetic character.

◆ is_digit()

template<StandardCharacter CharType>

constexpr bool fly::BasicString< CharType >::is_digit ( char_type ch )

staticconstexpr

Checks if the given character is a decimal digit character.

The STL's std::isdigit and std::iswdigit require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to classify.

Returns: True if the character is a decimal digit character.

◆ is_lower()

template<StandardCharacter CharType>

constexpr bool fly::BasicString< CharType >::is_lower ( char_type ch )

staticconstexpr

Checks if the given character is a lower-case alphabetic character as classified by the default C locale.

The STL's std::islower and std::iswlower require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to classify.

Returns: True if the character is an alphabetic character.

◆ is_space()

template<StandardCharacter CharType>

constexpr bool fly::BasicString< CharType >::is_space ( char_type ch )

staticconstexpr

Checks if the given character is a whitespace character as classified by the default C locale.

The STL's std::isspace and std::iswspace require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to classify.

Returns: True if the character is a whitespace character.

◆ is_upper()

template<StandardCharacter CharType>

constexpr bool fly::BasicString< CharType >::is_upper ( char_type ch )

staticconstexpr

Checks if the given character is an upper-case alphabetic character as classified by the default C locale.

The STL's std::isupper and std::iswupper require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to classify.

Returns: True if the character is an alphabetic character.

◆ is_x_digit()

template<StandardCharacter CharType>

constexpr bool fly::BasicString< CharType >::is_x_digit ( char_type ch )

staticconstexpr

Checks if the given character is a hexadecimal digit character.

The STL's std::isxdigit and std::iswxdigit require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to classify.

Returns: True if the character is a hexadecimal digit character.

◆ join()

template<StandardCharacter CharType>

template<typename... Args>

static string_type fly::BasicString< CharType >::join	(	char_type	separator,
		Args &&...	args
	)

static

Concatenate a list of objects with the given separator.

Template Parameters

Args	Variadic template arguments.

Parameters

separator	Character to use as a separator.
args	The variadic list of arguments to be joined.

Returns: The resulting join of the given arguments.

◆ remove_all()

template<StandardCharacter CharType>

void fly::BasicString< CharType >::remove_all	(	string_type &	target,
		view_type	search
	)

static

Remove all instances of a substring in a string.

Parameters

target	The string container which will be modified.
search	The string to search for and remove.

◆ replace_all() [1/2]

template<StandardCharacter CharType>

void fly::BasicString< CharType >::replace_all	(	string_type &	target,
		view_type	search,
		char_type	replace
	)

static

Replace all instances of a substring in a string with a character.

Parameters

target	The string container which will be modified.
search	The string to search for and replace.
replace	The replacement character.

◆ replace_all() [2/2]

template<StandardCharacter CharType>

void fly::BasicString< CharType >::replace_all	(	string_type &	target,
		view_type	search,
		view_type	replace
	)

static

Replace all instances of a substring in a string with another string.

Parameters

target	The string container which will be modified.
search	The string to search for and replace.
replace	The replacement string.

◆ size()

template<StandardCharacter CharType>

template<StandardStringLike T>

static constexpr size_type fly::BasicString< CharType >::size ( T && value )

staticconstexpr

Determine the length of any string-like value. Accepts character arrays, std::basic_string specializations, and std::basic_string_view specializations.

Template Parameters

T	The string-like type.

Parameters

value The string-like value.

Returns: The length of the string-like value.

◆ split() [1/2]

template<StandardCharacter CharType>

auto fly::BasicString< CharType >::split	(	view_type	input,
		char_type	delimiter
	)

static

Split a string into a vector of strings.

Parameters

input	The string to split.
delimiter	The delimiter to split the string on.

Returns: A vector containing the split strings.

◆ split() [2/2]

template<StandardCharacter CharType>

auto fly::BasicString< CharType >::split	(	view_type	input,
		char_type	delimiter,
		size_type	count
	)

static

Split a string into a vector of strings, up to a maximum size. If the max size is reached, the rest of the string is appended to the last element in the vector.

Parameters

input	The string to split.
delimiter	The delimiter to split the string on.
count	The maximum return vector size. Zero implies unlimited.

Returns: A vector containing the split strings.

◆ to_lower()

template<StandardCharacter CharType>

constexpr auto fly::BasicString< CharType >::to_lower ( char_type ch )

staticconstexpr

Converts the given character to a lower-case alphabetic character as classified by the default C locale.

The STL's std:tolower and std::towlower require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to convert.

Returns: The converted character.

◆ to_upper()

template<StandardCharacter CharType>

constexpr auto fly::BasicString< CharType >::to_upper ( char_type ch )

staticconstexpr

Converts the given character to an upper-case alphabetic character as classified by the default C locale.

The STL's std:toupper and std::towupper require that the provided character fits into an unsigned char and unsigned wchar_t, respectively. Other values result in undefined behavior. This method has no such restriction.

Parameters

ch	The character to convert.

Returns: The converted character.

◆ trim()

template<StandardCharacter CharType>

void fly::BasicString< CharType >::trim ( string_type & target )

static

Remove leading and trailing whitespace from a string.

Parameters

target The string to trim.

◆ unescape_all_codepoints()

template<StandardCharacter CharType>

auto fly::BasicString< CharType >::unescape_all_codepoints ( view_type value )

static

Unescape all Unicode codepoints in a string.

Accepts escaped sequences of the following forms:

1. \unnnn for Unicode codepoints in the range [U+0000, U+FFFF].
2. \unnnn\unnnn surrogate pairs for Unicode codepoints in the range [U+10000, U+10FFFF].
3. \Unnnnnnnn for all Unicode codepoints.

Parameters

value The string containing the escaped character sequence.

Returns: If successful, a copy of the source string with all Unicode codepoints unescaped. Otherwise, an uninitialized value.

◆ unescape_codepoint()

template<StandardCharacter CharType>

template<typename IteratorType >

static std::optional<string_type> fly::BasicString< CharType >::unescape_codepoint	(	IteratorType &	it,
		const IteratorType &	end
	)

static

Unescape a single Unicode codepoint, starting at the character pointed to by provided iterator. If successful, after invoking this method, that iterator will point at the first character after the escaped sequence in the source string.

Accepts escaped sequences of the following forms:

1. \unnnn for Unicode codepoints in the range [U+0000, U+FFFF].
2. \unnnn\unnnn surrogate pairs for Unicode codepoints in the range [U+10000, U+10FFFF].
3. \Unnnnnnnn for all Unicode codepoints.

Template Parameters

IteratorType The type of the escaped Unicode string's iterator.

Parameters

it	Pointer to the beginning of the escaped character sequence.
end	Pointer to the end of the escaped character sequence.

Returns: If successful, a string containing the unescaped Unicode codepoint. Otherwise, an uninitialized value.

◆ validate()

template<StandardCharacter CharType>

bool fly::BasicString< CharType >::validate ( view_type value )

inlinestatic

Validate that a string is strictly Unicode compliant.

Parameters

value The string to validate.

Returns: True if the string is Unicode compliant.

◆ wildcard_match()

template<StandardCharacter CharType>

bool fly::BasicString< CharType >::wildcard_match	(	view_type	source,
		view_type	search
	)

static

Check if a string matches another string with wildcard expansion.

Parameters

source	The source string to match against.
search	The wildcard string to search with.

Returns: True if the wildcard string matches the source string.

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

fly/types/string/string.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

template<StandardCharacter CharType> class fly::BasicString< CharType >

Member Function Documentation

◆ convert()

◆ decode_codepoint()

◆ encode_codepoint()

◆ escape_all_codepoints()

◆ escape_codepoint()

◆ format()

◆ format_to()

◆ generate_random_string()

◆ is_alpha()

◆ is_digit()

◆ is_lower()

◆ is_space()

◆ is_upper()

◆ is_x_digit()

◆ join()

◆ remove_all()

◆ replace_all() [1/2]

◆ replace_all() [2/2]

◆ size()

◆ split() [1/2]

◆ split() [2/2]

◆ to_lower()

◆ to_upper()

◆ trim()

◆ unescape_all_codepoints()

◆ unescape_codepoint()

◆ validate()

◆ wildcard_match()

template<StandardCharacter CharType>
class fly::BasicString< CharType >