u8_decode_string() [2/8]

std::basic_string<ucp_t, CharTraitsTo, ReboundAllocator> Chusov::String::u8_decode_string

(

const BasicStringType &

str

)

Produces a C++ string of Unicode 11.0 code points from a C++ UTF-8 encoded string with a custom char-traits class. .

Template Parameters

CharTraitsTo	specifies a CharTraits type used to instantiate the std::basic_string template in order to produce the output string. The std::char_traits<Chusov::String::ucp_t> specialization is provided by the chsvlib library.
BasicStringType	is an instantiation of the std::basic_string or (C++17) std::basic_string_view standard templates for the type char.

Parameters

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

Returns

A newly created string, an instantiation of std::basic_string, with Unicode 11.0 code points as its elements along with the specified CharTraits policy. If the BasicStringType is an instantiation of std::basic_string, the type of allocator used by the returned string is default-constructed allocator of the type

typename std::allocator_traits<typename BasicStringType::allocator_type>::template rebind_alloc<Chusov::String::ucp_t>

. If the used standard library implements std::basic_string_view and latter is the type of BasicStringType, then the used allocator is

std::allocator<Chusov::String::ucp_t>

. Other overloads of u8_decode_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 decode 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, ucp_t>::value

must be true.

Exceptions

Chusov::Exceptions::InvalidCharSequenceException

The specified UTF-8 string is detected to contain an invalid or incomplete multi-byte UTF-8 character.

See also

u8_decode_string Another overload which allows specification of both the traits policy and the type of the allocator used by the returned string.
u8_decode_string An overload which requires specification of a type of a default-constructible allocator to be used by the returned string but also allows omission of the CharTraitsTo parameter and uses the CharTraits policy class of str respecialized for Chusov::String::ucp_t.
u8_decode_string An overload which uses rebound specializations of both traits and allocator templates of str.