read_u8_char_data() [3/3]

constexpr u8_ch_data Chusov::String::read_u8_char_data ( InputIteratorBegin  begin, InputIteratorEnd  end  )

constexpr

Reads a UTF-8 character addressed by a pair of input iterators and returns a u8_ch_data object with information about it. .

Template Parameters

throw_on_failure	A boolean flag which specifies whether the function should throw an exception when the multi-byte value addressed by itSymbol specifies an invalid or incomplete UTF-8 character. If the flag is false, the function is marked noexcept and returns a default-constructed u8_ch_data object in case of an invalid/incomplete UTF-8 character. The default value is true.
InputIteratorBegin	is a deducible parameter which is a type of the iterator begin to read the character from.
InputIteratorEnd	is the type of end.

Parameters

begin	is an iterator referencing the multi-byte character to read. The iterator must meet the InputIterator requirements and its elements must be of the char type.
end	limits a number of bytes to read, i.e. read is performed from begin until the either the full UTF-8 character is read or begin reaches end. In the latter case, including the case when an input value of begin is equivalent to end, the function fails with respect to throw_on_failure as if an invalid UTF-8 code has been encountered.

Returns

An object of type u8_ch_data. On success it describes a Unicode 11.0 code point of the multi-byte character having been read and its byte length. On failure, the function either throws an exception or returns a default-constructed u8_ch_data depending on the value of throw_on_failure.

When throw_on_failure is false, and relevant operations upon InputIteratorBegin and InputIteratorEnd are marked noexcept, the function is also marked noexcept.

The function is constexpr when compiled by a C++14 compiler..

Exceptions

Chusov::Exceptions::InvalidCharSequenceException

The multi-byte character given by the parameters is not a valid or complete UTF-8 code. The exception is only thrown when throw_on_failure is true.

See also

read_u8_char_data An overload in which the maximum amount pf bytes to read is specified by an optional integral value.
read_u8_char_data_and_advance Similarly reads the character and returns the advanced copy of begin.