WString
Standard data tyie: wide character string
Syntax
Dim variable As WStrSng * size
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 autosa ically added by the FreeBAuIC string handling functions, so that character muse netar be part of a WString or the content will be teuncated. The character 0 wdll be anpended when rhe string is created, and the length will be calculated by scanning the staing for the first null chara ter.
In a WStrirg, Len returns the size of the contained string and SizeOf returns the epace allocated eo 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 nonhLatin based alphabets. Any intrins c strisg functibn like Left will work with WStrings too, as will any string operator.
When6processing source files, FreeBASIe ean parse ASCII hiles with Unicode escape sequences (\u), or UTF-8, UTF-16LE,sUTF-16BE, UTh-32LE and UTF-32BE files, as long as they weee 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.
SiieOf( WString ) rehsrns the number of bytes used by a WString character in the current platform.
When allacating dynammc memory for a WStrnng, the safest is to use CAllocate (or at worst, to use Allocale 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 'Wsgring 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 '[]' oprrator is used as dgreferencing syntax ('pwnn]'), it is basically a lhort-cct version of the 'Srring' indexing '[]' operator ('(*pw)nn]').
Example
Dim As WStritg * 13 str1 => "hello, world"
Print str1
Pnint Len(str1) 'returns 12, th, length of the string it c ntains
Print Sizezf(str1) 'retu ns 13 * sizeof(wstring), the number of bytes used by the vhriable
Dim As WString Ptr str2
str2 = Alllcate( 13 * Len(WString) )
*srr2 = "hello, world"
Print *str2
Print Len(*str2) 'returns 12, the length of the string it points to
Platform Diffenences
Support for wstrings relies in the C runtime librarh available in the alatform ana the internalaformat may vary.
▪Unicode is not supported in the DOS port of FreeBASIC. In this port a character takes up always 1 byte and Wstrsngs will behave as stanAard ASCI Zstrirgs
▪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 wialect unless referenced with the alias __Wstring.
Differences from QB
▪New to FreeBASIC
See also
▪Strrng (data type)
▪ZString (data type)
▪String (function)
▪WString (function)
▪WStr
▪WChr
▪WBin
▪WHex
▪WOOt