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 justztd::span
s.- 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
ofztd::span
ofconst code_point
s. The returnedstd::optional
value is engaged (has a value) if the stored encoding has a validreplacement_code_points
function and it can be called. If it does not, then the library checks to see if themaybe_replacement_code_points
function exists, and returns thestd::optional
from that type directly. If neither are present, an unengagedstd::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
ofztd::span
ofconst code_unit
s. The returnedstd::optional
value is engaged (has a value) if the stored encoding has a validreplacement_code_units
function and it can be called. If it does not, then the library checks to see if themaybe_replacement_code_units
function exists, and returns thestd::optional
from that type directly. If neither are present, an unengagedstd::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.
-
inline any_decode_state(const any_encoding_with &__encoding)ο
-
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.
-
inline any_encode_state(const any_encoding_with &__encoding)ο