FreeBasic ByVal Keyword

last modified June 16, 2025

The FreeBasic ByVal keyword specifies that a parameter should be passed by value to a function or subroutine. When passed by value, the function receives a copy of the original data.

Basic Definition

In FreeBasic, ByVal is the default parameter passing mechanism. It means the called function gets its own copy of the parameter's value.

Changes made to ByVal parameters inside the function don't affect the original variable. This provides safety but may have performance overhead for large data structures.

Simple ByVal Example

This basic example demonstrates passing a parameter by value.

byval_simple.bas

Sub ModifyValue(ByVal x As Integer)
    x = x * 2
    Print "Inside function: "; x
End Sub

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

The original num remains unchanged after the function call. The function works with its own copy of the value. This shows how ByVal protects the original variable from modification.

ByVal with Strings

Strings can also be passed by value in FreeBasic.

byval_string.bas

Sub ProcessString(ByVal s As String)
    s = "Modified: " & s
    Print "Inside function: "; s
End Sub

Dim text As String = "Original"
Print "Before function: "; text
ProcessString(text)
Print "After function: "; text

The original string remains unchanged. The function modifies its local copy. String passing by value is safe but may involve memory allocation overhead.

ByVal with Arrays

Arrays are typically passed by reference, but we can use ByVal with pointers.

byval_array.bas

Sub ProcessArray(ByVal arr As Integer Ptr)
    ' Can access array elements but cannot change the pointer
    Print "First element: "; arr[0]
    arr[0] = 100 ' Modifies original array
End Sub

Dim numbers(2) As Integer = {1, 2, 3}
ProcessArray(@numbers(0))
Print "After function: "; numbers(0)

Here we pass an array pointer by value. The function can modify array contents but cannot change where the pointer points. The original array gets modified through the pointer.

ByVal with User-Defined Types

User-defined types can be passed by value, creating a full copy.

byval_udt.bas

Type Point
    x As Integer
    y As Integer
End Type

Sub MovePoint(ByVal pt As Point)
    pt.x = pt.x + 10
    pt.y = pt.y + 10
    Print "Inside function: "; pt.x, pt.y
End Sub

Dim origin As Point
origin.x = 0
origin.y = 0
Print "Before function: "; origin.x, origin.y
MovePoint(origin)
Print "After function: "; origin.x, origin.y

The original Point structure remains unchanged. The function works with a complete copy of the structure. For large structures, this may impact performance.

ByVal vs ByRef Comparison

This example contrasts ByVal and ByRef parameter passing.

byval_vs_byref.bas

Sub ByValExample(ByVal x As Integer)
    x = x * 2
End Sub

Sub ByRefExample(ByRef x As Integer)
    x = x * 2
End Sub

Dim value As Integer = 5
ByValExample(value)
Print "After ByVal: "; value

value = 5 ' Reset value
ByRefExample(value)
Print "After ByRef: "; value

The ByVal version doesn't modify the original, while ByRef does. This clearly shows the difference between passing by value and by reference. Choose ByVal when you want to protect the original variable.

ByVal with Function Return Values

Functions can return values that are then passed ByVal to other functions.

byval_function.bas

Function GetNumber() As Integer
    Return 42
End Function

Sub PrintNumber(ByVal n As Integer)
    Print "The number is: "; n
End Sub

PrintNumber(GetNumber())

The function return value is passed ByVal to PrintNumber. This demonstrates how return values are automatically treated as ByVal parameters when used in function calls.

ByVal with Pointers

Pointers can be passed by value, creating a copy of the pointer itself.

byval_pointer.bas

Sub ModifyPointer(ByVal ptr As Integer Ptr)
    Dim temp As Integer = 100
    ptr = @temp ' Only changes local copy
    Print "Inside function: "; *ptr
End Sub

Dim value As Integer = 5
Dim p As Integer Ptr = @value
Print "Before function: "; *p
ModifyPointer(p)
Print "After function: "; *p

The original pointer remains unchanged. The function modifies its local copy of the pointer. The original pointed-to value remains accessible.

Best Practices

Default behavior: Remember ByVal is default in FreeBasic.
Small data: Use ByVal for small, simple data types.
Safety: Prefer ByVal when you want to protect original data.
Performance: Avoid ByVal for large structures.
Clarity: Explicitly use ByVal when it's important for readability.

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