read_u8_char_data_and_advance() [1/2]

constexpr std::pair<u8_ch_data, InputIterator> Chusov::String::read_u8_char_data_and_advance ( InputIterator  itSymbol, std::size_t  cbSymbol = UTF8_MAX_LEN  )

constexpr

Reads a UTF-8 character addressed by an input iterator, advances it and returns a pair of a u8_ch_data object with information about the character together with the copy of the iterator after the reading. .

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 in case of failure returns a default-constructed u8_ch_data object. 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 std::pair object with its first element, of the u8_ch_data type, to contain information about the code which has been read, and the second element to be a copy of itSymbol advanced by the number of bytes occupied by the input code. In case of failure, when throw_on_failure is false, the returned pair contains a default-constructed u8_ch_data object and a copy of itSymbol in a state corresponding to an input byte which caused the failure. If throw_on_failure is true, the function either succeeds or throws an exception.

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 A more simple interface which only returns u8_ch_data representation about the UTF-8 character it has read from a given iterator.