u8_encode_string() [3/8]

std::basic_string<char, ReboundCharTraits, 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 a custom allocator. .

Template Parameters

AllocatorTo	is an Allocator object to instantiate the std::basic_string to produce the type of the resulting string. The allocator is default-constructed.
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 Allocator and a CharTraits policy obtained from respecializing the

typename BasicStringType::traits_type

type for char. Other overloads of u8_encode_string (see below) allow omission of AllocatorTo specification or adding specification of a CharTraits policy 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 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 specification of both the traits policy and the type of the allocator used by the returned string.
u8_encode_string Another overload which allows omission of the AllocatorTo specification and uses an allocator obtained from rebinding an allocator of the input string str, although explicit specification of the CharTraits policy is required.
u8_encode_string An overload which uses rebound specializations of both traits and allocator templates of str.