WString
Standard data type: wide character string
A WString is a fixed-size array of wide-character elements. It has no descriptor and does not resize automatically. If a WString value is declared with a fixed size, that size includes the terminating zero element, so the usable text capacity is size - 1 elements. When assigning to a fixed-size WString, FreeBASIC truncates the assigned text as needed so that the terminator still fits.
A Wstring Ptr points at a zero-terminated wide-character buffer. Pointer-based WString storage must be allocated, reallocated, and freed explicitly with Allocate, CAllocate, Reallocate, and Deallocate.
The end of a WString is marked by element value 0. The FreeBASIC string handling routines append that terminator when creating or assigning WString data, and they calculate the length by scanning for the first zero element. Embedded zero elements therefore terminate the visible string for the normal WString operations.
For a WString, Len returns the number of stored wide-character elements before the first zero terminator. SizeOf returns the number of bytes reserved by the variable when that storage size is known by the compiler, such as a fixed-size WString variable. SizeOf cannot recover the original allocation size from a dereferenced pointer or from a ByRef argument.
The size and meaning of one WString element depends on the target. Do not assume that WString is always UTF-16, always UTF-32, or always a complete Unicode scalar value per element. On targets with 16-bit wide characters, values outside the Basic Multilingual Plane are represented as UTF-16 surrogate pairs where the compiler or conversion routines support them, and string indexing still sees two 16-bit elements.
SizeOf( WString ) returns the number of bytes used by one WString element for the current target.
WString is useful for calling wide-character APIs and for text that should be processed with FreeBASIC wide-string routines. For portable file formats, network protocols, and stored data, prefer an explicit encoding such as UTF-8 and convert at the boundary where needed.
When processing source files, FreeBASIC can parse ASCII source with Unicode escape sequences (\u or \U), or source files saved as UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, or UTF-32BE when the file has a Byte Order Mark (BOM). For broad portability, plain ASCII or UTF-8 source without relying on target-specific wide-character width is usually the safest choice.
The FreeBASIC text file functions can read and write Unicode files in different encodings when Encoding is specified when the file is opened. The data is converted between the file encoding and the target's internal WString representation.
When allocating dynamic memory for a WString, prefer CAllocate or otherwise make sure the buffer is initialized or assigned immediately. A manually allocated WString buffer without a zero terminator is not a valid zero-terminated string.
Pointer note: *pw, where pw is a Wstring Ptr, can be interpreted either as a WString expression or as a reference to one wide-character element depending on context. If the other operand is numeric, *pw is treated as the element pointed to by pw. Use parentheses when the intent matters. For example, (*pw)[n] indexes the pointed-to string, while pw[n] indexes the pointer as an array of WString elements.
WString follows the target wide-character model used by the runtime and C/CRT declarations.
Syntax
Description
A WString is a fixed-size array of wide-character elements. It has no descriptor and does not resize automatically. If a WString value is declared with a fixed size, that size includes the terminating zero element, so the usable text capacity is size - 1 elements. When assigning to a fixed-size WString, FreeBASIC truncates the assigned text as needed so that the terminator still fits.
A Wstring Ptr points at a zero-terminated wide-character buffer. Pointer-based WString storage must be allocated, reallocated, and freed explicitly with Allocate, CAllocate, Reallocate, and Deallocate.
The end of a WString is marked by element value 0. The FreeBASIC string handling routines append that terminator when creating or assigning WString data, and they calculate the length by scanning for the first zero element. Embedded zero elements therefore terminate the visible string for the normal WString operations.
For a WString, Len returns the number of stored wide-character elements before the first zero terminator. SizeOf returns the number of bytes reserved by the variable when that storage size is known by the compiler, such as a fixed-size WString variable. SizeOf cannot recover the original allocation size from a dereferenced pointer or from a ByRef argument.
The size and meaning of one WString element depends on the target. Do not assume that WString is always UTF-16, always UTF-32, or always a complete Unicode scalar value per element. On targets with 16-bit wide characters, values outside the Basic Multilingual Plane are represented as UTF-16 surrogate pairs where the compiler or conversion routines support them, and string indexing still sees two 16-bit elements.
SizeOf( WString ) returns the number of bytes used by one WString element for the current target.
WString is useful for calling wide-character APIs and for text that should be processed with FreeBASIC wide-string routines. For portable file formats, network protocols, and stored data, prefer an explicit encoding such as UTF-8 and convert at the boundary where needed.
When processing source files, FreeBASIC can parse ASCII source with Unicode escape sequences (\u or \U), or source files saved as UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, or UTF-32BE when the file has a Byte Order Mark (BOM). For broad portability, plain ASCII or UTF-8 source without relying on target-specific wide-character width is usually the safest choice.
The FreeBASIC text file functions can read and write Unicode files in different encodings when Encoding is specified when the file is opened. The data is converted between the file encoding and the target's internal WString representation.
When allocating dynamic memory for a WString, prefer CAllocate or otherwise make sure the buffer is initialized or assigned immediately. A manually allocated WString buffer without a zero terminator is not a valid zero-terminated string.
Pointer note: *pw, where pw is a Wstring Ptr, can be interpreted either as a WString expression or as a reference to one wide-character element depending on context. If the other operand is numeric, *pw is treated as the element pointed to by pw. Use parentheses when the intent matters. For example, (*pw)[n] indexes the pointed-to string, while pw[n] indexes the pointer as an array of WString elements.
Example
Dim As WString * 13 str1 => "hello, world"
Print str1
Print Len(str1) 'returns 12, the number of stored Wstring elements
Print SizeOf(str1) 'returns 13 * sizeof(wstring), the bytes reserved by str1
Print str1
Print Len(str1) 'returns 12, the number of stored Wstring elements
Print SizeOf(str1) 'returns 13 * sizeof(wstring), the bytes reserved by str1
Dim As WString Ptr str2
str2 = CAllocate( 13 * SizeOf(WString) )
If str2 = 0 Then End 1
*str2 = "hello, world"
Print *str2
Print Len(*str2) 'returns 12, the number of stored Wstring elements
Deallocate str2
str2 = CAllocate( 13 * SizeOf(WString) )
If str2 = 0 Then End 1
*str2 = "hello, world"
Print *str2
Print Len(*str2) 'returns 12, the number of stored Wstring elements
Deallocate str2
Platform Differences
WString follows the target wide-character model used by the runtime and C/CRT declarations.
- On DOS, WString elements are byte-sized. The DOS port does not provide a full Unicode wide-character environment, so portable Unicode code should not rely on DOS WString storage.
- On Android in this tree, wchar_t and WString elements are byte-sized. Prefer UTF-8 String or ZString storage for portable Android text unless a specific API requires otherwise.
- On Windows targets, including Win32, Win64, and Windows ARM64, WString elements are 16-bit UTF-16 code units. Xbox and Cygwin also use 16-bit wide-character elements in this tree. Len and indexing count code units, not user-perceived characters.
- On most other Unix-like targets, including Linux, the BSD targets, macOS/Darwin, Solaris/illumos, Haiku, and Wii, WString elements are 32-bit signed wide-character values.
- For C interop, include the appropriate CRT headers and use the target's wchar_t declarations instead of assuming a fixed width.
Dialect Differences
- Not available in the -lang qb dialect unless referenced with the alias __Wstring.
Differences from QB
- New to FreeBASIC
See also