encoding_error

enum class ztd::text::encoding_error : int

Describes a failure to encode, decode, transcode, or count, for four core various reasons.

Remark

This does not cover specific failures, like if a sequence was overlong (e.g., UTF-8) or if an encode operation produced an uunpaired surrogate value (e.g. UTF-16).

Values:

enumerator ok

The okay status; everything is fine.

Remark

This does not necessarily mean an error handler was not called. An error handler can set the error code to ztd::text::encoding_error::ok after performing corrective action: see ztd::text::replacement_handler_t for an example.

enumerator invalid_sequence

Input contains ill-formed sequences. This means there were available units of input to read, but what was read resulted in an error.

enumerator incomplete_sequence

Input contains incomplete sequences. This means that the input was exhausted, without finding an invalid sequence, and therefore more input may be required.

Remark

Depending on context, this may or may not be an error in your use case (e.g., reading part of an incomplete network buffer and waiting for more). See ztd::text::basic_incomplete_handler as a way to aid with this use case.

enumerator insufficient_output_space

Output cannot receive the successfully encoded or decoded sequence. This means that, while there were no invalid or incomplete sequences in the input, the output ran out of space to receive it.

Remark

Provide a bigger storage area or guarantee that it meets the minimum required size for potential output. This can be queried for an encoding by using ztd::text::max_code_points_v<the_encoding> for code points, and ztd::text::max_code_units_v<the_encoding> for code units.

inline constexpr ::std::string_view ztd::text::to_name(encoding_error __error_code)

Converts an encoding_error to a string value.

Remark

If a value outside of the allowed encoding_error is passed, then undefined behavior happens.

Returns:

A null-terminated string_view to the data.