recode_view & recode_iterator

The recode_view class provides a one-by-one view of the stored range’s code units as another encoding’s code units. Dereferencing the iterators returns a single code_unit value corresponding to the desired encoding’s type.

The range-based classes are excellent ways to walk over units of information in a low-memory environment, as they only store the minimum amount of data necessary to perform their operations on the fly. This reduces the speed but is fine for one-at-a-time encoding operations. To decode eagerly and in bulk, see the recode functions. The paired recode_iterator class does the bulk of the work and stores all of the information. It is paired with an empty, blank sentinel value so as to decrease the cost of iteration.

template<typename _FromEncoding, typename _ToEncoding = utf8_t, typename _Range = __txt_detail::__default_char_view_t<code_unit_t<_FromEncoding>>, typename _FromErrorHandler = default_handler_t, typename _ToErrorHandler = default_handler_t, typename _FromState = decode_state_t<_FromEncoding>, typename _ToState = encode_state_t<_ToEncoding>>
class recode_view : public view_base

A recoding iterator that takes an input of code units and provides an output over the code units of the desired _ToEncoding after converting from the _FromEncoding in a fashion that will never produce a ztd::text::encoding_error::insufficient_output error.

Remark

This type produces proxies as their reference type, and are only readable, not writable iterators. The type will also try many different shortcuts for decoding the input and encoding the intermediates, respectively, including invoking a few customization points for either decode_one. or encode_one . It may also call recode_one to bypass having to do the round-trip through two encodings, which an encoding pair that a developer is interested in can use to do the conversion more quickly. The view presents code units one at a time, regardless of how many code units are output by one decode operation. This means if, for example, one (1) UTF-16 code unit becomes two (2) UTF-8 code units, it will present each code unit one at a time. If you are looking to explicitly know each collection of characters, you will have to use lower-level interfaces.

Template Parameters:
  • _FromEncoding – The encoding to read the underlying range of code points as.

  • _ToEncoding – The encoding to read the underlying range of code points as.

  • _Range – The range of input that will be fed into the _FromEncoding’s decode operation.

  • _FromErrorHandler – The error handler for any decode-step failures.

  • _ToErrorHandler – The error handler for any encode-step failures.

  • _FromState – The state type to use for the decode operations to intermediate code points.

  • _ToState – The state type to use for the encode operations to intermediate code points.

Public Types

using iterator = recode_iterator<_FromEncoding, _ToEncoding, _Range, _FromErrorHandler, _ToErrorHandler, _FromState, _ToState>

The iterator type for this view.

using sentinel = recode_sentinel_t

The sentinel type for this view.

using range_type = _Range

The underlying range type.

using from_encoding_type = _FromEncoding

The encoding type used for decoding to intermediate code point storage.

using to_encoding_type = _ToEncoding

The encoding type used for encoding to the final code units storage.

using from_error_handler_type = _FromErrorHandler

The error handler when a decode operation fails.

using to_error_handler_type = _ToErrorHandler

The error handler when an encode operation fails.

using from_state_type = _FromState

The state type used for decode operations.

using to_state_type = _ToState

The state type used for encode operations.

Public Functions

inline constexpr recode_view(range_type __range) noexcept

Constructs a recode_view from the underlying range.

Parameters:

__range – [in] The input range to wrap and iterate over.

inline constexpr recode_view(range_type __range, to_encoding_type __to_encoding) noexcept

Constructs a recode_view from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

inline constexpr recode_view(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding) noexcept

Constructs a recode_view from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __from_encoding – [in] The encoding object to call decode_one or equivalent functionality on.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

inline constexpr recode_view(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding, from_error_handler_type __from_error_handler, to_error_handler_type __to_error_handler) noexcept

Constructs a recode_view from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __from_encoding – [in] The encoding object to call decode_one or equivalent functionality on.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

  • __from_error_handler – [in] The error handler for decode operations to store in this view.

  • __to_error_handler – [in] The error handler for encode operations to store in this view.

