String utilities. More...

Namespaces
namespace	deprecated

namespace	operators
	Inline namespace containg operators for special custom string types.

namespace	unicode

Classes
class	BasicFixedString
	A string with a fixed size. More...

class	BasicHashKey
	A string that enables heterogeneous lookup when used as a key for hash tables. More...

class	BasicStaticString
	A string that uses a statically allocated buffer for the data. More...

class	BasicStringView
	A string view that can be implicitly converted to std::basic_string. More...

class	Converter
	A convert that allows conversion from one string type to another. More...

struct	FillTag
	Type used to autzomatically select the correct size in constructors of BasicFixedString that normally take a size. More...

struct	IsNoopConversion
	Determines if a conversion between two string types is a NOOP. More...

struct	UninitializedTag
	Type used to select the constructor of BasicFixedString that leaves characters uninitialized. More...

class	view
	This is a wrapper class that supplies missing `operator + ()` for string views. More...

Concepts
concept	SpecialStringType
	A concept for determining whether a type is a special custom string type.

concept	CharacterType
	A concept for character data.

Typedefs
Specialized Fixed Strings
template<std::size_t kSize>
using	FixedString = BasicFixedString< char, kSize >
	A statically allocated string containing elements of type char

template<std::size_t kSize>
using	FixedWString = BasicFixedString< wchar_t, kSize >
	A statically allocated string containing elements of type wchar_t

template<std::size_t kSize>
using	FixedU8String = BasicFixedString< char8_t, kSize >
	A statically allocated string containing elements of type char8_t

template<std::size_t kSize>
using	FixedU16String = BasicFixedString< char16_t, kSize >
	A statically allocated string containing elements of type char16_t

template<std::size_t kSize>
using	FixedU32String = BasicFixedString< char32_t, kSize >
	A statically allocated string containing elements of type char32_t

Specialized Hash Keys
using	HashKey = BasicHashKey< char >
	A hash key with characters of type char

using	WHashKey = BasicHashKey< wchar_t >
	A hash key with characters of type wchar_t

using	U8HashKey = BasicHashKey< char8_t >
	A hash key with characters of type char8_t

using	U16HashKey = BasicHashKey< char16_t >
	A hash key with characters of type char16_t

using	U32HashKey = BasicHashKey< char32_t >
	A hash key with characters of type char32_t

Specialized Static Strings
template<std::size_t kCapacity>
using	StaticString = BasicStaticString< char, kCapacity >
	A statically allocated string containing elements of type char

template<std::size_t kCapacity>
using	StaticWString = BasicStaticString< wchar_t, kCapacity >
	A statically allocated string containing elements of type wchar_t

template<std::size_t kCapacity>
using	StaticU8String = BasicStaticString< char8_t, kCapacity >
	A statically allocated string containing elements of type char8_t

template<std::size_t kCapacity>
using	StaticU16String = BasicStaticString< char16_t, kCapacity >
	A statically allocated string containing elements of type char16_t

template<std::size_t kCapacity>
using	StaticU32String = BasicStaticString< char32_t, kCapacity >
	A statically allocated string containing elements of type char32_t

using	StringView = BasicStringView< char >
	A string view of type char that can be implicitly converted to std::basic_string.

using	WStringView = BasicStringView< wchar_t >
	A string view of type wchar_t that can be implicitly converted to std::basic_string.

using	U8StringView = BasicStringView< char8_t >
	A string view of type char8_t that can be implicitly converted to std::basic_string.

using	U16StringView = BasicStringView< char16_t >
	A string view of type char16_t that can be implicitly converted to std::basic_string.

using	U32StringView = BasicStringView< char32_t >
	A string view of type char32_t that can be implicitly converted to std::basic_string.

Functions
template<tools::StringViewable String, tools::CharType OutputCharT>
	Converter (String &&, std::in_place_type_t< OutputCharT >) -> Converter< OutputCharT, typename tools::StringViewableViewType< String >::const_iterator, typename tools::StringViewableViewType< String >::const_iterator >

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, tools::CharType OutputCharT>
	Converter (InputIterator, InputSentinel, std::in_place_type_t< OutputCharT >) -> Converter< OutputCharT, InputIterator, InputSentinel >

template<typename Char , typename Traits >
constexpr auto	fromStringView (const std::basic_string_view< Char, Traits > &view) -> std::basic_string< Char, Traits >
	Creates a string from a string view.

template<CharacterType Character>
constexpr auto	strlen (const Character *string) -> std::size_t
	Calculate the length of a string.

