Standard data type: wide character string

dim variable as Wstring * size
dim variable as Wstring ptr

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]').

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:
Differences from QB:
See also:
Back to Standard Data Types
Back to String Functions
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki phatcode