read_u8_char_data() [2/3]

CONSTEXPR_CPP14 u8_ch_data Chusov::String::read_u8_char_data	(	InputIterator	itSymbol,
		std::size_t	cbSymbol = UTF8_MAX_LEN
	)

Reads a UTF-8 character addressed by an input iterator 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.
InputIterator	is a deducible parameter which is a type of itSymbol.

Parameters

itSymbol	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.
cbSymbol	is a maximum number of bytes addressed by itSymbol to inspect in order to obtain one complete UTF-8 character. The default value is UTF8_MAX_LEN.

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 iterator range \(\left.\left[\textrm{begin}, \textrm{end}\right.\right)\).
read_u8_char_data_and_advance Similarly reads the character and also returns the advanced copy of itSymbol.