FreeBasic ByRef Keyword

Last modified October 18, 2026

The FreeBasic ByRef keyword is used to pass arguments by reference to procedures. When passed by reference, the procedure can modify the original variable's value. This differs from ByVal which passes a copy.

Basic Definition

In FreeBasic, ByRef is not the default for every type. In the default -lang fb dialect, built-in numeric types are passed ByVal by default, while String and user-defined Type parameters are passed ByRef by default. Arrays are always passed by reference and ByRef or ByVal is not allowed on them. When a parameter is passed by reference, the procedure receives a reference to the original variable rather than a copy of its value.

When a parameter is passed by reference, any changes made to the parameter within the procedure affect the original variable. This is useful when you need to modify multiple values or work with large data structures.

Basic ByRef Example

This simple example demonstrates how ByRef allows modifying the original variable.

byref_basic.bas

Sub Increment(ByRef value As Integer)
    value += 1
End Sub

Dim num As Integer = 5
Print "Before: "; num
Increment(num)
Print "After: "; num

Here we pass num by reference to the Increment subroutine. The subroutine modifies the original variable, increasing its value by 1. The change persists after the subroutine ends.

ByRef vs ByVal Comparison

This example contrasts ByRef with ByVal to show the difference in behavior.

byref_vs_byval.bas

Sub ModifyByRef(ByRef x As Integer)
    x = 100
End Sub

Sub ModifyByVal(ByVal x As Integer)
    x = 200
End Sub

Dim value As Integer = 10
ModifyByRef(value)
Print "After ByRef: "; value

value = 10
ModifyByVal(value)
Print "After ByVal: "; value

The ModifyByRef sub changes the original variable, while ModifyByVal only changes its local copy. The ByVal version has no effect on the original value variable.

Swapping Variables with ByRef

ByRef is commonly used to implement a swap operation between two variables.

byref_swap.bas

Sub SwapValues(ByRef a As Integer, ByRef b As Integer)
    Dim temp As Integer = a
    a = b
    b = temp
End Sub

Dim x As Integer = 10
Dim y As Integer = 20
Print "Before swap: x="; x; ", y="; y
SwapValues(x, y)
Print "After swap: x="; x; ", y="; y

The SwapValues procedure exchanges the values of two integer variables. The name Swap is avoided because it clashes with the built-in FreeBASIC Swap statement. Since both parameters are ByRef, the changes affect the original variables x and y in the calling code.

ByRef with Arrays

Arrays are always passed by reference in FreeBasic. Specifying ByRef or ByVal on an array parameter is a compile error.

byref_array.bas

Sub ModifyArray(arr() As Integer)
    arr(0) = 100
    arr(1) = 200
End Sub

Dim numbers(1) As Integer = {1, 2}
Print "Before: "; numbers(0); ", "; numbers(1)
ModifyArray(numbers())
Print "After: "; numbers(0); ", "; numbers(1)

This example shows that array modifications inside a procedure affect the original array. The ModifyArray procedure changes elements of the passed array without needing explicit ByRef keywords.

ByRef with Strings

Strings can be passed by reference to avoid creating unnecessary copies.

byref_string.bas

Sub AppendGreeting(ByRef s As String)
    s = "Hello, " + s
End Sub

Dim fname As String = "John"
Print "Before: "; fname
AppendGreeting(fname)
Print "After: "; fname

The AppendGreeting procedure modifies the original string variable by adding a greeting prefix. Using ByRef with strings is more efficient for large strings as it avoids copying the entire content.

ByRef with User-Defined Types

ByRef is particularly useful with large user-defined types to avoid copying.

byref_udt.bas

Type Person
    name As String
    age As Integer
End Type

Sub UpdatePerson(ByRef p As Person)
    p.age += 1
End Sub

Dim student As Person
student.name = "Alice"
student.age = 20
Print "Before: "; student.name; ", "; student.age
UpdatePerson(student)
Print "After: "; student.name; ", "; student.age

This example passes a Person structure by reference to UpdatePerson. The procedure increments the age field, and the change affects the original student variable. For large structures, ByRef is more efficient.

ByRef with Function Return Values

Functions can return a reference to a variable by declaring the return type with ByRef As, so the call can be assigned to directly.

byref_function.bas

Function MaxRef(ByRef a As Integer, ByRef b As Integer) ByRef As Integer
    If a > b Then Return a
    Return b
End Function

Dim x As Integer = 10
Dim y As Integer = 20
MaxRef(x, y) = 50
Print "x: "; x
Print "y: "; y

This advanced example shows a function returning a reference to the larger of two integers. We can then assign to this reference, modifying either x or y directly through the function's return value.

Best Practices

Clarity: Explicitly use ByRef or ByVal in parameter lists so the passing mode is obvious.
Modification: Only use ByRef when you need to modify the parameter.
Large Data: Use ByRef for large structures to avoid copying.
Safety: Be careful with ByRef to avoid unintended modifications.
Documentation: Document when parameters are modified by reference.

This tutorial covered the FreeBasic ByRef keyword with practical examples showing its usage in different scenarios. ByRef is powerful but should be used judiciously to maintain code clarity and safety.

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