inline constexpr recode_view(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding, from_error_handler_type __from_error_handler, to_error_handler_type __to_error_handler, from_state_type __from_state, to_state_type __to_state) noexcept

Constructs a recode_view from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __from_encoding – [in] The encoding object to call decode_one or equivalent functionality on.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

  • __from_error_handler – [in] The error handler for decode operations to store in this view.

  • __to_error_handler – [in] The error handler for encode operations to store in this view.

  • __from_state – [in] The state to user for the decode operation.

  • __to_state – [in] The state to user for the decode operation.

inline constexpr iterator begin() & noexcept

The beginning of the range.

inline constexpr iterator begin() const & noexcept

The beginning of the range.

inline constexpr iterator begin() && noexcept

The beginning of the range.

inline constexpr sentinel end() const noexcept

The end of the range. Uses a sentinel type and not a special iterator.

template<typename _FromEncoding, typename _ToEncoding, typename _Range, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
class recode_iterator : private ebco<remove_cvref_t<_FromEncoding>, 1>, private ebco<remove_cvref_t<_ToEncoding>, 2>, private ebco<remove_cvref_t<_FromErrorHandler>, 3>, private ebco<remove_cvref_t<_ToErrorHandler>, 4>, private __txt_detail::__state_storage<remove_cvref_t<_FromEncoding>, remove_cvref_t<_FromState>, 0>, private __txt_detail::__state_storage<remove_cvref_t<_ToEncoding>, remove_cvref_t<_ToState>, 1>, private __txt_detail::__cursor_cache<max_code_units_v<unwrap_remove_cvref_t<_ToEncoding>>, ranges::is_range_input_or_output_range_exactly_v<unwrap_remove_cvref_t<_Range>>>, private __txt_detail::__error_cache<decode_error_handler_always_returns_ok_v<unwrap_remove_cvref_t<_FromEncoding>, unwrap_remove_cvref_t<_FromErrorHandler>> && encode_error_handler_always_returns_ok_v<unwrap_remove_cvref_t<_ToEncoding>, unwrap_remove_cvref_t<_ToErrorHandler>>>, private ebco<ranges::range_reconstruct_t<unwrap_remove_cvref_t<_Range>>, 4>

A recoding iterator that takes an input of code units and provides an output over the code units of the desired _ToEncoding after converting from the _FromEncoding in a fashion that will never produce a ztd::text::encoding_error::insufficient_output error.

Remark

This type produces proxies as their reference type, and are only readable, not writable iterators. The type will also try many different shortcuts for decoding the input and encoding the intermediates, respectively, including invoking a few customization points for either decode_one or encode_one . It may also call recode_one to bypass having to do the round-trip through two encodings, which an encoding pair that a developer is interested in can use to do the conversion more quickly. The view presents code units one at a time, regardless of how many code units are output by one decode operation. This means if, for example, one (1) UTF-16 code unit becomes two (2) UTF-8 code units, it will present each code unit one at a time. If you are looking to explicitly know each collection of characters, you will have to use lower-level interfaces.

Template Parameters:
  • _FromEncoding – The encoding to read the underlying range of code points as.

  • _ToEncoding – The encoding to read the underlying range of code points as.

  • _Range – The range of input that will be fed into the _FromEncoding’s decode operation.

  • _FromErrorHandler – The error handler for any decode-step failures.

  • _ToErrorHandler – The error handler for any encode-step failures.

  • _FromState – The state type to use for the decode operations to intermediate code points.

  • _ToState – The state type to use for the encode operations to intermediate code points.

Public Types

using range_type = _Range

The underlying range type.

using iterator_type = _BaseIterator

The base iterator type.

using from_encoding_type = _FromEncoding

The encoding type used for decoding to intermediate code point storage.

using to_encoding_type = _ToEncoding

The encoding type used for encoding to the final code units storage.

using from_error_handler_type = _FromErrorHandler

The error handler when a decode operation fails.

using to_error_handler_type = _ToErrorHandler

The error handler when an encode operation fails.

using from_state_type = remove_cvref_t<_FromState>

The state type used for decode operations.

