read_u8_char_data_and_advance() [2/2]

constexpr std::pair<u8_ch_data, InputIterator> Chusov::String::read_u8_char_data_and_advance ( InputIteratorBegin  begin, InputIteratorEnd  end  )

constexpr

Reads a UTF-8 character addressed by a pair of input iterators, advances the first one and returns a pair of a u8_ch_data object with information about the character together with the copy of the iterator advances as a result of 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 begin specifies an invalid or incomplete UTF-8 character. If the flag is false and in case of failure the function returns a default-constructed u8_ch_data object. The default value is true.
InputIteratorBegin	is a deducible parameter of the first iterator begin ro 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	specifies the upper bound and corresponds to a pseudo byte right after the range of bytes accessable by the function.

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