constexpr auto	strlen (std::nullptr_t) -> std::size_t
	Overload for xentara::utils::core::strlen() for literal null pointers.

Variables
constexpr UninitializedTag	kUninitialized
	A marker used to select constructor of BasicFixedString that leaves characters uninitialized.

constexpr FillTag	kFill
	A marker used to select constructor of BasicFixedString that leaves characters uninitialized.

Encoding Conversions
enum class	ConvertInvokeFallback { UseHeapAllocation , Truncate }
	Fallback behaviour for convertInvoke() More...

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::output_iterator< OutputChar > OutputIterator, std::sentinel_for< OutputIterator > OutputSentinel = std::unreachable_sentinel_t> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convert (InputIterator begin, InputSentinel end, OutputIterator output, OutputSentinel outputEnd=std::unreachable_sentinel) -> OutputIterator
	Converts a character sequence from one type to another.

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convert (InputIterator begin, InputSentinel end) -> std::basic_string< OutputChar >
	Converts a character sequence from one type to another.

template<tools::CharType OutputChar, typename CharTraits , std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convert (InputIterator begin, InputSentinel end) -> std::basic_string< OutputChar, CharTraits >
	Converts a character sequence from one type to another.

template<tools::CharType OutputChar, typename CharTraits , tools::Allocator< OutputChar > Allocator, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convert (InputIterator begin, InputSentinel end, const Allocator &allocator=Allocator()) -> std::basic_string< OutputChar, CharTraits, Allocator >
	Converts a character sequence from one type to another.

template<tools::CharType OutputChar, tools::StringViewable String>
auto	convert (String &&string) -> std::basic_string< OutputChar >
	Converts a string from one type to another.

template<tools::CharType OutputChar, typename CharTraits , tools::StringViewable String>
auto	convert (String &&string) -> std::basic_string< OutputChar, CharTraits >
	Converts a string from one type to another.

template<tools::CharType OutputChar, typename CharTraits , tools::Allocator< OutputChar > Allocator, tools::StringViewable String>
auto	convert (String &&string, const Allocator &allocator=Allocator()) -> std::basic_string< OutputChar, CharTraits, Allocator >
	Converts a string from one type to another.

template<tools::CharType OutputChar, tools::StringViewable String>
auto	convertOrView (const String &string) -> std::conditional_t< kIsNoopConversion< tools::StringViewableCharType< String >, OutputChar >, std::basic_string_view< OutputChar >, std::basic_string< OutputChar > >
	Converts a string from one type to another, returning a view if no conversion is necessary.

template<tools::CharType OutputChar, typename CharTraits , tools::StringViewable String>
auto	convertOrView (const String &string) -> std::conditional_t< kIsNoopConversion< tools::StringViewableCharType< String >, OutputChar >, std::basic_string_view< OutputChar, CharTraits >, std::basic_string< OutputChar, CharTraits > >
	Converts a string from one type to another, returning a view if no conversion is necessary.

template<tools::CharType OutputChar, typename CharTraits , tools::Allocator< OutputChar > Allocator, tools::StringViewable String>
auto	convertOrView (const String &string, const Allocator &allocator=Allocator()) -> std::conditional_t< kIsNoopConversion< tools::StringViewableCharType< String >, OutputChar >, std::basic_string_view< OutputChar, CharTraits >, std::basic_string< OutputChar, CharTraits, Allocator > >
	Converts a string from one type to another, returning a view if no conversion is necessary.

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convertedSize (InputIterator begin, InputSentinel end) -> std::size_t
	Gets the size of a converted character sequence.

template<tools::CharType OutputChar, tools::StringViewable String>
auto	convertedSize (const String &string) -> std::size_t
	Gets the size of a converted string view.

template<tools::CharType OutputChar, tools::CharType InputChar>
constexpr auto	maxConvertedSize (std::size_t inputSize) noexcept -> std::size_t
	Gets the maximum possible size of a converted string of a certain size.

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel> requires tools::CharType<std::iter_value_t<InputIterator>>
constexpr auto	maxConvertedSize (InputIterator begin, InputSentinel end) -> std::size_t
	Gets the maximum possible size of a converted character sequence.

template<tools::CharType OutputChar, tools::StringViewable String>
constexpr auto	maxConvertedSize (const String &string) -> std::size_t
	Gets the maximum possible size of a converted string.

template<tools::CharType OutputChar, std::contiguous_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::invocable< std::basic_string_view< OutputChar > > Callback> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convertInvoke (InputIterator begin, InputSentinel end, Callback &&callback, ConvertInvokeFallback fallbackStrategy=ConvertInvokeFallback::UseHeapAllocation) -> decltype(auto)
	Converts a character sequence from one type to another and calls a callback with the result.

