WString
Standard data type: wide character string
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, 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), UTF-8, UTF-16LE, UTF-16BE, UTF-32LE and UTF-32BE.
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.
Support for wstrings relies in the C runtime library available in the platform and the internal format may vary.
Syntax
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, 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), UTF-8, UTF-16LE, UTF-16BE, UTF-32LE and UTF-32BE.
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.
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
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
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 wstrings are encoded in UCS-2 and a character takes up always 2 bytes. This is actually not UTF-16 LE, as FreeBASIC doesn't bother with surrogates introduced in Win XP. This further means that what FreeBASIC understands with a character may not represent a full codepoint.
- 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