FreeBasic WString Keyword

last modified June 16, 2025

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. Each character occupies 2 bytes (UTF-16 encoding), allowing 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

Print greeting
Print Len(greeting)  ' Returns 9 (8 characters + null terminator)
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 byte length.

WString with Unicode Characters

WString can store characters from various writing systems and symbols.

wstring_unicode.bas

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

Print text

For i As Integer = 0 To Len(text) - 1
    Print Hex(AscW(text[i])); " ";
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 AscW function returns the Unicode value.

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 = WStr("Wide text: 测试")

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

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

Print convertedWide
Print convertedAscii
Print Len(convertedAscii)  ' Note: May lose information

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"

Declare Function MessageBoxW Lib "user32" _
    (ByVal hWnd As Integer, ByVal lpText As WString, _
     ByVal lpCaption As WString, ByVal uType As Integer) As Integer

Dim title As WString = WStr("WString Demo")
Dim message As WString = 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 = WStr("FreeBasic ")
Dim ws2 As WString = WStr("WString操作")

' Concatenation
Dim combined As WString = 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

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 = WStr("File content: ❤☀☆☂☻♞")

' Write UTF-16 (little-endian) with BOM
Open filename For Binary Access Write As #1
Put #1, , WChr(&hFEFF)  ' Write UTF-16 BOM
Put #1, , content
Close #1

' Read back
Dim readContent As WString
Open filename For Binary Access Read As #1
Seek #1, 3  ' Skip BOM (2 bytes) + null terminator
Get #1, , readContent
Close #1

Print readContent

This demonstrates writing and reading WString to a file with UTF-16 encoding. We include a BOM (Byte Order Mark) for proper encoding identification. Note the careful handling of byte positions when reading.

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