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_LIBICONV (CMake: ZTD_TEXT_USE_ICONV)
    • Enables use of the iconv project.

    • Attempts to use the headers directly if possible.

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

    • Makes the ztd::text::basic_iconv available (accessible directly VIA #include <ztd/text/basic_iconv.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
  • 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
  • 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.