Configuring the Library

There are various configuration macros and CMake/build-time switches that will change the behavior of the library or attempt to use different

• ZTD_TEXT_USE_CUNEICODE (CMake: ZTD_TEXT_USE_CUNEICODE)

  • Enables use of the Cuneicode project, which has low-level C routines for converting from one encoding form to another encoding form. Only includes a limited number of conversions, specifically from and to the execution encoding to other encodings.

  • Makes the ztd::text::cnc_encoding available (accessible directly VIA #include <ztd/text/cnc_encoding.hpp>)

  • Default: off.

  • Turned on if the special __has_include directive is present with the compiler and __has_include(<ztd/cuneicode/cuneicode.h>) works.

• ZTD_TEXT_USE_ICONV (CMake: ZTD_TEXT_USE_ICONV)

  • Enables use of the iconv project.

  • Attempts to load it from the system at runtime using GetProcAddress, dlopen/dlsym/dlclose.

  • Makes the ztd::text::iconv_encoding available (accessible directly VIA #include <ztd/text/iconv_encoding.hpp>).

  • Default: off.

  • Not turned on by-default under any conditions.

• ZTD_TEXT_UNICODE_CODE_POINT_DISTINCT_TYPE

  • Turns ztd::text::unicode_code_point from a type definition to char32_t to an implementation-defined class type which enforces the various invariants of being a unicode code point.

  • Default: off.

  • Not turned on by-default under any conditions.

• ZTD_TEXT_UNICODE_CODE_POINT_INVARIANT_ABORT

  • If ztd::text::unicode_code_point is a distinct class (as controlled by ZTD_TEXT_UNICODE_CODE_POINT_DISTINCT_TYPE), each construction of a unicode_code_point object that violates the required invariants of a unicode code point will trigger an abort.

  • It is normally a ZTD_TEXT_ASSERT(...) or equivalent.

  • Default: off.

  • Not turned on by-default under any conditions.

• ZTD_TEXT_DEFAULT_HANDLER_THROWS

  • Makes the ztd::text::default_handler into a throwing handler rather than a replacement character handler.

  • This is not at all recommended since malformed text (or text assumed to be the wrong encoding) is common, and not properly handling a thrown exception can result in what is, effectively, a denial-of-service attack for things which need to continually handle untrusted input.

  • Default: off.

  • Not turned on by-default under any conditions.

• ZTD_TEXT_UNICODE_SCALAR_VALUE_DISTINCT_TYPE

  • Turns ztd::text::unicode_scalar_value from a type definition to char32_t to an implemenation-defined class type which enforces the various invariants of being a unicode scalar value.

  • Default: on.

  • Not turned off by-default under any conditions.

• ZTD_TEXT_UNICODE_SCALAR_VALUE_INVARIANT_ABORT

  • If ztd::text::unicode_scalar_value is a distinct class (as controlled by ZTD_TEXT_UNICODE_SCALAR_VALUE_DISTINCT_TYPE), each construction of a unicode_scalar_value object that violates the required invariants of a unicode scalar value will trigger an abort.

  • It is normally a ZTD_TEXT_ASSERT(...) or equivalent.

  • Default: off.

  • Not turned on by-default under any conditions.

• ZTD_CXX_COMPILE_TIME_ENCODING_NAME

  • Gives the ztd::text::literal encoding a name that matches what the encoding of string literals ("👍") are.

  • Overrides any of library’s heuristics and shenanigans to determine the string literal encoding.

  • If this does not match the actual string literal encoding, it can cause ☢️☢️Undefined Behavior☢️☢️.

  • Default: A complex set of platform checks. See ztd::text::literal encoding for more details.

  • Not turned on normally under any circumstances.

• ZTD_TEXT_YES_PLEASE_DESTROY_MY_LITERALS_UTTERLY_I_MEAN_IT

  • Enables ignoring the fact that the string literal ("🤷‍♀️") encoding cannot be determined/discovered on the given platform for the ztd::text::literal encoding.

  • Will cause ☢️☢️Undefined Behavior☢️☢️ if a string literal or wide string literal is encoded or decoded to/from and the encoding does not match whatever pot-shot guess the system takes.

  • Default: off.

  • Not turned on by-default under any conditions.

  • Please don’t use this unless you have some really, really weird setup that requires messing everything up…

• ZTD_CXX_COMPILE_TIME_WIDE_ENCODING_NAME

  • Gives the ztd::text::wide_literal encoding a name that matches what the encoding of wide string literals (L"👍") are.

  • Overrides any of library’s heuristics and shenanigans to determine the wide string literal encoding.

  • If this does not match the actual wide string literal encoding, it can cause ☢️☢️Undefined Behavior☢️☢️.

  • Default: A complex set of platform checks. See ztd::text::wide_literal encoding for more details.

  • Not turned on normally under any circumstances.

• ZTD_TEXT_YES_PLEASE_DESTROY_MY_WIDE_LITERALS_UTTERLY_I_MEAN_IT

  • Enables ignoring the fact that the wide string literal (L"🤷‍♀️") encoding cannot be determined/discovered on the given platform for the ztd::text::wide_literal encoding.

  • Will cause ☢️☢️Undefined Behavior☢️☢️ if a string literal or wide string literal is encoded or decoded to/from and the encoding does not match whatever pot-shot guess the system takes.

  • Default: off.

  • Not turned on by-default under any conditions.

  • Please don’t use this unless you have some really, really weird setup that requires messing everything up…

• ZTD_TEXT_INTERMEDIATE_DECODE_BUFFER_BYTE_SIZE

  • Changes the default intermediate buffer size placed on the stack for temporary operations.

  • Default: a series of compile time platform checking heuristics to determine a generally useful buffer size that will not overflow the stack.

  • Not turned on by default under any conditions.

  • Specify a numeric value for ZTD_TEXT_INTERMEDIATE_DECODE_BUFFER_BYTE_SIZE to have it used instead.

  • Will always be used as the input to a function determining the maximum between this type and a buffer size consistent with ztd::text::max_code_points_v or ztd::text::max_code_points_v.

• ZTD_TEXT_INTERMEDIATE_ENCODE_BUFFER_BYTE_SIZE

  • Changes the default intermediate buffer size placed on the stack for temporary operations.

  • Default: a series of compile time platform checking heuristics to determine a generally useful buffer size that will not overflow the stack.

  • Not turned on by default under any conditions.

  • Specify a numeric value for ZTD_TEXT_INTERMEDIATE_ENCODE_BUFFER_BYTE_SIZE to have it used instead.

  • Will always be used as the input to a function determining the maximum between this type and a buffer size consistent with ztd::text::max_code_points_v or ztd::text::max_code_points_v.

• ZTD_TEXT_INTERMEDIATE_TRANSCODE_BUFFER_BYTE_SIZE

  • Changes the default intermediate buffer size placed on the stack for temporary operations.

  • Default: a series of compile time platform checking heuristics to determine a generally useful buffer size that will not overflow the stack.

  • Not turned on by default under any conditions.

  • Specify a numeric value for ZTD_TEXT_INTERMEDIATE_TRANSCODE_BUFFER_BYTE_SIZE to have it used instead.

  • Will always be used as the input to a function determining the maximum between this type and a buffer size consistent with ztd::text::max_code_points_v or ztd::text::max_code_points_v.