any_encoding_with

This is the lowest level base template, any_encoding_with, that sits beneath any_encoding and any_byte_encoding. It is recommended for power users with specific goals for the input and output types of the encode and decode operations, where normal buffer-based I/O is unsuitable. In general, you should be relying on any_encoding and any_byte_encoding.

Base Template

template<typename _EncodeCodeUnits, typename _EncodeCodePoints, typename _DecodeCodeUnits, typename _DecodeCodePoints, ::std::size_t _MaxCodeUnits = __txt_detail::__default_max_code_units_any_encoding, ::std::size_t _MaxCodePoints = __txt_detail::__default_max_code_points_any_encoding>
class any_encoding_with

An encoding class which has the given encode output and input, as well as the decode input and output ranges, provided as fixed types alongside the maximum number of code units put in and pushed out.

Remark

This class is generally interacted with by using its derivate class, ztd::text::any_byte_encoding, and its convenience alias, ztd::text::any_encoding. This class’s use is recommended only for power users who have encoding ranges that cannot be interacted with through ztd::span and therefore need other ways. We are looking into ways to produce a ranges::subrange<any_iterator> as a completely generic range to aid those individuals who do not want to deal in just ztd::spans.

Template Parameters:

  • _EncodeCodeUnits – The output of encode_one and related operations.

  • _EncodeCodePoints – The input of encode_one and related operations.

  • _DecodeCodeUnits – The input of decode_one and related operations.

  • _DecodeCodePoints – The output of decode_one and related operations.

  • _MaxCodeUnits – The maximum number of code units that can be output through a given operation. Directly related to the maximum_code_units inline constexpr variable definition.

  • _MaxCodePoints – The maximum number of code points that can be output through a given operation. Directly related to the maximum_code_points inline constexpr variable definition.

Subclassed by any_byte_encoding< _Byte, _CodePoint >

Public Types

using decode_state = any_decode_state

The state that can be used between calls to decode.

Remark

This is an opaque struct with no members. It follows the β€œencoding-dependent state” model, which means it has a constructor that takes an ztd::text::any_encoding_with so it can properly initialize its state.

using encode_state = any_encode_state

The state that can be used between calls to encode.

Remark

This is an opaque struct with no members. It follows the β€œencoding-dependent state” model, which means it has a constructor that takes an ztd::text::any_encoding_with so it can properly initialize its state.

using code_unit = ranges::range_value_type_t<_EncodeCodeUnits>

The individual units that result from an encode operation or are used as input to a decode operation.

using code_point = ranges::range_value_type_t<_DecodeCodePoints>

The individual units that result from a decode operation or as used as input to an encode operation.

using is_encode_injective = ::std::false_type

Whether or not the encode operation can process all forms of input into code point values.

Remark

This is always going to be false because this is a type-erased encoding; this value is determined by a runtime decision, which means that the most conservative and truthful answer is selected for this property.

using is_decode_injective = ::std::false_type

Whether or not the decode operation can process all forms of input into code point values.

Remark

This is always going to be false because this is a type-erased encoding; this value is determined by a runtime decision, which means that the most conservative and truthful answer is selected for this property.

Public Functions

any_encoding_with() = delete

Cannot default-construct a ztd::text::any_encoding_with object.

template<typename _Encoding, typename ..._Args, ::std::enable_if_t<!::std::is_same_v<_Encoding, any_encoding_with> && !is_specialization_of_v<remove_cvref_t<_Encoding>, ::std::in_place_type_t>>* = nullptr>
inline any_encoding_with(_Encoding &&__encoding, _Args&&... __args)

Constructs a ztd::text::any_encoding_with with the encoding object and any additional arguments.

Template Parameters:

_Encoding – The Encoding specified by the first argument.

Parameters:

  • __encoding – [in] The encoding object that informs the ztd::text::any_encoding_with what encoding object to store.

  • __args – [in] Any additional arguments used to construct the encoding in the erased storage.

template<typename _Encoding, typename ..._Args>
inline any_encoding_with(::std::in_place_type_t<_Encoding> __tag, _Args&&... __args)

Constructs a ztd::text::any_encoding_with with the encoding type specified in the __tag argument.

Template Parameters:

_Encoding – The Encoding specified by the __tag argument.

Parameters:

  • __tag – [in] The type marker that informs the ztd::text::any_encoding_with what encoding object to store.

  • __args – [in] Any additional arguments used to construct the encoding in the erased storage.

any_encoding_with(const any_encoding_with&) = delete

Cannot copy-construct a ztd::text::any_encoding_with object.

any_encoding_with &operator=(const any_encoding_with&) = delete

Cannot copy-assign a ztd::text::any_encoding_with object.

any_encoding_with(any_encoding_with&&) = default

Move-constructs a ztd::text::any_encoding_with from the provided r-value reference.

Remark

This leaves the passed-in r-value reference without an encoding object. Calling any function on a moved-fron ztd::text::any_encoding_with, except for destruction, is a violation and invokes Undefined Behavior (generally, a crash).

any_encoding_with &operator=(any_encoding_with&&) = default

Move-assigns a ztd::text::any_encoding_with from the provided r-value reference.

Remark

