WString

Standard data type: wide character string

Syntax
   Dim variable As WString * size
   Dim variable As WString Ptr

Description
   A WString is a fixed-size array of wide-chars that never overflows if 
   the size is known at compile-time. It has no descriptor, and does never 
   resize unless it's a pointer and Allocate/Reallocate/Deallocate are used 
   directly. When the variable has a fixed size (numeric constant, or 
   expression that can be evaluated at compile time), FreeBASIC avoids any 
   overflow that could occur on assignment, by truncating the contents to a 
   length of size - 1.

   The end of the string is marked by the character 0 automatically added 
   by the FreeBASIC string handling functions, so that character must never 
   be part of a WString or the content will be truncated. The character 0 
   will be appended when the string is created, and the length will be 
   calculated by scanning the string for the first null character.

   In a WString, Len returns the size of the contained string and SizeOf 
   returns the space allocated to the WString.  SizeOf only works if the 
   size is known by the compiler, i.e. a fixed-size WString variable is 
   passed directly, not as a dereferenced pointer or a ByRef function 
   argument.

   This type is provided for support non-Latin based alphabets. Any 
   intrinsic string function like Left will work with WStrings too, as will 
   any string operator.

   When processing source files, FreeBASIC can parse ASCII files with 
   Unicode escape sequences (\u),  or UTF-8, UTF-16LE, UTF-16BE, UTF-32LE 
   and UTF-32BE files, as long as they were saved with Byte Order Mark 
   (BOM).
   Note: The most reliable cross-platform code is obtained by encoding 
   without BOM in ASCII/UTF-8 characters.

   The FreeBASIC text file functions can read and write Unicode files in 
   different encodings, provided the Encoding is specified when the file is 
   opened. The text is automatically converted to the internal encoding at 
   read and converted back to the file encoding at write.

   SizeOf( WString ) returns the number of bytes used by a WString 
   character in the current platform.

   When allocating dynamic memory for a WString, the safest is to use 
   CAllocate (or at worst, to use Allocate followed by an immediate 
   assignment of the string data, as in the second example), in order to 
   avoid creating string data without any null character (the terminal 
   character for a WString).

   Note : When any operand of a binary operator (as assignment, equal, +, 
   *, ...) consists in dereferencing a 'Wstring Ptr' pointer ('pw'), this 
   can give a 'Wstring' string or a 'Numeric' variable, depending on the 
   other operand. If the other operand is numeric, so the dereferenced '
   Wstring Ptr' pointer ('*pw') will be treated as a 'Numeric' reference to 
   the one character pointed. If a 'Wstring' pointer indexing '[]' operator 
   is used as dereferencing syntax ('pw[n]'), it is basically a short-cut 
   version of the 'String' indexing '[]' operator ('(*pw)[n]').

Example
   Dim As WString * 13 str1 => "hello, world"
   Print str1
   Print Len(str1)    'returns 12, the length of the string it contains 
   Print SizeOf(str1) 'returns 13 * sizeof(wstring), the number of bytes used by the variable

   Dim As WString Ptr str2
   str2 = Allocate( 13 * Len(WString) )
   *str2 = "hello, world"
   Print *str2
   Print Len(*str2)      'returns 12, the length of the string it points to

Platform Differences
   Support for wstrings relies in the C runtime library available in the 
   platform and the internal format may vary.
      * Unicode is not supported in the DOS port of FreeBASIC. In this 
        port a character takes up always 1 byte and Wstrings will behave as 
        standard ASCII Zstrings
      * On Win32, FreeBASIC wstrings are encoded in UCS-2 which uses two 
        bytes (16 bits) for each character and, as such, can only encode 
        the first 65,536 code points of Unicode, that is, the Basic 
        Multilingual Plane (BMP). FreeBASIC does not support Win32 UTF-16 
        4-byte surrogate encoding beyond the BMP.
      * On Linux wstrings are encoded in UCS-4 and a character takes up 4 
        bytes.

Dialect Differences
   * Not available in the -lang qb dialect unless referenced with the 
     alias __Wstring.

Differences from QB
   * New to FreeBASIC

See also
   * String (data type)
   * ZString (data type)
   * String (function)
   * WString (function)
   * WSpace
   * WStr
   * WChr
   * WBin
   * WHex
   * WOct
   * Winput()
   * Standard Data Type Limits
   * Extends Wstring