template<tools::CharType OutputChar, typename CharTraits , std::contiguous_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::invocable< std::basic_string_view< OutputChar, CharTraits > > Callback> requires tools::CharType<std::iter_value_t<InputIterator>>
auto	convertInvoke (InputIterator begin, InputSentinel end, Callback &&callback, ConvertInvokeFallback fallbackStrategy=ConvertInvokeFallback::UseHeapAllocation) -> decltype(auto)
	Converts a character sequence from one type to another and calls a callback with the result.

template<tools::CharType OutputChar, tools::StringViewable String, std::invocable< std::basic_string_view< OutputChar > > Callback>
auto	convertInvoke (const String &string, Callback &&callback, ConvertInvokeFallback fallbackStrategy=ConvertInvokeFallback::UseHeapAllocation) -> decltype(auto)
	Converts a string from one type to another and calls a callback with the result.

template<tools::CharType OutputChar, typename CharTraits , tools::StringViewable String, std::invocable< std::basic_string_view< OutputChar, CharTraits > > Callback>
auto	convertInvoke (const String &string, Callback &&callback, ConvertInvokeFallback fallbackStrategy=ConvertInvokeFallback::UseHeapAllocation) -> decltype(auto)
	Converts a string from one type to another and calls a callback with the result.

template<tools::CharType OutputChar, tools::CharType InputChar>
constexpr auto	convertInvokeNeedsFallback (std::size_t size) -> bool
	Determines whether convertInvoke() needs to use the fallback mechanism.

template<tools::CharType OutputChar, std::contiguous_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel> requires tools::CharType<std::iter_value_t<InputIterator>>
constexpr auto	convertInvokeNeedsFallback (InputIterator begin, InputSentinel end) -> bool
	Determines whether convertInvoke() needs to use the fallback mechanism for a character sequence.

template<tools::CharType OutputChar, tools::StringViewable String>
constexpr auto	convertInvokeNeedsFallback (const String &string) -> bool
	Determines whether convertInvoke() needs to use the fallback mechanism for a string.

Detailed Description

String utilities.

This namespace contains string utilities.

Typedef Documentation

◆ FixedString

template<std::size_t kSize>

using xentara::utils::string::FixedString = typedef BasicFixedString<char, kSize>

A statically allocated string containing elements of type char

Include file: #include <xentara/utils/string/FixedString.hpp>

Template Parameters

kSize The capacity of the string

◆ FixedU16String

template<std::size_t kSize>

using xentara::utils::string::FixedU16String = typedef BasicFixedString<char16_t, kSize>

A statically allocated string containing elements of type char16_t

Include file: #include <xentara/utils/string/FixedString.hpp>

Template Parameters

kSize The capacity of the string

◆ FixedU32String

template<std::size_t kSize>

using xentara::utils::string::FixedU32String = typedef BasicFixedString<char32_t, kSize>

A statically allocated string containing elements of type char32_t

Include file: #include <xentara/utils/string/FixedString.hpp>

Template Parameters

kSize The capacity of the string

◆ FixedU8String

template<std::size_t kSize>

using xentara::utils::string::FixedU8String = typedef BasicFixedString<char8_t, kSize>

A statically allocated string containing elements of type char8_t

Include file: #include <xentara/utils/string/FixedString.hpp>

Template Parameters

kSize The capacity of the string

◆ FixedWString

template<std::size_t kSize>

using xentara::utils::string::FixedWString = typedef BasicFixedString<wchar_t, kSize>

A statically allocated string containing elements of type wchar_t

Include file: #include <xentara/utils/string/FixedString.hpp>

Template Parameters

kSize The capacity of the string

◆ HashKey

using xentara::utils::string::HashKey = typedef BasicHashKey<char>

A hash key with characters of type char

Include file: #include <xentara/utils/string/HashKey.hpp>

◆ StaticString

template<std::size_t kCapacity>

using xentara::utils::string::StaticString = typedef BasicStaticString<char, kCapacity>

A statically allocated string containing elements of type char

Include file: #include <xentara/utils/string/StaticString.hpp>

Template Parameters

kCapacity The capacity of the string

◆ StaticU16String

template<std::size_t kCapacity>

using xentara::utils::string::StaticU16String = typedef BasicStaticString<char16_t, kCapacity>

A statically allocated string containing elements of type char16_t

Include file: #include <xentara/utils/string/StaticString.hpp>

Template Parameters

