# 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-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

    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

## 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

- String (data type)
- ZString (data type)
- String (function)
- WString (function)
- WSpace
- WStr
- WChr
- WBin
- WHex
- WOct
- WInput()
- Standard Data Type Limits
- Extends WString