{{fbdoc item="title" value="WSTRING"}}----
Standard data type: wide character string

{{fbdoc item="syntax"}}##
	[[KeyPgDim|dim]] //variable// [[KeyPgAs|as]] **Wstring** * //size//
	[[KeyPgDim|dim]] //variable// [[KeyPgAs|as]] **Wstring** [[KeyPgPtr|ptr]]
##
{{fbdoc item="desc"}}
	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 ##[[KeyPgAllocate|Allocate]]##/##[[KeyPgReallocate|Reallocate]]##/##[[KeyPgDeallocate|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**##, ##[[KeyPgLen|Len]]## returns the size of the contained string and ##[[KeyPgSizeof|Sizeof]]## returns the space allocated to the ##**Wstring**##.  ##[[KeyPgSizeof|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 ##[[KeyPgByref|Byref]]## function argument.
	
	This type is provided for support non-Latin based alphabets. Any intrinsic string function like ##[[KeyPgLeft|Left]]## will work with ##**Wstring**##s 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).
	
	The ""FreeBASIC"" text file functions can read and write Unicode files in different encodings, provided the ##[[KeyPgEncoding|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.
	
	##[[KeyPgSizeof|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 ##[[KeyPgCallocate|Callocate]]## (or at worst, to use ##[[KeyPgAllocate|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]##').

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/datatype/wstring.bas"}}%%(freebasic)
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
%%

{{fbdoc item="filename" value="examples/manual/datatype/wstring2.bas"}}%%(freebasic)
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
%%

{{fbdoc item="target"}}
	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 ##[[KeyPgWstring|Wstrings]]## will behave as standard ASCII ##[[KeyPgZstring|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.

{{fbdoc item="lang"}}
	- Not available in the //[[CompilerOptlang|-lang qb]]// dialect unless referenced with the alias ##**""__Wstring""**##.

{{fbdoc item="diff"}}
	- New to ""FreeBASIC""

{{fbdoc item="see"}}
	- ##[[KeyPgString|String]]## (data type)
	- ##[[KeyPgZstring|Zstring]]## (data type)
	- ##[[KeyPgStringFunction|String]]## (function)
	- ##[[KeyPgWstringFunction|Wstring]]## (function)
	- ##[[KeyPgWspace|Wspace]]##
	- ##[[KeyPgWstr|Wstr]]##
	- ##[[KeyPgWchr|Wchr]]##
	- ##[[KeyPgWbin|Wbin]]##
	- ##[[KeyPgWhex|Whex]]##
	- ##[[KeyPgWoct|Woct]]##
	- ##[[KeyPgWinput|Winput()]]##
	- ##[[TblVarTypes|Standard Data Type Limits]]##
	- ##[[KeyPgExtendsWstring|Extends Wstring]]##

{{fbdoc item="back" value="CatPgStdDataTypes|Standard Data Types"}}{{fbdoc item="back" value="CatPgString|String Functions"}}