/**	@file	dk3str.h	String handling functions.
The dk3str.c module contains functions for 8-bit character strings,
16-bit character strings and 32-bit character strings.

One of the main goals in the rewrite of dktools from version 2 to version 3
was internationalization and localization.
A programmer has to deal with both "char" and "wchar_t" strings today.
The wchar_t type uses 16 bits on some systems, 32 bits on others.
UTF-16 encoding is used for 16-bit wchar_t data, direct UNICODE encoding
is used for 32-bit wchar_t. When using the char type we can have
different encodings, the most popular are ISO-LATIN-1, UTF-8 and ASCII.

To use localized strings just having string handling routines isn't enough.
We also need system functions, i.e. to open files...

At the time of writing (July 2012) most *x operating systems provide
system functions working with the char data type in ISO-LATIN-1,
UTF-8 and ASCII encoding. On Windows systems the use of wchar_t is
recommended, UTF-16 is used.

For portable programming the dktools libraries use the "dkChar" data
type which is by default mapped to char on all non-Windows systems and to
wchar_t on Windows systems.

The dk3str.c module provides functions for string handling, the
dk3enc.c module provides functions for conversions between the different
character sizes and encodings. The dk3sf.c module provides mappings to
system functions working with the dkChar type.

The module headers contain macros (i.e. dk3str_len()) which are
mapped to different functions (i.e. strlen(), dk3str_c8_len() or 
wcslen(), _wcslen() dk3str_c16_len())
depending on the size of the dkChar character and the availability
of system functions.

Most macros map to system functions whenever available and use the
self-made fallback functions only if a system function is missing.

The dk3str..._cpy() and dk3str..._ncpy() macros are exceptions from
this rule: The always map to the dk3str..._cpy_fb() and dk3str..._ncpy_fb()
functions as these allow in-string copying from right to left.
When using the system functions, source and destination must not overlap.

If you know source and destination do not overlap, you can use
the DK3STR..._CPY() and DK3STR..._NCPY() macros which map to the system
function if available.

Functions by category:

- 8-bit string and character handling:
  - dk3str_c8_tolower()\n
    Convert character to lower case.
  - dk3str_c8_toupper()\n
    Convert character to upper case.
  - dk3str_c8_chr()\n
    Find first occurance of character in string.
  - dk3str_c8_rchr()\n
    Find last occurance of character in string.
  - dk3str_c8_len()\n
    Get string length.
  - dk3str_c8_cmp()\n
    Compare two strings.
  - dk3str_c8_ncmp()\n
    Compare two strings, use first n characters only.
  - dk3str_c8_casecmp()\n
    Compare two strings, case-insensitive.
  - dk3str_c8_is_abbr()\n
    Check whether a string is an abbreviated pattern.
  - dk3str_c8_is_bool()\n
    Check whether a string represents a boolean value.
  - dk3str_c8_is_on()\n
    Check whether a string represents boolean value "true".
  - dk3str_c8_cpy()\n
    Copy string.
  - dk3str_c8_ncpy()\n
    Copy string, specify destination buffer length.
  - dk3str_c8_cat()\n
    Append one string to another.
  - dk3str_c8_start()\n
    Find first word in string.
  - dk3str_c8_next()\n
    Find second word in string.
  - dk3str_c8_chomp()\n
    Remove trailing whitespaces.
  - dk3str_c8_dup_app()\n
    Create copy of string in dynamic memory.
  - dk3str_c8_array_index()\n
    Get index of string in array of patterns.
  - dk3str_c8_array_abbr()\n
    Get index of string in array of patterns,
    abbreviation allowed.
  - dk3str_c8_explode	Split string containing multiple words into
    multiple strings.
  - dk3str_c8_normalize()\n
    Replace whitespace-sequences by one character.
  - dk3str_c8_correct_filename()\n
    Slash/backslash correction for paths.
  - dk3str_c8_is_abs_path()\n
    Check whether a string is an absolute path.
  - dk3str_c8_append_path_app()\n
    Append one path to another.
- 16-bit string and character handling:
  - dk3str_c16_tolower()\n
    Convert character to lower case.
  - dk3str_c16_toupper()\n
    Convert character to upper case.
  - dk3str_c16_chr()\n
    Find first occurance of character in string.
  - dk3str_c16_rchr()\n
    Find last occurance of character in string.
  - dk3str_c16_len()\n
    Get string length.
  - dk3str_c16_cmp()\n
    Compare two strings.
  - dk3str_c16_ncmp()\n
    Compare two strings, use first n characters only.
  - dk3str_c16_casecmp()\n
    Compare two strings, case-insensitive.
  - dk3str_c16_is_abbr()\n
    Check whether a string is an abbreviated pattern.
  - dk3str_c16_is_bool()\n
    Check whether a string represents a boolean value.
  - dk3str_c16_is_on()\n
    Check whether a string represents boolean value "true".
  - dk3str_c16_cpy()\n
    Copy string.
  - dk3str_c16_ncpy()\n
    Copy string, specify destination buffer length.
  - dk3str_c16_cat()\n
    Append one string to another.
  - dk3str_c16_start()\n
    Find first word in string.
  - dk3str_c16_next()\n
    Find second word in string.
  - dk3str_c16_chomp()\n
    Remove trailing whitespaces.
  - dk3str_c16_dup_app()\n
    Create copy of string in dynamic memory.
  - dk3str_c16_array_index()\n
    Get index of string in array of patterns.
  - dk3str_c16_array_abbr()\n
    Get index of string in array of patterns,
    abbreviation allowed.
  - dk3str_c16_explode()\n
    Split string containing multiple words into
    multiple strings.
  - dk3str_c16_normalize()\n
    Replace whitespace-sequences by one character.
  - dk3str_c16_correct_filename()\n
    Slash/backslash correction for paths.
  - dk3str_c16_is_abs_path()\n
    Check whether a string is an absolute path.
  - dk3str_c16_append_path_app()\n
    Append one path to another.
- 32-bit string and character handling:
  - dk3str_c32_tolower()\n
    Convert character to lower case.
  - dk3str_c32_toupper()\n
    Convert character to upper case.
  - dk3str_c32_chr()\n
    Find first occurance of character in string.
  - dk3str_c32_rchr()\n
    Find last occurance of character in string.
  - dk3str_c32_len()\n
    Get string length.
  - dk3str_c32_cmp()\n
    Compare two strings.
  - dk3str_c32_ncmp()\n
    Compare two strings, use first n characters only.
  - dk3str_c32_casecmp()\n
    Compare two strings, case-insensitive.
  - dk3str_c32_is_abbr()\n
    Check whether a string is an abbreviated pattern.
  - dk3str_c32_is_bool()\n
    Check whether a string represents a boolean value.
  - dk3str_c32_is_on()\n
    Check whether a string represents boolean value "true".
  - dk3str_c32_cpy()\n
    Copy string.
  - dk3str_c32_ncpy()\n
    Copy string, specify destination buffer length.
  - dk3str_c32_cat()\n
    Append one string to another.
  - dk3str_c32_start()\n
    Find first word in string.
  - dk3str_c32_next()\n
    Find second word in string.
  - dk3str_c32_chomp()\n
    Remove trailing whitespaces.
  - dk3str_c32_dup_app()\n
    Create copy of string in dynamic memory.
  - dk3str_c32_array_index()\n
    Get index of string in array of patterns.
  - dk3str_c32_array_abbr()\n
    Get index of string in array of patterns,
    abbreviation allowed.
  - dk3str_c32_explode()\n
    Split string containing multiple words into
    multiple strings.
  - dk3str_c32_normalize()\n
    Replace whitespace-sequences by one character.
  - dk3str_c32_correct_filename()\n
    Slash/backslash correction for paths.
  - dk3str_c32_is_abs_path()\n
    Check whether a string is an absolute path.
  - dk3str_c32_append_path_app()\n
    Append one path to another.
- Finding required output buffer size to convert string from one encoding
  to another:
  - dk3str_cnvsz_c8p_to_c8u_app()\n
    ASCII/ISO-LATIN-1 to UTF-8.
  - dk3str_cnvsz_c8u_to_c8p_app()\n
    UTF-8 to ASCII/ISO-LATIN-1.
  - dk3str_cnvsz_c8p_to_c16_app()\n
    ASCII/ISO-LATIN-1 to UTF-16.
  - dk3str_cnvsz_c8u_to_c16_app()\n
    UTF-8 to UTF-16.
  - dk3str_cnvsz_c16_to_c8p_app()\n
    UTF-16 to ASCII/ISO-LATIN-1.
  - dk3str_cnvsz_c16_to_c8u_app()\n
    UTF-16 to UTF-8.
  - dk3str_cnvsz_c8p_to_c32_app()\n
    ASCII/ISO-LATIN-1 to 32-bit.
  - dk3str_cnvsz_c8u_to_c32_app()\n
    UTF-8 to 32-bit.
  - dk3str_cnvsz_c16_to_c32_app()\n
    UTF-16 to 32-bit.
  - dk3str_cnvsz_c32_to_c8p_app()\n
    32-bit to ASCII/ISO-LATIN-1.
  - dk3str_cnvsz_c32_to_c8u_app()\n
    32-bit to UTF-8.
  - dk3str_cnvsz_c32_to_c16_app()\n
    32-bit to UTF-16.
- Convert string from one encoding to another, output buffer provided:
  - dk3str_cnv_c8_to_str_app()\n
    ASCII/ISO-LATIN-1 to dkChar.
  - dk3str_string_to_c8_simple_app()\n
    dkChar to ASCII/ISO-LATIN-1.
  - dk3str_c16_to_c8_simple_app()\n
    16-bit to 8-bit ASCII/ISO-LATIN-1.
  - dk3str_c32_to_c8_simple_app()\n
    32-bit to 8-bit ASCII/ISO-LATIN-1.
  - dk3str_cnv_c8p_to_c8u_app()\n
    ASCII/ISO-LATIN-1 to UTF-8.
  - dk3str_cnv_c8u_to_c8p_app()\n
    UTF-8 to ASCII/ISO-LATIN-1.
  - dk3str_cnv_c8p_to_c16_app()\n
    ASCII/ISO-LATIN-1 to UTF-16.
  - dk3str_cnv_c8u_to_c16_app()\n
    UTF-8 to UTF-16.
  - dk3str_cnv_c16_to_c8p_app()\n
    UTF-16 to ASCII/ISO-LATIN-1.
  - dk3str_cnv_c16_to_c8u_app()\n
    UTF-16 to UTF-8.
  - dk3str_cnv_c8p_to_c32_app()\n
    ASCII/ISO-LATIN-1 to 32-bit.
  - dk3str_cnv_c8u_to_c32_app()\n
    UTF-8 to 32-bit.
  - dk3str_cnv_c16_to_c32_app()\n
    UTF-16 to 32-bit.
  - dk3str_cnv_c32_to_c8p_app()\n
    32-bit to ASCII/ISO-LATIN-1.
  - dk3str_cnv_c32_to_c8u_app()\n
    32-bit to UTF-8.
  - dk3str_cnv_c32_to_c16_app()\n
    32-bit to UTF-16.
- Convert string from one encoding to another, dynamic memory used for output:
  - dk3str_cnvnew_c8p_to_c8u_app()\n
    ASCII/ISO-LATIN-1 to UTF-8.
  - dk3str_cnvnew_c8u_to_c8p_app()\n
    UTF-8 to ASCII/ISO-LATIN-1.
  - dk3str_cnvnew_c8p_to_c16_app()\n
    ASCII/ISO-LATIN-1 to UTF-16.
  - dk3str_cnvnew_c8u_to_c16_app()\n
    UTF-8 to UTF-16.
  - dk3str_cnvnew_c16_to_c8p_app()\n
    UTF-16 to ASCII/ISO-LATIN-1.
  - dk3str_cnvnew_c16_to_c8u_app()\n
    UTF-16 to UTF-8.
  - dk3str_cnvnew_c8p_to_c32_app()\n
    ASCII/ISO-LATIN-1 to 32-bit.
  - dk3str_cnvnew_c8u_to_c32_app()\n
    UTF-8 to 32-bit.
  - dk3str_cnvnew_c16_to_c32_app()\n
    UTF-16 to 32-bit.
  - dk3str_cnvnew_c32_to_c8p_app()\n
    32-bit to ASCII/ISO-LATIN-1.
  - dk3str_cnvnew_c32_to_c8u_app()\n
    32-bit to UTF-8.
  - dk3str_cnvnew_c32_to_c16_app()\n
    32-bit to UTF-16.
*/