xentara-utils v1.0
Xentara utilities library
xentara::utils::string Namespace Reference

String utilities. More...

Classes

class  StaticString
 A statically allocated string. More...
 
class  Utf16Converter
 A converter to convert UTF-8 strings to UTF-16. More...
 
class  Utf8Converter
 A converter to convert UTF-16 strings to UTF-8. More...
 
class  view
 This is a wrapper class that supplies missing operator + () for string views. More...
 

Concepts

concept  CharacterType
 A concept for character data.
 

Functions

template<typename... Fragments>
auto cat (const Fragments &... fragments) -> std::string
 Concatenates a number of fragments to a string in local encoding. More...
 
template<tools::Integral Value>
auto fromString (std::u16string_view string) -> std::variant< Value, std::errc >
 Converts a UTF-16 string into a number. More...
 
template<typename Char , typename Traits >
constexpr auto fromStringView (const std::basic_string_view< Char, Traits > &view) -> std::basic_string< Char, Traits >
 Crates va string from a string view. More...
 
template<tools::Arithmetic Type>
constexpr auto maxNumericLength () -> std::size_t
 Returns the maximum length needed to hold a number of a certain type. More...
 
template<CharacterType Character>
constexpr auto strlen (const Character *string) -> std::size_t
 Calculate the length of a string. More...
 
constexpr auto strlen (std::nullptr_t) -> std::size_t
 Overload for xentara::utils::core::strlen() for literal null pointers. More...
 
template<tools::CharType Char, tools::Arithmetic Number>
auto toStaticString (Number number) -> StaticString< Char, maxNumericLength< Number >()>
 Converts a number into a string using a statically allocated buffer. More...
 
template<tools::Arithmetic Value>
auto toString (Value value) -> std::u16string
 Converts a number to a UTF-16 string. More...
 
auto toString (std::chrono::system_clock::time_point timePoint) -> std::u16string
 Converts a time point to a UTF-16 string. More...
 
template<tools::Arithmetic Value>
auto toUtf8String (Value value) -> std::u8string
 Converts a number to a UTF-8 string. More...
 
auto toUtf8String (std::chrono::system_clock::time_point timePoint) -> std::u8string
 Converts a time point to a UTF-8 string. More...
 
template<tools::Arithmetic Value>
auto toLocalString (Value value) -> StaticString< char, maxNumericLength< Value >()>
 Creates a buffer that contains the string representation of a number as a local string. More...
 
template<std::convertible_to< std::u8string_view > View>
 Utf16Converter (View &&) -> Utf16Converter< typename std::u8string_view::const_iterator, typename std::u8string_view::const_iterator >
 
template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::output_iterator< char16_t > OutputIterator, std::sentinel_for< OutputIterator > OutputSentinel = std::unreachable_sentinel_t>
requires std::convertible_to<std::iter_value_t<InputIterator>, char8_t>
auto toUtf16 (InputIterator begin, InputSentinel end, OutputIterator output, OutputSentinel outputEnd=std::unreachable_sentinel) -> OutputIterator
 Converts a UTF-8 string to UTF-16. More...
 
template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char8_t>
auto toUtf16 (InputIterator begin, InputSentinel end) -> std::u16string
 Converts a UTF-8 string to UTF-16. More...
 
auto toUtf16 (std::u8string_view string) -> std::u16string
 Converts a UTF-8 string to UTF-16. More...
 
auto toUtf16 (std::string_view string) -> std::u16string
 Converts a UTF-8 string to UTF-16. More...
 
template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char8_t>
auto utf16Size (InputIterator begin, InputSentinel end) -> std::size_t
 Gets the size of a UTF-8 string when converted to to UTF-16. More...
 
auto utf16Size (std::u8string_view string) -> std::size_t
 Gets the size of a UTF-8 string when converted to to UTF-16. More...
 
auto utf16Size (std::string_view string) -> std::size_t
 Gets the size of a UTF-8 string when converted to to UTF-16. More...
 
template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::output_iterator< char8_t > OutputIterator, std::sentinel_for< OutputIterator > OutputSentinel = std::unreachable_sentinel_t>
requires std::convertible_to<std::iter_value_t<InputIterator>, char16_t>
auto toUtf8 (InputIterator begin, InputSentinel end, OutputIterator output, OutputSentinel outputEnd=std::unreachable_sentinel) -> OutputIterator
 Converts a UTF-16 string to UTF-8. More...
 
