Iterator Interface

The icubaby::iterator class is an output iterator to which code units in the source encoding can be assigned. This will produce equivalent code units in the output encoding which are written to a second output iterator. This makes it straightforward to use standard library algorithms such as std::copy() or std::ranges::copy() with the library.

Iterator Interface Example

using icubaby::char8;
auto const in = std::array{static_cast<char8> (0xF0),
                           static_cast<char8> (0x9F),
                           static_cast<char8> (0x98),
                           static_cast<char8> (0x80)};
std::vector<char16_t> out;
icubaby::t8_16 t;
auto it = icubaby::iterator{&t, std::back_inserter (out)};
for (auto const cu: in) {
  *(it++) = cu;
}
it = t.end_cp (it);

This code creates an instance of icubaby::iterator named it which holds two values: a pointer to transcoder t and output interator (std::back_insert_iterator() in this case). Assigning a series of code units from the input to it result in the out vector being filled with equivalent code units in the output encoding.

The above code snippet loops over the contents of the in array one code unit at a time. We can use std::ranges::copy() to achieve the same effect:

using icubaby::char8;
auto const in = std::array{static_cast<char8> (0xF0),
                           static_cast<char8> (0x9F),
                           static_cast<char8> (0x98),
                           static_cast<char8> (0x80)};
std::vector<char16_t> out;
icubaby::t8_16 t;
auto it = std::ranges::copy (in, icubaby::iterator{&t, std::back_inserter (out)}).out;
it = t.end_cp (it);

icubaby::iterator Reference

template<typename Transcoder, typename OutputIterator>
class iterator

An output iterator which passes code units being output through a transcoder.

This iterator simplifies the job of converting unicode representation and storing the results of that conversion. Each time that a code point is recovered from the sequence written to this class, the equivalent sequence is written to the iterator with which the object was constructed.

For example, a function to convert a UTF-16 string to UTF-8 becomes very simple:

std::u8string utf16_to_8_demo (std::u16string u16) {
  std::u8string u8;
  icubaby::t16_8 t;
  icubaby::iterator out{&t, std::back_inserter(u8)};
  t.end_cp (std::copy (u16.begin(), u16.end(), out));
  return u8;
}

Template Parameters:

• Transcoder – A transcoder type.

• OutputIterator – An output iterator type.

Public Types

using iterator_category = std::output_iterator_tag

Defines this class as fulfilling the requirements of an output iterator.

using value_type = void

The class is an output iterator and as such does not yield values.

using difference_type = std::ptrdiff_t

A type that can be used to identify distance between iterators.

using pointer = void

Defines a pointer to the type iterated over (none in the case of this iterator).

using reference = void

Defines a reference to the type iterated over (none in the case of this iterator).

Public Functions

inline iterator(Transcoder *transcoder, OutputIterator out)

Initializes the underlying transcoder and the output iterator to which elements will be written.

Parameters:

• transcoder – The underlying transcoder. This class does not take ownership of the pointer.

• out – An output iterator to which code units produced by the transcoder will be written.

inline iterator &operator=(typename Transcoder::input_type const &value)

Passes a code unit to the associated transcoder.

Parameters:

value – The code unit to be passed to the transcoder.

Returns:

*this

inline constexpr iterator &operator*() noexcept

no-op

Returns:

*this

inline constexpr iterator &operator++() noexcept

no-op

Returns:

*this

inline constexpr iterator operator++(int) noexcept

no-op

Returns:

*this

inline constexpr OutputIterator base() const noexcept

Accesses the underlying iterator.

inline constexpr Transcoder *transcoder() noexcept

Accesses the underlying transcoder.

inline constexpr Transcoder const *transcoder() const noexcept

Accesses the underlying transcoder.