Literal

The literal encoding handles C and C++ string literals ("🐱") used at compile time and stored in the binary. The library uses a number of heuristics to determine with any degree of certainty what the encoding of string literals are, but in some cases it is not explicitly possible to achieve this goal.

If the library cannot figure out the literal encoding, the code will typically error with a static_assert, loudly, that it cannot use the functions on the type when you attempt to do anything with them because it may mangle whatever input or output you are expecting.

If you know the encoding of literals for your project (you provide the command line switch, or similar), then you can define a configuration macro named ZTD_CXX_COMPILE_TIME_ENCODING_NAME to be a string literal of your type, such as "UTF-8" or "ISO-8859-1".

If the library does not recognize the encoding and cannot transcode it properly, it will also loudly warn you that it does not understand the encoding of the literal (in which case, file an issue about it and we will add it to the list of acceptable literal encodings).

If you like to live dangerously and do not care for the warnings, you can define a configuration macro named ZTD_TEXT_YES_PLEASE_DESTROY_MY_LITERALS_UTTERLY_I_MEAN_IT and it will just blindly go with whatever weird default it ended up deciding on.

(This is usually a catastrophically terrible idea, but let is not be said that we didn’t give you the power to do great things, even if it cost you your foot.)

Alias

constexpr literal_t ztd::text::literal = {}: An instance of the literal_t type for ease of use.

Base Type

class literal_t : public __literal

The encoding of string literal_ts ( e.g. "👍" ) at compile time.

Public Types

using is_unicode_encoding = ::std::integral_constant<bool, is_unicode_encoding_id(__txt_detail::__literal_id)>: Whether or not this literal_t encoding is a Unicode Transformation Format, such as UTF-8, UTF-EBCDIC, or GB18030.

using code_unit = code_unit_t<__base_t>: The individual units that result from an encode operation or are used as input to a decode operation.

using code_point = code_point_t<__base_t>: The individual units that result from a decode operation or as used as input to an encode operation. For most encodings, this is going to be a Unicode Code Point or a Unicode Scalar Value.

using encode_state = encode_state_t<__base_t>: The state that can be used between calls to encode_one.

using decode_state = decode_state_t<__base_t>: The state that can be used between calls to decode_one.

using is_decode_injective = ::std::integral_constant<bool, is_decode_injective_v<__base_t>>

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

Remark

The decode step should always be injective because every encoding used for literal_ts in C++ needs to be capable of being represented by UCNs. Whether or not a platform is a jerk, who knows?

using is_encode_injective = ::std::integral_constant<bool, is_encode_injective_v<__base_t>>

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

Remark

This is absolutely not guaranteed to be the case, and as such we must check the provided encoding name for us to be sure.

Public Functions

constexpr literal_t() noexcept = default: Default constructs a ztd::text::literal.

constexpr literal_t(const literal_t&) noexcept = default: Copy constructs a ztd::text::literal.

constexpr literal_t(literal_t&&) noexcept = default: Move constructs a ztd::text::literal.

constexpr literal_t &operator=(const literal_t&) noexcept = default: Copy assigns into a ztd::text::literal_t object.

constexpr literal_t &operator=(literal_t&&) noexcept = default: Move assigns into a ztd::text::literal_t object.

template<typename _Input, typename _Output, typename _ErrorHandler> inline constexpr auto decode_one(_Input &&__input, _Output &&__output, _ErrorHandler &&__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.

template<typename _Input, typename _Output, typename _ErrorHandler> inline constexpr auto encode_one(_Input &&__input, _Output &&__output, _ErrorHandler &&__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 const ::ztd::text_encoding_id decoded_id = decoded_id_v<__base_t>: The id representing the decoded text.

static constexpr const ::ztd::text_encoding_id encoded_id = encoded_id_v<__base_t>: The id representing the encoded text.

static constexpr ::std::size_t max_code_points = 16: The maximum number of code points a single complete operation of decoding can produce.

static constexpr ::std::size_t max_code_units = 32: The maximum code units a single complete operation of encoding can produce.