using to_state_type = remove_cvref_t<_ToState>

The state type used for encode operations.

using iterator_category = ::std::conditional_t<::ztd::ranges::is_iterator_concept_or_better_v<::std::bidirectional_iterator_tag, _BaseIterator>, ::std::conditional_t<_IsBackwards, ::std::bidirectional_iterator_tag, ::std::forward_iterator_tag>, ranges::iterator_category_t<_BaseIterator>>

The strength of the iterator category, as defined in relation to the base.

using iterator_concept = ::std::conditional_t<::ztd::ranges::is_iterator_concept_or_better_v<::std::bidirectional_iterator_tag, _BaseIterator>, ::std::conditional_t<_IsBackwards, ::std::bidirectional_iterator_tag, ::std::forward_iterator_tag>, ranges::iterator_concept_t<_BaseIterator>>

The strength of the iterator concept, as defined in relation to the base.

using value_type = code_unit_t<_ToEncoding>

The object type that gets output on every dereference.

using pointer = value_type*

A pointer type to the value_type.

using reference = value_type

The value returned from derefencing the iterator.

Remark

This is a proxy iterator, so the reference is a non-reference value_type.

using difference_type = ranges::iterator_difference_type_t<_BaseIterator>

The type returned when two of these pointers are subtracted from one another.

Remark

It’s not a very useful type…

Public Functions

inline constexpr recode_iterator() noexcept(::std::is_nothrow_default_constructible_v<__base_from_encoding_t> && ::std::is_nothrow_default_constructible_v<__base_to_encoding_t> && ::std::is_nothrow_default_constructible_v<__base_from_error_handler_t> && ::std::is_nothrow_default_constructible_v<__base_to_error_handler_t> && ::std::is_nothrow_constructible_v<__base_from_state_t, _FromEncoding> && ::std::is_nothrow_constructible_v<__base_to_state_t, _ToEncoding> && ::std::is_default_constructible_v<__base_range_t>)

Default constructs a ztd::text::recode_iterator.

Remark

This can only work if the underlying encodings, error handlers, and states can handle default construction.

constexpr recode_iterator(const recode_iterator&) = default

Copy constructs a recode_iterator.

constexpr recode_iterator(recode_iterator&&) = default

Move constructs a recode_iterator.

inline constexpr recode_iterator(range_type __range) noexcept(noexcept(recode_iterator(::std::move(__range), to_encoding_type{})))

Constructs a recode_iterator from the underlying range.

Parameters:

__range – [in] The input range to wrap and iterate over.

inline constexpr recode_iterator(range_type __range, to_encoding_type __to_encoding)

Constructs a recode_iterator from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

inline constexpr recode_iterator(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding)

Constructs a recode_iterator from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __from_encoding – [in] The encoding object to call decode_one or equivalent functionality on.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

inline constexpr recode_iterator(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding, from_error_handler_type __from_error_handler, to_error_handler_type __to_error_handler)

Constructs a recode_iterator from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __from_encoding – [in] The encoding object to call decode_one or equivalent functionality on.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

  • __from_error_handler – [in] The error handler for decode operations to store in this view.

  • __to_error_handler – [in] The error handler for encode operations to store in this view.

inline constexpr recode_iterator(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding, from_error_handler_type __from_error_handler, to_error_handler_type __to_error_handler, from_state_type __from_state, to_state_type __to_state)

Constructs a recode_iterator from the underlying range.

Parameters:
  • __range – [in] The input range to wrap and iterate over.

  • __from_encoding – [in] The encoding object to call decode_one or equivalent functionality on.

  • __to_encoding – [in] The encoding object to call encode_one or equivalent functionality on.

  • __from_error_handler – [in] The error handler for decode operations to store in this view.

  • __to_error_handler – [in] The error handler for encode operations to store in this view.

  • __from_state – [in] The state to user for the decode operation.

  • __to_state – [in] The state to user for the decode operation.

constexpr recode_iterator &operator=(const recode_iterator&) = default

Copy assigns- a recode_iterator.

