FreeBasic ZString Keyword

last modified June 16, 2025

The FreeBasic ZString keyword represents a null-terminated ASCII string type. It is compatible with C-style strings and is often used for interoperability with external libraries.

Basic Definition

In FreeBasic, ZString is a string type that stores characters in ASCII format and is terminated by a null character (ASCII 0). This makes it compatible with C strings.

ZString variables are fixed-length by default but can be used with pointers for dynamic strings. They are ideal for working with Windows API functions and other external libraries that expect C-style strings.

Declaring ZString Variables

This example shows how to declare and initialize ZString variables.

zstring_declare.bas

Dim greeting As ZString * 20 = "Hello, there!"
Dim emptyString As ZString * 10

Print greeting
Print Len(greeting)
Print emptyString

Here we declare two ZString variables. The first is initialized with a string literal and has space for 20 characters. The second is empty with space for 10 characters. The Len function returns the actual string length.

ZString with Pointers

ZString pointers allow working with dynamic null-terminated strings.

zstring_pointer.bas

Dim pz As ZString Ptr
pz = Allocate(50)

*pz = "FreeBasic ZString Example"

Print *pz
Print Len(*pz)

Deallocate(pz)

This example demonstrates dynamic ZString allocation. We allocate memory, assign a string, and print it. Always deallocate memory when done. Pointer syntax allows flexible string manipulation.

ZString in Function Parameters

ZString is commonly used for function parameters when interfacing with C.

zstring_function.bas

Declare Function CountVowels Alias "count_vowels" (ByVal s As ZString Ptr) As Integer

Function CountVowels(s As ZString Ptr) As Integer
    Dim count As Integer = 0
    Dim i As Integer = 0
    
    While (*s)[i] <> 0
        Select Case LCase((*s)[i])
            Case "a", "e", "i", "o", "u"
                count += 1
        End Select
        i += 1
    Wend
    
    Return count
End Function

Dim text As ZString * 50 = "Programming in FreeBasic"
Print "Vowel count: "; CountVowels(@text)

This shows a function that counts vowels in a ZString. The parameter is a ZString pointer. We iterate through characters until the null terminator. The @ operator gets the address of the ZString variable.

ZString Array

Arrays of ZStrings can store multiple fixed-length strings efficiently.

zstring_array.bas

Dim days(7) As ZString * 10 = _
{ _
    "Sunday", "Monday", "Tuesday", "Wednesday", _
    "Thursday", "Friday", "Saturday" _
}

For i As Integer = 0 To 6
    Print days(i)
Next

Here we create an array of 7 ZStrings, each with space for 10 characters. We initialize them with day names. The array provides efficient storage for multiple fixed-length strings.

Converting Between String and ZString

FreeBasic allows conversion between String and ZString types.

zstring_conversion.bas

Dim fbString As String = "FreeBasic String"
Dim zs As ZString * 50 = fbString

Print "Original String: "; fbString
Print "Converted ZString: "; zs

Dim backToString As String = zs
Print "Back to String: "; backToString

This demonstrates converting between String and ZString. The assignment automatically handles the conversion. Note that ZString has a fixed buffer size while String is dynamic.

ZString with Windows API

ZString is essential when calling Windows API functions that expect C strings.

zstring_winapi.bas

#Include Once "windows.bi"

Declare Function MessageBoxA Lib "user32.dll" _
    (ByVal hWnd As Integer, ByVal lpText As ZString Ptr, _
     ByVal lpCaption As ZString Ptr, ByVal uType As Integer) As Integer

Dim message As ZString * 100 = "This is a ZString message"
Dim title As ZString * 50 = "ZString Demo"

MessageBoxA(0, @message, @title, 0)

This example shows using ZString with the Windows API MessageBox function. We declare the function with ZString pointer parameters and pass addresses of our ZString variables using @ operator.

ZString vs String

This table compares ZString and String types in FreeBasic:

Feature	ZString	String
Termination	Null-terminated	Length-prefixed
Encoding	ASCII	UTF-16 or ASCII
Memory	Fixed size	Dynamic
C Compatibility	Yes	No
Default	No	Yes

Best Practices

Buffer Size: Always allocate enough space for ZString buffers.
Null Termination: Ensure strings are properly null-terminated.
API Calls: Use ZString for Windows API and external libraries.
Conversion: Convert to String for complex string operations.
Pointers: Use ZString pointers for dynamic string handling.

This tutorial covered the FreeBasic ZString 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