This module contains new string types and utilities for dealing with Windows strings. The Windows SDK uses the following types to represent a character or string:

type
  CHAR = char
  WCHAR = uint16
  LPSTR|LPCSTR = ptr CHAR # however, it should be an ANSI string, not a UTF-8 string
  LPWSTR|LPCWSTR = ptr WCHAR
  BSTR = distinct ptr WCHAR # BSTR is not binary compatible with LPWSTR
  (ptr) array[I, CHAR] # sometimes a string is defined as array[1, CHAR], but not necessarily only one character
  (ptr) array[I, WCHAR] # sometimes a string is defined as array[1, WCHAR], but not necessarily only one wide character

By default, Nim's string type uses UTF-8 encoding. However, Windows uses wide-character strings (a.k.a. Unicode strings) or multibyte-character strings (a.k.a. ANSI strings). Therefore, this module introduces the following string types.

type
  string # Nim's built-in string type, UTF-8 encoded by default; can sometimes be an ANSI string.
  cstring # compatible with the type char* in ANSI C
  wstring = distinct string # a new string type to store Unicode strings
  mstring = distinct string # a new string type to store ANSI strings

Some type classes are also defined for convenience when dealing with strings.

type
  SomeChar = byte | char | WCHAR
  SomeString = string | mstring | wstring
  SomeBuffer[I] = ptr SomeChar | array[I, SomeChar] | ptr array[I, SomeChar] |
    ptr UncheckedArray[SomeChar] | openArray[SomeChar] | seq[SomeChar]
  Stringable = SomeChar | SomeString | SomeBuffer | cstring | BSTR

Here is pseudocode for the most useful functions introduced by this module.

proc `&`(s: cstring|string|wstring|mstring): pointer
  # Get address of the first char of a string.
  # For string, it has a similar meaning to cstring(s).

proc `$`(x: Stringable): string
proc `+$`(x: Stringable): wstring
proc `-$`(x: Stringable): mstring
  # Convert any stringable type to string, wstring, or mstring.
  # These operators assume string|cstring|ptr char|openArray[char] are UTF-8-encoded strings.
  # Use `%$` to treat `openArray[SomeChar]` explicitly as a string.

proc `$$`(x: Stringable): string
proc `+$$`(x: Stringable): wstring
proc `-$$`(x: Stringable): mstring
  # Convert any stringable type to string, wstring, or mstring.
  # These operators assume string|cstring|ptr char|openArray[char] are ANSI-encoded strings.
  # For mstring|wstring|LPWSTR etc, these operators are the same as `$`, `+$`, `-$`.

template `<<`(s: SomeString, b: SomeBuffer)
template `<<`(b: SomeBuffer, s: SomeString)
template `<<<`(b: SomeBuffer, s: SomeString)
template `>>`(a: typed, b: typed) = b << a
template `>>>`(a: typed, b: typed) = b <<< a
  # String << Buffer or Buffer >> String: Fill string by buffer.
  # Buffer << String or String >> Buffer: Fill buffer by string.
  # Buffer <<< String or String >>> Buffer: Fill a buffer with a string, including a null terminator.
  
  # These operators don't convert the encoding (they copy byte by byte).
  # Please make sure both sides have the same character size.
  # If the destination does not have length information (e.g. pointer or UncheckedArray),
  # please make sure the buffer size is large enough.

proc nullTerminate(s: var SomeString)
  # Assume a string is null terminated and set the correct length.

proc nullTerminated[T: SomeString](s: T): T
  # Assume a string is null terminated and return the length-corrected string.

template L(s: string): wstring
  # Generate wstring at compile-time if possible.
  # Only a const string or string literal can be converted to a Unicode string at compile time;
  # otherwise it is just `+$`.

template T(s: string): mstring|wstring
  # Generate a wstring or mstring depending on the conditional symbol: useWinAnsi.
  # For example: (this code works under both Unicode and ANSI modes)
    
    MessageBox(0, T"hello, world", T"Nim is Powerful 中文測試", 0)

template T(n: Natural): mstring|wstring
  # Generate a wstring or mstring buffer depending on the conditional symbol: useWinAnsi.
  # Use `&` to get the buffer address and then pass to Windows API.

converter winstrConverter(s: SomeString): SomeBuffer
  # With these converters, passing strings to the Windows API is easier.
  #   The following converters don't need encoding conversion:
  #     string => LPSTR|ptr char
  #     mstring => LPSTR|ptr char
  #     wstring => LPWSTR|BSTR
  #     cstring => ptr char
  #     BSTR => LPWSTR
  #
  #   Some converters do need encoding conversion (UTF-8 to Unicode).
  #   A new memory block will be allocated. However, these converters are useful and convenient.
  #     cstring|string => LPWSTR|BSTR

There are also new string functions for dealing with wstring and mstring like the built-in string type.

proc newWString(len: Natural): wstring
  # Generate wstring buffer
proc newMString(len: Natural): mstring
  # Generate mstring buffer

proc setLen(s: var mstring|wstring, newLen: Natural)
proc substr(s: wstring|mstring, first = 0): wstring|mstring
proc substr(s: wstring|mstring, first, last: int): wstring|mstring
proc len(s: wstring|mstring): int
proc high(s: wstring|mstring): int
proc low(s: wstring|mstring): int
proc repr(s: wstring|mstring): string
proc toHex(s: wstring|mstring): string

proc `[]`(s: wstring|mstring, i: int): WCHAR|mstring
proc `[]=`(s: wstring|mstring, i: int, u: WCHAR|CHAR)
proc `[]=`(s: wstring|mstring, i: int, u: wstring|mstring)
proc `[]`(s: wstring|mstring, x: HSlice)
proc `[]=`(s: var wstring|var mstring, x: HSlice[int], b: wstring|mstring)
proc `==`(x, y: wstring|mstring): bool
proc `<=`(x, y: wstring|mstring): bool
proc `<`(x, y: wstring|mstring): bool
proc cmp(x, y: wstring|mstring): int
proc `&`(s: wstring|mstring, t: wstring|mstring): wstring|mstring

iterator items(s: wstring|mstring): WCHAR|mstring
iterator mitems(s: var wstring): WCHAR
iterator pairs(s: wstring|mstring): tuple[key: int|mIndex, val: WCHAR|mstring]
iterator mpairs(s: var wstring): WCHAR

Winim doesn't use the built-in WideCString, but still supports it.

converter winstrConverter(s: WideCString): LPWSTR
  # WideCString can be sent directly to the Windows API (Unicode only).

proc `+$`(s: WideCString): wstring
  # Converts WideCString to wstring.

proc newWideCString(s: wstring): WideCString
  # Converts wstring to WideCString.