This leaves the passed-in r-value reference without an encoding object. Calling any function on a moved-fron ztd::text::any_encoding_with, except for destruction, is a violation and invokes Undefined Behavior (generally, a crash).

inline ::std::optional<::ztd::span<const code_point>> maybe_replacement_code_points() const noexcept

Retrieves the replacement code points for when conversions fail and ztd::text::replacement_handler_t (or equivalent) needs to make a substitution.

Returns:

A std::optional of ztd::span of const code_points. The returned std::optional value is engaged (has a value) if the stored encoding has a valid replacement_code_points function and it can be called. If it does not, then the library checks to see if the maybe_replacement_code_points function exists, and returns the std::optional from that type directly. If neither are present, an unengaged std::optional is returned.

inline ::std::optional<::ztd::span<const code_unit>> maybe_replacement_code_units() const noexcept

Retrieves the replacement code units for when conversions fail and ztd::text::replacement_handler_t (or equivalent) needs to make a substitution.

Returns:

A std::optional of ztd::span of const code_units. The returned std::optional value is engaged (has a value) if the stored encoding has a valid replacement_code_units function and it can be called. If it does not, then the library checks to see if the maybe_replacement_code_units function exists, and returns the std::optional from that type directly. If neither are present, an unengaged std::optional is returned.

inline bool contains_unicode_encoding() const noexcept

Returns whether or not the encoding stored in this ztd::text::any_encoding_with is a Unicode encoding.

Remark

This can be useful to know, in advance, whether or not there is a chance for lossy behavior. Even if, at compile time, various functions will demand you use an error handler, this runtime property can help you get a decent idea of just how bad and lossy this conversion might be compared to normal UTF conversion formats.

inline __decode_result decode_one(_DecodeCodeUnits __input, _DecodeCodePoints __output, __decode_error_handler __error_handler, decode_state &__state) const

Decodes a single complete unit of information as code points and produces a result with the input and output ranges moved past what was successfully read and written; or, produces an error and returns the input and output ranges untouched.

Remark

To the best ability of the implementation, the iterators will be returned untouched (e.g., the input models at least a view and a forward_range). If it is not possible, returned ranges may be incremented even if an error occurs due to the semantics of any view that models an input_range.

Parameters:

  • __input – [in] The input view to read code uunits from.

  • __output – [in] The output view to write code points into.

  • __error_handler – [in] The error handler to invoke if encoding fails.

  • __state – [inout] The necessary state information. For this encoding, the state is empty and means very little.

Returns:

A ztd::text::decode_result object that contains the input range, output range, error handler, and a reference to the passed-in state.

inline __encode_result encode_one(_EncodeCodePoints __input, _EncodeCodeUnits __output, __encode_error_handler __error_handler, encode_state &__state) const

Encodes a single complete unit of information as code units and produces a result with the input and output ranges moved past what was successfully read and written; or, produces an error and returns the input and output ranges untouched.

Remark

To the best ability of the implementation, the iterators will be returned untouched (e.g., the input models at least a view and a forward_range). If it is not possible, returned ranges may be incremented even if an error occurs due to the semantics of any view that models an input_range.

Parameters:

  • __input – [in] The input view to read code points from.

  • __output – [in] The output view to write code units into.

  • __error_handler – [in] The error handler to invoke if encoding fails.

  • __state – [inout] The necessary state information. For this encoding, the state is empty and means very little.

Returns:

A ztd::text::encode_result object that contains the input range, output range, error handler, and a reference to the passed-in state.

Public Static Attributes

static constexpr ::std::size_t max_code_points = _MaxCodePoints

The maximum number of code points a single complete operation of decoding can produce. This is 1 for all Unicode Transformation Format (UTF) encodings.

static constexpr ::std::size_t max_code_units = _MaxCodeUnits

The maximum code units a single complete operation of encoding can produce.

static constexpr ::ztd::text_encoding_id decoded_id = ::ztd::text_encoding_id::unknown

The decoded id. Because this is a type-erased encoding, anything can come out: therefore, it is set to β€œunknown” at all times.

static constexpr ::ztd::text_encoding_id encoded_id = ::ztd::text_encoding_id::unknown

The encoded id. Because this is a type-erased encoding, anything can come out: therefore, it is set to β€œunknown” at all times.

class any_decode_state

Public Functions

inline any_decode_state(const any_encoding_with &__encoding)

Creates a state properly initialized from the stored encoding.

any_decode_state(const any_decode_state&) = delete

You cannot copy construct an any_decode_state.

any_decode_state &operator=(const any_decode_state&) = delete

You cannot copy assign an any_decode_state.

any_decode_state(any_decode_state&&) = default

Move constructs an any_decode_state.

any_decode_state &operator=(any_decode_state&&) = default

Move assigns an any_decode_state.

class any_encode_state

Public Functions

inline any_encode_state(const any_encoding_with &__encoding)

Creates a state properly initialized from the stored encoding.

any_encode_state(const any_encode_state&) = delete

You cannot copy construct an any_encode_state.

any_encode_state &operator=(const any_encode_state&) = delete

You cannot copy assign an any_encode_state.

any_encode_state(any_encode_state&&) = default

Move constructs an any_encode_state.

any_encode_state &operator=(any_encode_state&&) = default

Move assigns an any_encode_state.