template<std::constructible_from< char8_t > Char = char8_t, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char16_t>
auto toUtf8 (InputIterator begin, InputSentinel end) -> std::basic_string< Char >
 Converts a UTF-16 string to UTF-8. More...
 
template<std::constructible_from< char8_t > Char = char8_t>
auto toUtf8 (std::u16string_view string) -> std::basic_string< Char >
 Converts a UTF-16 string to UTF-8. More...
 
template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char16_t>
auto utf8Size (InputIterator begin, InputSentinel end) -> std::size_t
 Gets the size of a UTF-16 string when converted to to UTF-8. More...
 
auto utf8Size (std::u16string_view string) -> std::size_t
 Gets the size of a UTF-16 string when converted to to UTF-8. More...
 

Detailed Description

String utilities.

This namespace contains string utilities.

Function Documentation

◆ cat()

template<typename... Fragments>
auto xentara::utils::string::cat ( const Fragments &...  fragments) -> std::string

Concatenates a number of fragments to a string in local encoding.

The fragments can be anything convertible to an std::string_view, an std::u8string_view, or an std::u16string_view, as well as any number, character, or boolean value.

Please note that the type char will be interpreted as a character, not a number.

Note
Under Windows, types convertible to std::wstring_view are supported as well, to enable passing WCHAR-based strings to xentara::utils::string::cat().
Support for User Defined Types
cat uses customization points to allow adding support for concatenating user defined types. The customization points are either namespace scope functions or function objects findable by ADL lookup, or member functions of the custom type.

There are two was to support concatenation using cat.

1. Using xentara_cat_string

In order to use this approach, you must provide one of the following:

  • a function or function object named xentara_cat_string, that is const-callable as xentara_cat_string(const UserDefinedType &fragment), or
  • a member function named xentara_cat_string, that can be called as fragment.xentara_cat_string() on a const object.

The function must return any other value that is supported by cat.

2. Using xentara_cat_size and xentara_cat_append

In order to use this approach, you must provide one of the following:

  • a function or function object named xentara_cat_append, that is const-callable as xentara_cat_append(std::string &string, const UserDefinedType &fragment), or
  • a member function named xentara_cat_append, that can be called as fragment.xentara_cat_append(std::string &string) on a const object.

The function must append a text representation of the given object to the given string.

To enable cat to pre-allocate the storage, you must also provide one of the following:

  • a function or function object named xentara_cat_size, that is const-callable as xentara_cat_size(const UserDefinedType &fragment),
  • a member function named xentara_cat_size, that can be called as fragment.xentara_cat_append() on a const object, or
  • a member function named size, that can be called as fragment.xentara_cat_append() on a const object.

The function must return the number of characters that will be appended when calling xentara_cat_append.

Parameters
fragmentsThe fragments
Returns
The convatenated string

◆ fromString()

template<tools::Integral Value>
auto xentara::utils::string::fromString ( std::u16string_view  string) -> std::variant<Value, std::errc>

Converts a UTF-16 string into a number.

Parameters
stringThe string
Returns
The number, or an error code on failure

◆ fromStringView()

template<typename Char , typename Traits >
constexpr auto xentara::utils::string::fromStringView ( const std::basic_string_view< Char, Traits > &  view) -> std::basic_string<Char, Traits>
constexpr

Crates va string from a string view.

Template Parameters
Char
Traits
Parameters
view
Returns

◆ maxNumericLength()

template<tools::Arithmetic Type>
constexpr auto xentara::utils::string::maxNumericLength ( ) -> std::size_t
constexpr

Returns the maximum length needed to hold a number of a certain type.

This function can be used to preallocate buffers used to format numeric strings.

Returns
The maximum buffer size required to format the number, using the format used by std::to_chars.

◆ strlen() [1/2]

template<CharacterType Character>
constexpr auto xentara::utils::string::strlen ( const Character *  string) -> std::size_t
constexpr

Calculate the length of a string.

Calculates the number of characters in a string. The behaviour is undefined if string is not nullptr or a null terminated character array.

This function has a number of differences compared to std::strlen:

  • The function is constexpr
  • The function can take a string of any character type
  • The function will interpret nullptr as a zero-length string
    Note
    Like std::strlen, this function does not count code points, but code units. In an UTF-8 string, for example, this function will simply count the number of bytes in the string, without accounting for multi byte characters.
    Parameters
    stringThe string. Must be either a null terminated string, or nullptr.
    Returns
    The number of code units contained in the string