kCapacity The capacity of the string

◆ StaticU32String

template<std::size_t kCapacity>

using xentara::utils::string::StaticU32String = typedef BasicStaticString<char32_t, kCapacity>

A statically allocated string containing elements of type char32_t

Include file: #include <xentara/utils/string/StaticString.hpp>

Template Parameters

kCapacity The capacity of the string

◆ StaticU8String

template<std::size_t kCapacity>

using xentara::utils::string::StaticU8String = typedef BasicStaticString<char8_t, kCapacity>

A statically allocated string containing elements of type char8_t

Include file: #include <xentara/utils/string/StaticString.hpp>

Template Parameters

kCapacity The capacity of the string

◆ StaticWString

template<std::size_t kCapacity>

using xentara::utils::string::StaticWString = typedef BasicStaticString<wchar_t, kCapacity>

A statically allocated string containing elements of type wchar_t

Include file: #include <xentara/utils/string/StaticString.hpp>

Template Parameters

kCapacity The capacity of the string

◆ StringView

using xentara::utils::string::StringView = typedef BasicStringView<char>

A string view of type char that can be implicitly converted to std::basic_string.

Include file: #include <xentara/utils/string/StringView.hpp>

◆ U16HashKey

using xentara::utils::string::U16HashKey = typedef BasicHashKey<char16_t>

A hash key with characters of type char16_t

Include file: #include <xentara/utils/string/HashKey.hpp>

◆ U16StringView

using xentara::utils::string::U16StringView = typedef BasicStringView<char16_t>

A string view of type char16_t that can be implicitly converted to std::basic_string.

Include file: #include <xentara/utils/string/StringView.hpp>

◆ U32HashKey

using xentara::utils::string::U32HashKey = typedef BasicHashKey<char32_t>

A hash key with characters of type char32_t

Include file: #include <xentara/utils/string/HashKey.hpp>

◆ U32StringView

using xentara::utils::string::U32StringView = typedef BasicStringView<char32_t>

A string view of type char32_t that can be implicitly converted to std::basic_string.

Include file: #include <xentara/utils/string/StringView.hpp>

◆ U8HashKey

using xentara::utils::string::U8HashKey = typedef BasicHashKey<char8_t>

A hash key with characters of type char8_t

Include file: #include <xentara/utils/string/HashKey.hpp>

◆ U8StringView

using xentara::utils::string::U8StringView = typedef BasicStringView<char8_t>

A string view of type char8_t that can be implicitly converted to std::basic_string.

Include file: #include <xentara/utils/string/StringView.hpp>

◆ WHashKey

using xentara::utils::string::WHashKey = typedef BasicHashKey<wchar_t>

A hash key with characters of type wchar_t

Include file: #include <xentara/utils/string/HashKey.hpp>

◆ WStringView

using xentara::utils::string::WStringView = typedef BasicStringView<wchar_t>

A string view of type wchar_t that can be implicitly converted to std::basic_string.

Include file: #include <xentara/utils/string/StringView.hpp>

Enumeration Type Documentation

◆ ConvertInvokeFallback

enum class xentara::utils::string::ConvertInvokeFallback

strong

Fallback behaviour for convertInvoke()

This enum allows you to specify how convertInvoke() should behave if the string is too large to be converted using a stack-allocated buffer.

Enumerator
UseHeapAllocation	Use heap allocation to allocate the buffer.
Truncate	Truncate the string.

Function Documentation

◆ convert() [1/7]

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convert	(	InputIterator	begin,
		InputSentinel	end
	)		-> std::basic_string<OutputChar>

Converts a character sequence from one type to another.

This function converts a character sequence from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

Note: If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar The character type to use for the returned string

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence

Returns: Returns the output sequence as a string

◆ convert() [2/7]

template<tools::CharType OutputChar, typename CharTraits , std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convert	(	InputIterator	begin,
		InputSentinel	end
	)		-> std::basic_string<OutputChar, CharTraits>

Converts a character sequence from one type to another.

This function converts a character sequence from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

Note: If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the returned string
CharTraits	The character traits to be used for the returned string

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence

Returns: Returns the output sequence as a string

◆ convert() [3/7]

template<tools::CharType OutputChar, typename CharTraits , tools::Allocator< OutputChar > Allocator, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convert	(	InputIterator	begin,
		InputSentinel	end,
		const Allocator &	allocator = `Allocator()`
	)		-> std::basic_string<OutputChar, CharTraits, Allocator>

Converts a character sequence from one type to another.

This function converts a character sequence from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

