u8_encode_string() [1/8]

std::basic_string<char, CharTraitsTo, AllocatorTo> 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 custom char-traits policy and an allocator. .

Template Parameters

CharTraitsTo	is a CharTraits object used to instantiate the std::basic_string template and create the output string.
AllocatorTo	is an Allocator object to instantiate the std::basic_string to produce the type of the resulting 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 Allocator. Other overloads of u8_encode_string (see below) allow omitting the specification of CharTraitsTo and AllocatorTo and use the traits and allocator templates of BasicStringType respecialized for char.

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 both

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

and

std::is_same<typename std::allocator_traits<AllocatorTo>::allocator_type, AllocatorTo>::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 omission of the AllocatorTo specification and use an allocator obtained from rebinding of an allocator of the input string str.
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.