◆ strlen() [2/2]

constexpr auto xentara::utils::string::strlen ( std::nullptr_t  ) -> std::size_t
constexpr

Overload for xentara::utils::core::strlen() for literal null pointers.

Returns
Always returns 0

◆ toLocalString()

template<tools::Arithmetic Value>
auto xentara::utils::string::toLocalString ( Value  value) -> StaticString<char, maxNumericLength<Value>()>

Creates a buffer that contains the string representation of a number as a local string.

◆ toStaticString()

template<tools::CharType Char, tools::Arithmetic Number>
auto xentara::utils::string::toStaticString ( Number  number) -> StaticString<Char, maxNumericLength<Number>()>

Converts a number into a string using a statically allocated buffer.

◆ toString() [1/2]

auto xentara::utils::string::toString ( std::chrono::system_clock::time_point  timePoint) -> std::u16string

Converts a time point to a UTF-16 string.

Parameters
timePointThe time point
Returns
A string containing the time point

◆ toString() [2/2]

template<tools::Arithmetic Value>
auto xentara::utils::string::toString ( Value  value) -> std::u16string

Converts a number to a UTF-16 string.

Parameters
valueThe number
Returns
A string containing the number

◆ toUtf16() [1/4]

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char8_t>
auto xentara::utils::string::toUtf16 ( InputIterator  begin,
InputSentinel  end 
) -> std::u16string

Converts a UTF-8 string to UTF-16.

This function converts a UTF-8 character sequence to UTF-16. Illegal characters (high and low surrogates, and code points higher than U+10FFFF) and non-decodable bytes are replaced by the replacement character.

Parameters
beginThe beginning of the input sequence
endThe end of the input sequence
Returns
Returns the output sequence as a string

◆ toUtf16() [2/4]

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::output_iterator< char16_t > OutputIterator, std::sentinel_for< OutputIterator > OutputSentinel = std::unreachable_sentinel_t>
requires std::convertible_to<std::iter_value_t<InputIterator>, char8_t>
auto xentara::utils::string::toUtf16 ( InputIterator  begin,
InputSentinel  end,
OutputIterator  output,
OutputSentinel  outputEnd = std::unreachable_sentinel 
) -> OutputIterator

Converts a UTF-8 string to UTF-16.

This function converts a UTF-8 character sequence to UTF-16. Illegal characters (high and low surrogates, and code points higher than U+10FFFF) and non-decodable bytes are replaced by the replacement character.

Parameters
beginThe beginning of the input sequence
endThe end of the input sequence
outputAn output iterator for the output sequence
outputEndA sentinel to mark the end of the output sequence
Returns
Returns an iterator to the position beyond the last character written to the output sequence

◆ toUtf16() [3/4]

auto xentara::utils::string::toUtf16 ( std::string_view  string) -> std::u16string

Converts a UTF-8 string to UTF-16.

This function converts a UTF-8 character sequence to UTF-16. Illegal characters (high and low surrogates, and code points higher than U+10FFFF) and non-decodable bytes are replaced by the replacement character.

Parameters
stringThe input sequence
Returns
Returns the output sequence as a string

◆ toUtf16() [4/4]

auto xentara::utils::string::toUtf16 ( std::u8string_view  string) -> std::u16string

Converts a UTF-8 string to UTF-16.

This function converts a UTF-8 character sequence to UTF-16. Illegal characters (high and low surrogates, and code points higher than U+10FFFF) and non-decodable bytes are replaced by the replacement character.

Parameters
stringThe input sequence
Returns
Returns the output sequence as a string

◆ toUtf8() [1/3]

template<std::constructible_from< char8_t > Char = char8_t, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char16_t>
auto xentara::utils::string::toUtf8 ( InputIterator  begin,
InputSentinel  end 
) -> std::basic_string<Char>

Converts a UTF-16 string to UTF-8.

This function converts a UTF-16 character sequence to UTF-8. Orphaned surrogates are replaced by the replacement character.

Template Parameters
Charthe character type for the output sequence. Usually, this should be char8_t or char.
Parameters
beginThe beginning of the input sequence
endThe end of the input sequence
Returns
Returns the output sequence as a string