Note: If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the returned string
CharTraits	The character traits to be used for the returned string
Allocator	The allocator type to be used for the returned string

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence
allocator	The allocator to be used for the returned string

Returns: Returns the output sequence as a string

◆ convert() [4/7]

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::output_iterator< OutputChar > OutputIterator, std::sentinel_for< OutputIterator > OutputSentinel = std::unreachable_sentinel_t>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convert	(	InputIterator	begin,
		InputSentinel	end,
		OutputIterator	output,
		OutputSentinel	outputEnd = `std::unreachable_sentinel`
	)		-> OutputIterator

Converts a character sequence from one type to another.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

If the converted string does not fit into the output sequence, then it is silently truncated. If you need to know whether the sequence was truncated or not, you must use a Converter object instead of this function.

Note: If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence
output	An output iterator for the output sequence
outputEnd	A 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

◆ convert() [5/7]

template<tools::CharType OutputChar, tools::StringViewable String>

auto xentara::utils::string::convert ( String && string ) -> std::basic_string<OutputChar>

Converts a string from one type to another.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

Note: If you pass a std::basic_string<OutputChar> && "std::basic_string" to this function, if will simply move the input string to the output string. This allows you to efficiently use this function in templates, where the input and output types may be the same.; If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar The character type to use for the returned string

Parameters

string The string to convert

Returns: Returns the output sequence as a string

◆ convert() [6/7]

template<tools::CharType OutputChar, typename CharTraits , tools::StringViewable String>

auto xentara::utils::string::convert ( String && string ) -> std::basic_string<OutputChar, CharTraits>

Converts a string from one type to another.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

Note: If you pass a std::basic_string<OutputChar> && "std::basic_string" to this function, if will simply move the input string to the output string. This allows you to efficiently use this function in templates, where the input and output types may be the same.; If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the returned string
CharTraits	The character traits to be used for the returned string

Parameters

string The string to convert

Returns: Returns the output sequence as a string

◆ convert() [7/7]

template<tools::CharType OutputChar, typename CharTraits , tools::Allocator< OutputChar > Allocator, tools::StringViewable String>

auto xentara::utils::string::convert	(	String &&	string,
		const Allocator &	allocator = `Allocator()`
	)		-> std::basic_string<OutputChar, CharTraits, Allocator>

Converts a string from one type to another.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

Note: If you pass a std::basic_string<OutputChar> && "std::basic_string" to this function, if will simply move the input string to the output string. This allows you to efficiently use this function in templates, where the input and output types may be the same.; If the input and output types have the same encoding, the data is copied as-is, without checking the validity. This means you cannot use this function to correct corrupt Unicode data.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the returned string
CharTraits	The character traits to be used for the returned string
Allocator	The allocator type to be used for the returned string

Parameters

string	The string to convert
allocator	The allocator to be used for the returned string

Returns: Returns the output sequence as a string

◆ convertedSize() [1/2]

template<tools::CharType OutputChar, tools::StringViewable String>

auto xentara::utils::string::convertedSize ( const String & string ) -> std::size_t

Gets the size of a converted string view.

This function determines how much space will be needed to convert a string using convert().

Include file: #include <xentara/utils/string/convert.hpp>

Parameters

string The string to convert

Returns: Returns the number of code units the conversion will generate

◆ convertedSize() [2/2]

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convertedSize	(	InputIterator	begin,
		InputSentinel	end
	)		-> std::size_t

Gets the size of a converted character sequence.

This function determines how much space will be needed to convert a character sequence using convert().

Include file: #include <xentara/utils/string/convert.hpp>

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence

Returns: Returns the number of code units the conversion will generate

◆ Converter() [1/2]

template<std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, tools::CharType OutputCharT>

xentara::utils::string::Converter	(	InputIterator	,
		InputSentinel	,
		std::in_place_type_t< OutputCharT >
	)		-> Converter< OutputCharT, InputIterator, InputSentinel >

◆ Converter() [2/2]

template<tools::StringViewable String, tools::CharType OutputCharT>

xentara::utils::string::Converter	(	String &&	,
		std::in_place_type_t< OutputCharT >
	)		-> Converter< OutputCharT, typename tools::StringViewableViewType< String >::const_iterator, typename tools::StringViewableViewType< String >::const_iterator >

◆ convertInvoke() [1/4]

template<tools::CharType OutputChar, typename CharTraits , tools::StringViewable String, std::invocable< std::basic_string_view< OutputChar, CharTraits > > Callback>

