This module contains new string types and utilities to deal with strings in Windows. Windows SDK use following types to represent a char or a string:

type
  CHAR = char
  WCHAR = uint16
  LPSTR|LPCSTR = ptr CHAR # however, it should be ansi string, not utf8 string
  LPWSTR|LPCWSTR = ptr WCHAR
  BSTR = distinct ptr WCHAR # BSTR is not binary compatible with LPWSTR
  (ptr) array[I, CHAR] # sometimes string defined as array[1, CHAR] but not only one char
  (ptr) array[I, WCHAR] # sometimes string defined as array[1, WCHAR] but not only one widechar

By default, Nim's string type is utf8 encoding. However, Windows use wide character string (aka. unicode string) or multibyte character string (aka. ansi string). So, this module introduce following string types.

type
  string # nim built-in string type, utf8 encoding by default, can be ansi string sometimes.
  cstring # compatible to the type char* in Ansi C
  wstring = distinct string # new string type to store unicode string
  mstring = distinct string # new string type to store ansi string

Some type classes are also defined for convenience to deal 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 are the pseudocode for 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 utf8 encoding.
  # setOpenArrayStringable() can be used to switch the behavior of `$` operator.

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 encoding.
  # 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 buffer by string, include a null.
  
  # These operators don't convert the encoding (copy byte by byte).
  # Please make sure both side have the same character size.
  # If destination don't have the 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 const string or string literal can be converted to unicode string at compile-time,
  # otherwise it is just `+$`.

template T(s: string): mstring|wstring
  # Generate wstring or mstring depend on conditional symbol: useWinAnsi.
  # For example: (this code works under both unicode and ansi mode)
    
    MessageBox(0, T"hello, world", T"Nim is Powerful 中文測試", 0)

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

converter winstrConverter(s: SomeString): SomeBuffer
  # With these converters, passing string to Windows API is more easy.
  #   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 (utf8 to unicode).
  #   New memory block will be allocated. However, they are useful and convenience.
  #     cstring|string => LPWSTR|BSTR

There are also new string functions to deal with wstring and mstring just like 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 don't use built-in WideCString, but still support it.

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

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

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