◆ toUtf8() [2/3]

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::output_iterator< char8_t > OutputIterator, std::sentinel_for< OutputIterator > OutputSentinel = std::unreachable_sentinel_t>
requires std::convertible_to<std::iter_value_t<InputIterator>, char16_t>
auto xentara::utils::string::toUtf8 ( InputIterator  begin,
InputSentinel  end,
OutputIterator  output,
OutputSentinel  outputEnd = std::unreachable_sentinel 
) -> OutputIterator

Converts a UTF-16 string to UTF-8.

This function converts a UTF-16 character sequence to UTF-8. Orphaned surrogates are replaced by the replacement character.

Template Parameters
Charthe character type for the output sequence. Usually, this should be char8_t or char.
Parameters
beginThe beginning of the input sequence
endThe end of the input sequence
outputAn output iterator for the output sequence
outputEndA sentinel to mark the end of the output sequence
Returns
Returns an iterator to the position beyond the last character written to the output sequence

◆ toUtf8() [3/3]

template<std::constructible_from< char8_t > Char = char8_t>
auto xentara::utils::string::toUtf8 ( std::u16string_view  string) -> std::basic_string<Char>

Converts a UTF-16 string to UTF-8.

This function converts a UTF-16 character sequence to UTF-8. Orphaned surrogates are replaced by the replacement character.

Template Parameters
Charthe character type for the output sequence. Usually, this should be char8_t or char.
Parameters
stringThe input sequence
Returns
Returns the output sequence as a string

◆ toUtf8String() [1/2]

auto xentara::utils::string::toUtf8String ( std::chrono::system_clock::time_point  timePoint) -> std::u8string

Converts a time point to a UTF-8 string.

Parameters
timePointThe time point
Returns
A string containing the time point

◆ toUtf8String() [2/2]

template<tools::Arithmetic Value>
auto xentara::utils::string::toUtf8String ( Value  value) -> std::u8string

Converts a number to a UTF-8 string.

Parameters
valueThe number
Returns
A string containing the number

◆ Utf16Converter()

template<std::convertible_to< std::u8string_view > View>
xentara::utils::string::Utf16Converter ( View &&  ) -> Utf16Converter< typename std::u8string_view::const_iterator, typename std::u8string_view::const_iterator >

◆ utf16Size() [1/3]

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char8_t>
auto xentara::utils::string::utf16Size ( InputIterator  begin,
InputSentinel  end 
) -> std::size_t

Gets the size of a UTF-8 string when converted to to UTF-16.

This function determines how much space will be needed to convert a UTF-8 string to UTF-16 using toUtf16().

Parameters
beginThe beginning of the input sequence
endThe end of the input sequence
Returns
Returns the number of UTF-16 characters the conversion will generate

◆ utf16Size() [2/3]

auto xentara::utils::string::utf16Size ( std::string_view  string) -> std::size_t

Gets the size of a UTF-8 string when converted to to UTF-16.

This function determines how much space will be needed to convert a UTF-8 string to UTF-16 using toUtf16().

Parameters
stringThe input sequence
Returns
Returns the number of UTF-16 characters the conversion will generate

◆ utf16Size() [3/3]

auto xentara::utils::string::utf16Size ( std::u8string_view  string) -> std::size_t

Gets the size of a UTF-8 string when converted to to UTF-16.

This function determines how much space will be needed to convert a UTF-8 string to UTF-16 using toUtf16().

Parameters
stringThe input sequence
Returns
Returns the number of UTF-16 characters the conversion will generate

◆ utf8Size() [1/2]

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires std::convertible_to<std::iter_value_t<InputIterator>, char16_t>
auto xentara::utils::string::utf8Size ( InputIterator  begin,
InputSentinel  end 
) -> std::size_t

Gets the size of a UTF-16 string when converted to to UTF-8.

This function determines how much space will be needed to convert a UTF-16 string to UTF-8 using toUtf8().

Parameters
beginThe beginning of the input sequence
endThe end of the input sequence
Returns
Returns the number of UTF-8 characters the conversion will generate

◆ utf8Size() [2/2]

auto xentara::utils::string::utf8Size ( std::u16string_view  string) -> std::size_t

Gets the size of a UTF-16 string when converted to to UTF-8.

This function determines how much space will be needed to convert a UTF-16 string to UTF-8 using toUtf8().

Parameters
stringThe input sequence
Returns
Returns the number of UTF-8 characters the conversion will generate