auto xentara::utils::string::convertInvoke	(	const String &	string,
		Callback &&	callback,
		ConvertInvokeFallback	fallbackStrategy = `ConvertInvokeFallback::UseHeapAllocation`
	)		-> decltype(auto)

Converts a string from one type to another and calls a callback with the result.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

This function uses a statically allocated buffer for any conversions that may be necessary, thus eliminating the need for heap allocations.

To avoid stack overflow, this function limits the buffer size necessary for the conversion to 64 kB. If the string is too long to convert, the specified fallback strategy will be used. This can be either:

Fall back to heap allocation, or
Truncate the string.
Include file
#include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the converted string
CharTraits	The character traits to be used for the converted string

Parameters

string	The string to convert
callback	The callback to call
fallbackStrategy	The fallback strategy to use if the string is too long to be safely converted on the stack.

Returns: Returns the return value of the handler

◆ convertInvoke() [2/4]

template<tools::CharType OutputChar, tools::StringViewable String, std::invocable< std::basic_string_view< OutputChar > > Callback>

auto xentara::utils::string::convertInvoke	(	const String &	string,
		Callback &&	callback,
		ConvertInvokeFallback	fallbackStrategy = `ConvertInvokeFallback::UseHeapAllocation`
	)		-> decltype(auto)

Converts a string from one type to another and calls a callback with the result.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

This function uses a statically allocated buffer for any conversions that may be necessary, thus eliminating the need for heap allocations.

To avoid stack overflow, this function limits the buffer size necessary for the conversion to 64 kB. If the string is too long to convert, the specified fallback strategy will be used. This can be either:

Fall back to heap allocation, or
Truncate the string.
Include file
#include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar The character type to use for the converted string

Parameters

string	The string to convert
callback	The callback to call
fallbackStrategy	The fallback strategy to use if the string is too long to be safely converted on the stack.

Returns: Returns the return value of the handler

◆ convertInvoke() [3/4]

template<tools::CharType OutputChar, typename CharTraits , std::contiguous_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::invocable< std::basic_string_view< OutputChar, CharTraits > > Callback>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convertInvoke	(	InputIterator	begin,
		InputSentinel	end,
		Callback &&	callback,
		ConvertInvokeFallback	fallbackStrategy = `ConvertInvokeFallback::UseHeapAllocation`
	)		-> decltype(auto)

Converts a character sequence from one type to another and calls a callback with the result.

This function converts a character sequence from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

This function uses a statically allocated buffer for any conversions that may be necessary, thus eliminating the need for heap allocations.

To avoid stack overflow, this function limits the buffer size necessary for the conversion to 64 kB. If the character sequence is too long to convert, the specified fallback strategy will be used. This can be either:

Fall back to heap allocation, or
Truncate the string.
Include file
#include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the converted string
CharTraits	The character traits to be used for the converted string

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence
callback	The callback to call
fallbackStrategy	The fallback strategy to use if the character sequence is too long to be safely converted on the stack.

Returns: Returns the return value of the handler

◆ convertInvoke() [4/4]

template<tools::CharType OutputChar, std::contiguous_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel, std::invocable< std::basic_string_view< OutputChar > > Callback>
requires tools::CharType<std::iter_value_t<InputIterator>>

auto xentara::utils::string::convertInvoke	(	InputIterator	begin,
		InputSentinel	end,
		Callback &&	callback,
		ConvertInvokeFallback	fallbackStrategy = `ConvertInvokeFallback::UseHeapAllocation`
	)		-> decltype(auto)

Converts a character sequence from one type to another and calls a callback with the result.

This function converts a character sequence from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

This function uses a statically allocated buffer for any conversions that may be necessary, thus eliminating the need for heap allocations.

To avoid stack overflow, this function limits the buffer size necessary for the conversion to 64 kB. If the character sequence is too long to convert, the specified fallback strategy will be used. This can be either:

Fall back to heap allocation, or
Truncate the string.
Include file
#include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar The character type to use for the converted string

Parameters

begin	The beginning of the input sequence
end	The end of the input sequence
callback	The callback to call
fallbackStrategy	The fallback strategy to use if the character sequence is too long to be safely converted on the stack.

Returns: Returns the return value of the handler

◆ convertInvokeNeedsFallback() [1/3]

template<tools::CharType OutputChar, tools::StringViewable String>

constexpr auto xentara::utils::string::convertInvokeNeedsFallback ( const String & string ) -> bool

constexpr

Determines whether convertInvoke() needs to use the fallback mechanism for a string.

