FreeBasic WString Keyword

Last modified October 18, 2026

The FreeBasic WString keyword represents a wide string data type that can store Unicode characters. WString is essential for working with international text and symbols beyond ASCII.

Basic Definition

In FreeBasic, WString is a built-in data type for Unicode strings. The size of each character is platform dependent: on Windows a WString character occupies 2 bytes (UCS-2), while on Linux it occupies 4 bytes (UCS-4), matching wchar_t on that platform. Either way, it allows representation of characters from various languages and symbols.

WString variables are null-terminated like regular strings but can handle extended character sets. They're particularly useful for internationalization and when working with Windows API functions that expect wide strings.

Declaring WString Variables

This example shows how to declare and initialize WString variables.

wstring_declare.bas

Dim greeting As WString * 50 = WStr("Hello, 世界!")
Dim emptyWString As WString * 50

Print greeting
Print Len(greeting)  ' Returns 10 (number of characters in the string)
Print emptyWString   ' Prints nothing

Here we declare a fixed-length WString with space for 50 characters and initialize it with a Unicode string. The WStr function converts a string literal to WString format. Note that Len returns the number of characters, not bytes; Sizeof returns the number of bytes allocated for the variable.

WString with Unicode Characters

WString can store characters from various writing systems and symbols.

wstring_unicode.bas

Dim text As WString * 200 = WStr("FreeBasic supports: ")
text += WStr("日本語, Русский, Ελληνικά, العربية")

Print text

For i As Integer = 0 To Len(text) - 1
    Print Hex(Asc(text, i + 1)); " ";
Next

This example demonstrates WString's ability to handle multiple scripts. We concatenate strings using += and print the Unicode code points of each character. The Asc function, given a position, returns the Unicode code point of the character at that position.

Converting Between String and WString

FreeBasic provides functions to convert between String and WString types.

wstring_conversion.bas

Dim asciiText As String = "ASCII text"
Dim wideText As WString * 50 = WStr("Wide text: 测试")

' Convert String to WString
Dim convertedWide As WString * 50 = WStr(asciiText)

' Convert WString to String
Dim convertedAscii As String = Str(wideText)

Print convertedWide
Print convertedAscii
Print Len(convertedAscii)  ' Length in bytes of the converted String

This shows conversion between string types. WStr converts from String to WString, while Str converts back. Be aware that converting to String may lose Unicode characters not in the current code page.

WString with Windows API

WString is particularly useful when calling Windows API functions.

wstring_winapi.bas

#Include Once "windows.bi"

Dim title As WString * 50 = WStr("WString Demo")
Dim message As WString * 50 = WStr("This is a Unicode message: ☺")

MessageBoxW(0, message, title, 0)

This example demonstrates using WString with Windows API. We declare the Unicode version of MessageBox (MessageBoxW) which expects WString parameters. The message includes a Unicode smiley character that wouldn't work with String.

WString Operations

WString supports many of the same operations as regular String.

wstring_operations.bas

Dim ws1 As WString * 50 = WStr("FreeBasic ")
Dim ws2 As WString * 50 = WStr("WString操作")

' Concatenation
Dim combined As WString * 200 = ws1 + ws2

' Comparison
If ws1 < ws2 Then
    Print "ws1 comes first"
End If

' Substring
Print Mid(combined, 10, 3)  ' Prints "WSt"

' Searching
Print InStr(combined, WStr("操作"))  ' Prints position

This shows common string operations with WString. Note that comparison is based on Unicode code point values. Mid and InStr work similarly to their String counterparts but handle wide characters correctly.

WString Arrays

Arrays of WString can be useful for storing multiple Unicode strings.

wstring_array.bas

Dim languages(3) As WString * 50

languages(0) = WStr("English")
languages(1) = WStr("Español")
languages(2) = WStr("Français")
languages(3) = WStr("日本語")

For i As Integer = 0 To 3
    Print languages(i)
Next

This example creates an array of WString to store language names in their native scripts. Each element can contain Unicode characters, and we can process them like any other array.

WString and File I/O

Reading and writing WString to files requires special consideration.

wstring_file.bas

Dim filename As String = "unicode.txt"
Dim content As WString * 50 = WStr("File content: ❤☀☆☂☻♞")

' Write the raw WString data (in the platform's internal wide format)
Open filename For Binary Access Write As #1
Put #1, , content
Close #1

' Read back
Dim readContent As WString * 50
Open filename For Binary Access Read As #1
Get #1, , readContent
Close #1

Print readContent

This demonstrates writing and reading WString to a file. The data is written in the platform's internal wide format (4 bytes per character on Linux, 2 bytes on Windows), not as a UTF-16 text file with a BOM. To write a real Unicode text file with a specific encoding, use the text file functions and specify the encoding when opening the file.

Best Practices

Use WString when working with Unicode text or Windows API
Be consistent with string types in your application
Handle conversions carefully to avoid data loss
Consider encoding when reading/writing files
Use WStr for WString literals

This tutorial covered the FreeBasic WString keyword with practical examples showing its usage in different scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all FreeBasic Tutorials.

Ebooks