u8_encode_string() [2/8]

std::basic_string<char, CharTraitsTo, ReboundAllocator> Chusov::String::u8_encode_string

(

const BasicStringType &

str

)

Converts a given C++ string of Unicode code points to the corresponding UTF-8 representation as another C++ string object with a custom char-traits policy. .

Template Parameters

CharTraitsTo	is a CharTraits object used to instantiate the std::basic_string template and create the output string.
BasicStringType	is an instantiation of the std::basic_string or (C++17) std::basic_string_view standard templates for the type Chusov::String::ucp_t.

Parameters

str	is a std::basic_string or (C++17) std::basic_string_view string object specialized for the Chusov::String::ucp_t characters.

Returns

A newly created string, an instantiation of std::basic_string, holding a multibyte UTF-8 representation of str with the specified CharTraits and an Allocator obtained from a default construction of the type, which, if BasicStringType is std::basic_string, is

typename std::allocator_traits<typename BasicStringType::allocator_type>::template rebind_alloc<char>

, or, if BasicStringType is std::basic_string_view, is

std::allocator<char>

. Other overloads of u8_encode_string (see below) allow omission of CharTraitsTo specification or adding specification of an allocator object to be used by the returned string.

Note

This overload does not participate in the overload resolution unless BasicStringType is an std::basic_string or (C++17) std::basic_string_view object with the traits_type subtype be a template of one type argument. Use another template to encode a string stored within an arbitrary C++ Container.

Also, for this overload to participate in the overload resolution

std::is_same<typename CharTraitsTo::char_type, char>::value

must be true.

Exceptions

Chusov::Exceptions::InvalidCharSequenceException

The specified Unicode string is detected to contain an invalid Chusov::String::ucp_t code point.

See also

ucp_string An alias for the standard std::basic_string template with the standard std::char_traits and std::allocator but specialized for Chusov::String::ucp_t.
u8_encode_string Another overload which allows specification of both the traits policy and the type of the allocator used by the returned string.
u8_encode_string An overload which requires AllocatorTo but also allows omission of the CharTraitsTo parameter and uses a CharTraits policy of str respecialized for char.
u8_encode_string An overload which uses rebound specializations of both traits and allocator templates of str.