To avoid stack overflow, convertInvoke() limits the stack allocated buffer size necessary for the conversion to 64 kB. If the string is too long to convert, a fallback strategy will be used. This function can be used to determine whether the fallback strategy will be needed for a specific string.

Parameters

string The string that will be converted

Returns: Returns true if convertInvoke() will need to use the specified fallback strategy, or false if the conversion can go ahead without using the fallback.

◆ convertInvokeNeedsFallback() [2/3]

template<tools::CharType OutputChar, std::contiguous_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires tools::CharType<std::iter_value_t<InputIterator>>

constexpr auto xentara::utils::string::convertInvokeNeedsFallback	(	InputIterator	begin,
		InputSentinel	end
	)		-> bool

constexpr

Determines whether convertInvoke() needs to use the fallback mechanism for a character sequence.

To avoid stack overflow, convertInvoke() limits the stack allocated buffer size necessary for the conversion to 64 kB. If the string is too long to convert, a fallback strategy will be used. This function can be used to determine whether the fallback strategy will be needed for a specific character sequence.

Parameters

begin	The beginning of the input sequence that will be converted
end	The end of the input sequence that will be converted

Returns: Returns true if convertInvoke() will need to use the specified fallback strategy, or false if the conversion can go ahead without using the fallback.

◆ convertInvokeNeedsFallback() [3/3]

template<tools::CharType OutputChar, tools::CharType InputChar>

constexpr auto xentara::utils::string::convertInvokeNeedsFallback ( std::size_t size ) -> bool

constexpr

Determines whether convertInvoke() needs to use the fallback mechanism.

To avoid stack overflow, convertInvoke() limits the stack allocated buffer size necessary for the conversion to 64 kB. If the string is too long to convert, a fallback strategy will be used. This function can be used to determine whether the fallback strategy will be needed for a specific string size.

Parameters

size	The size of the string that will be converted

Returns: Returns true if convertInvoke() will need to use the specified fallback strategy, or false if the conversion can go ahead without using the fallback.

◆ convertOrView() [1/3]

template<tools::CharType OutputChar, tools::StringViewable String>

auto xentara::utils::string::convertOrView ( const String & string ) -> std::conditional_t< kIsNoopConversion<tools::StringViewableCharType<String>, OutputChar>, std::basic_string_view<OutputChar>, std::basic_string<OutputChar>>

Converts a string from one type to another, returning a view if no conversion is necessary.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

In contrast to convert(), this function will only return a string, if a conversion needs to be done. If the encoding of the input type and the output type are the same, an std::basic_string_view referencing the data of the input string will be returned instead. This allows you to efficiently use this function in templates, where you want to avoid copying the data if possible.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar The character type to use for the returned string

Parameters

string The string to convert

Returns: Returns the output sequence as a string, or a view of the data of the input sequence if the encodings are the same.

◆ convertOrView() [2/3]

template<tools::CharType OutputChar, typename CharTraits , tools::StringViewable String>

auto xentara::utils::string::convertOrView ( const String & string ) -> std::conditional_t< kIsNoopConversion<tools::StringViewableCharType<String>, OutputChar>, std::basic_string_view<OutputChar, CharTraits>, std::basic_string<OutputChar, CharTraits>>

Converts a string from one type to another, returning a view if no conversion is necessary.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

In contrast to convert(), this function will only return a string, if a conversion needs to be done. If the encoding of the input type and the output type are the same, an std::basic_string_view referencing the data of the input string will be returned instead. This allows you to efficiently use this function in templates, where you want to avoid copying the data if possible.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the returned string
CharTraits	The character traits to be used for the returned string

Parameters

string The string to convert

Returns: Returns the output sequence as a string, or a view of the data of the input sequence if the encodings are the same.

◆ convertOrView() [3/3]

template<tools::CharType OutputChar, typename CharTraits , tools::Allocator< OutputChar > Allocator, tools::StringViewable String>

auto xentara::utils::string::convertOrView	(	const String &	string,
		const Allocator &	allocator = `Allocator()`
	)		-> std::conditional_t< kIsNoopConversion<tools::StringViewableCharType<String>, OutputChar>, std::basic_string_view<OutputChar, CharTraits>, std::basic_string<OutputChar, CharTraits, Allocator>>

Converts a string from one type to another, returning a view if no conversion is necessary.

This function converts a string from one Unicode encoding to another. Illegal code points (high and low surrogates, and code points higher than U+10FFFF) and non-decodable input values are replaced by the replacement character.

