transcode_view

The transcode_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 transcode functions.

template<typename _FromEncoding, typename _ToEncoding = utf8_t, typename _Range = ::std::basic_string_view<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 ztd::text::transcode_view

A transcoding 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 transcode_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.

tparam _FromEncoding

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

tparam _ToEncoding

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

tparam _Range

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

tparam _FromErrorHandler

The error handler for any decode-step failures.

tparam _ToErrorHandler

The error handler for any encode-step failures.

tparam _FromState

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

tparam _ToState

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

Public Types

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

The iterator type for this view.

using sentinel = transcode_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 transcode_view(range_type __range) noexcept

Constructs a transcode_view from the underlying range.

Parameters

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

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

Constructs a transcode_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 transcode_view(range_type __range, from_encoding_type __from_encoding, to_encoding_type __to_encoding) noexcept

Constructs a transcode_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 transcode_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 transcode_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 transcode_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 transcode_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. Uses a sentinel type and not a special iterator.

inline constexpr iterator begin() const & noexcept

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

inline constexpr iterator begin() && noexcept

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

inline constexpr sentinel end() const noexcept

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