constexpr recode_iterator &operator=(recode_iterator&&) = default

Move assigns a recode_iterator.

inline constexpr const from_encoding_type &from_encoding() const

The decoding (β€œfrom”) encoding object.

Returns:

A const l-value reference to the encoding object used to construct this iterator.

inline constexpr from_encoding_type &from_encoding()

The decoding (β€œfrom”) encoding object.

Returns:

An l-value reference to the encoding object used to construct this iterator.

inline constexpr const to_encoding_type &to_encoding() const

The encoding (β€œto”) encoding object.

Returns:

A const l-value reference to the encoding object used to construct this iterator.

inline constexpr to_encoding_type &to_encoding()

The encoding (β€œto”) encoding object.

Returns:

An l-value reference to the encoding object used to construct this iterator.

inline constexpr const from_state_type &from_state() const

The decoding (β€œfrom”) state object.

inline constexpr from_state_type &from_state()

The decoding (β€œfrom”) state object.

inline constexpr const to_state_type &to_state() const

The encoding (β€œto”) state object.

inline constexpr to_state_type &to_state()

The encoding (β€œto”) state object.

inline constexpr const from_error_handler_type &from_handler() const

The error handler object.

inline constexpr from_error_handler_type &from_handler()

The error handler object.

inline constexpr const to_error_handler_type &to_handler() const & noexcept

The error handler object.

inline constexpr to_error_handler_type &to_handler() & noexcept

The error handler object.

inline constexpr to_error_handler_type &&to_handler() && noexcept

The error handler object.

inline constexpr range_type range() & noexcept(::std::is_copy_constructible_v<range_type> ? ::std::is_nothrow_copy_constructible_v<range_type> : (::std::is_nothrow_move_constructible_v<range_type>))

The input range used to construct this object.

inline constexpr range_type range() const & noexcept(::std::is_nothrow_copy_constructible_v<range_type>)

The input range used to construct this object.

inline constexpr range_type range() && noexcept(::std::is_nothrow_move_constructible_v<range_type>)

The input range used to construct this object.

inline constexpr encoding_error pivot_error_code() const noexcept

Returns whether the last read operation had an encoding error or not.

Remark

If the error handler is identified as an error handler that, if given a suitably sized buffer, will never return an error. This is the case with specific encoding operations with ztd::text::replacement_handler_t, or ztd::text::throw_handler_t.

Returns:

The ztd::text::encoding_error that occurred. This can be ztd::text::encoding_error::ok for an operation that went just fine.

inline constexpr encoding_error error_code() const noexcept

Returns whether the last read operation had an encoding error or not.

Remark

If the error handler is identified as an error handler that, if given a suitably sized buffer, will never return an error. This is the case with specific encoding operations with ztd::text::replacement_handler_t, or ztd::text::throw_handler_t.

Returns:

The ztd::text::encoding_error that occurred. This can be ztd::text::encoding_error::ok for an operation that went just fine.

inline constexpr recode_iterator operator++(int)

Copy then increment the iterator.

Returns:

A copy of iterator, before incrementing.

inline constexpr recode_iterator &operator++()

Increment the iterator.

Returns:

A reference to *this, after incrementing the iterator.

inline constexpr value_type operator*() const

Dereference the iterator.

Remark

This is a proxy iterator, and therefore only returns a value_type object and not a reference object. Encoding iterators are only readable, not writable.

Returns:

A value_type (NOT a reference) of the iterator.

Friends

inline friend constexpr friend bool operator== (const recode_iterator &__it, const recode_sentinel_t &)

Compares whether or not this iterator has truly reached the end.

inline friend constexpr friend bool operator== (const recode_sentinel_t &__sen, const recode_iterator &__it)

Compares whether or not this iterator has truly reached the end.

inline friend constexpr friend bool operator!= (const recode_iterator &__it, const recode_sentinel_t &)

Compares whether or not this iterator has truly reached the end.

inline friend constexpr friend bool operator!= (const recode_sentinel_t &__sen, const recode_iterator &__it)

Compares whether or not this iterator has truly reached the end.