In contrast to convert(), this function will only return a string, if a conversion needs to be done. If the encoding of the input type and the output type are the same, an std::basic_string_view referencing the data of the input string will be returned instead. This allows you to efficiently use this function in templates, where you want to avoid copying the data if possible.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The character type to use for the returned string
CharTraits	The character traits to be used for the returned string
Allocator	The allocator type to be used for the returned string

Parameters

string	The string to convert
allocator	The allocator to be used for the returned string

Returns: Returns the output sequence as a string, or a view of the data of the input sequence if the encodings are the same.

◆ 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

Creates a string from a string view.

◆ maxConvertedSize() [1/3]

template<tools::CharType OutputChar, tools::StringViewable String>

constexpr auto xentara::utils::string::maxConvertedSize ( const String & string ) -> std::size_t

constexpr

Gets the maximum possible size of a converted string.

This function determines the maximum length that a string can ever have when converted to a different character using convert().

This function is faster that convertedSize(), because it only uses the string’s size and does not check the actual characters.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The char type used by the output string
InputChar	The char type used by the input string

Parameters

string The string that will be converted

◆ maxConvertedSize() [2/3]

template<tools::CharType OutputChar, std::input_iterator InputIterator, std::sentinel_for< InputIterator > InputSentinel>
requires tools::CharType<std::iter_value_t<InputIterator>>

constexpr auto xentara::utils::string::maxConvertedSize	(	InputIterator	begin,
		InputSentinel	end
	)		-> std::size_t

constexpr

Gets the maximum possible size of a converted character sequence.

This function determines the maximum length that a character sequence can ever have when converted to a different character using convert().

This function is faster that convertedSize(), because it only uses the input sequence’s size and does not check the actual characters.

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The char type used by the output string
InputChar	The char type used by the input string

Parameters

begin	The beginning of the input sequence that will be converted
end	The end of the input sequence that will be converted

◆ maxConvertedSize() [3/3]

template<tools::CharType OutputChar, tools::CharType InputChar>

constexpr auto xentara::utils::string::maxConvertedSize ( std::size_t inputSize ) -> std::size_t

constexprnoexcept

Gets the maximum possible size of a converted string of a certain size.

This function determines the maximum length that a string of type InputChar and size inputSize can ever have when converted to a different character type using convert().

Include file: #include <xentara/utils/string/convert.hpp>

Template Parameters

OutputChar	The char type used by the output string
InputChar	The char type used by the input string

Parameters

inputSize The size of the input string

◆ 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

string The 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

Variable Documentation

◆ kFill

constexpr FillTag xentara::utils::string::kFill

constexpr

A marker used to select constructor of BasicFixedString that leaves characters uninitialized.

See also: BasicFixedString

◆ kUninitialized

constexpr UninitializedTag xentara::utils::string::kUninitialized

constexpr

A marker used to select constructor of BasicFixedString that leaves characters uninitialized.

See also: BasicFixedString

Namespaces

Classes

Concepts

Typedefs

Functions

Variables

Encoding Conversions

Detailed Description

Typedef Documentation

◆ FixedString

◆ FixedU16String

◆ FixedU32String

◆ FixedU8String

◆ FixedWString

◆ HashKey

◆ StaticString

◆ StaticU16String

◆ StaticU32String

◆ StaticU8String

◆ StaticWString

◆ StringView

◆ U16HashKey

◆ U16StringView

◆ U32HashKey

◆ U32StringView

◆ U8HashKey

◆ U8StringView

◆ WHashKey

◆ WStringView

Enumeration Type Documentation

◆ ConvertInvokeFallback

Function Documentation

◆ convert() [1/7]

◆ convert() [2/7]

◆ convert() [3/7]

◆ convert() [4/7]

◆ convert() [5/7]

◆ convert() [6/7]

◆ convert() [7/7]

◆ convertedSize() [1/2]

◆ convertedSize() [2/2]

◆ Converter() [1/2]

◆ Converter() [2/2]

◆ convertInvoke() [1/4]

◆ convertInvoke() [2/4]

◆ convertInvoke() [3/4]

◆ convertInvoke() [4/4]

◆ convertInvokeNeedsFallback() [1/3]

◆ convertInvokeNeedsFallback() [2/3]

◆ convertInvokeNeedsFallback() [3/3]

◆ convertOrView() [1/3]

◆ convertOrView() [2/3]

◆ convertOrView() [3/3]

◆ fromStringView()

◆ maxConvertedSize() [1/3]

◆ maxConvertedSize() [2/3]

◆ maxConvertedSize() [3/3]

◆ strlen() [1/2]

◆ strlen() [2/2]

Variable Documentation

◆ kFill

◆ kUninitialized