Arrays are collections of values stored in a single variable. BambooBasic supports both single-dimensional and multi-dimensional arrays.

Arrays are declared using square brackets with the size:

; Array of 10 integers (indices 0-9)
Local numbers:Int[10]

; Array of 5 strings
Local names:String[5]

; Array of 100 doubles
Local temperatures:Double[100]

Access elements using zero-based indices:

Local scores:Int[5]

; Set values
scores[0] = 100
scores[1] = 95
scores[2] = 87
scores[3] = 92
scores[4] = 88

; Read values
Print "First score: " & ToString(scores[0])
Print "Last score: " & ToString(scores[4])

You can initialize arrays with values:

Local days:String[7]
days[0] = "Monday"
days[1] = "Tuesday"
days[2] = "Wednesday"
days[3] = "Thursday"
days[4] = "Friday"
days[5] = "Saturday"
days[6] = "Sunday"

For loop:

Local scores:Int[5]
scores[0] = 100
scores[1] = 95
scores[2] = 87
scores[3] = 92
scores[4] = 88

For i:Int = 0 To 4
    Print "Score " & ToString(i) & ": " & ToString(scores[i])
Next

Calculate array length:

Local numbers:Int[10]
Local arraySize:Int = 10

For i:Int = 0 To arraySize - 1
    numbers[i] = i * 10
    Print numbers[i]
Next

BambooBasic supports multi-dimensional arrays (2D, 3D, 4D, and beyond) with natural indexing syntax.

Important: Multi-dimensional arrays use dynamic allocation and support natural bracket notation.

2D Array (like a grid):

; 4x5 grid (4 rows, 5 columns)
Local grid:Int[4][5]

; Set values using natural indexing
grid[0][0] = 1
grid[2][3] = 99
grid[3][4] = 100

; Access values
Local value:Int = grid[2][3]
Print value  ; Output: 99

3D Array:

; 3D space: 2 layers, 3 rows, 4 columns
Local space:Int[2][3][4]

; Access with [layer][row][column]
space[0][0][0] = 1
space[1][2][3] = 99
Local value:Int = space[1][2][3]
Print value  ; Output: 99

4D Array and Beyond:

; 4D array: 2x2x2x3
Local hyper:Int[2][2][2][3]

hyper[1][1][1][2] = 42
Print ToString(hyper[1][1][1][2])  ; Output: 42

; BambooBasic supports arrays of any dimensionality!

; Create and fill a 4x5 grid
Local grid:Int[4][5]

For row:Int = 0 To 3
    For col:Int = 0 To 4
        grid[row][col] = row * 10 + col
    Next
Next

; Print the grid
For row:Int = 0 To 3
    Local line:String = ""
    For col:Int = 0 To 4
        line = line & ToString(grid[row][col]) & " "
    Next
    Print line
Next

Key Features:

• Natural indexing: grid[row][col] - no manual offset calculation needed!
• All elements automatically zero-initialized
• Supports 2D, 3D, 4D, and higher dimensions
• Local multi-dimensional arrays use dynamic allocation for flexibility

Local colors:String[5]
colors[0] = "Red"
colors[1] = "Green"
colors[2] = "Blue"
colors[3] = "Yellow"
colors[4] = "Purple"

For i:Int = 0 To 4
    Print "Color " & ToString(i + 1) & ": " & colors[i]
Next

You can pass arrays to functions using array parameter syntax:

Function PrintArray(arr:Int[], size:Int)
    For i:Int = 0 To size - 1
        Print "Element " & ToString(i) & ": " & ToString(arr[i])
    Next
EndFunction

Function Main()
    Local numbers:Int[5]
    numbers[0] = 10
    numbers[1] = 20
    numbers[2] = 30
    numbers[3] = 40
    numbers[4] = 50

    PrintArray(numbers, 5)

    Return False
EndFunction

Multi-dimensional array parameters:

; 2D array parameter
Function Print2D(grid:Int[][], rows:Int, cols:Int)
    For r:Int = 0 To rows - 1
        For c:Int = 0 To cols - 1
            Print ToString(grid[r][c])
        Next
    Next
EndFunction

; 3D array parameter
Function Print3D(space:Int[][][], layers:Int, rows:Int, cols:Int)
    For z:Int = 0 To layers - 1
        For r:Int = 0 To rows - 1
            For c:Int = 0 To cols - 1
                Print ToString(space[z][r][c])
            Next
        Next
    Next
EndFunction

Function Main()
    Local myGrid:Int[3][4]
    ; ... fill grid ...
    Print2D(myGrid, 3, 4)
    Return False
EndFunction

Understanding how arrays are passed and returned is crucial for proper memory management:

Arrays are PASSED BY REFERENCE:

• When you pass an array to a function, you're passing a pointer/reference
• Modifications made inside the function affect the original array
• No copying occurs when passing
• The array is NOT deleted when the function ends
• Ownership remains with the caller

Function DoubleValues(arr:Int[][], rows:Int, cols:Int)
    ; Modify the array - affects the original!
    For r:Int = 0 To rows - 1
        For c:Int = 0 To cols - 1
            arr[r][c] = arr[r][c] * 2  ; Original is modified
        Next
    Next
EndFunction  ; arr is NOT deleted here

Function Main()
    Local myArray:Int[2][2]
    myArray[0][0] = 5

    DoubleValues(myArray, 2, 2)

    Print ToString(myArray[0][0])  ; Output: 10 (was modified)
    Return False
EndFunction

Arrays are RETURNED BY VALUE (Deep Copy):

• When a function returns an array, a deep copy is automatically created
• The original array inside the function is deleted
• The deep copy is returned to the caller
• No memory leaks - all cleanup is automatic

Function CreateMatrix:Int[][]()
    Local matrix:Int[2][3]
    ; ... fill matrix ...
    Return matrix
    ; What happens:
    ; 1. Deep copy of matrix is created
    ; 2. Original matrix is deleted
    ; 3. Deep copy is returned
EndFunction

Function Main()
    ; Receive the returned array
    Local myMatrix:Int[2][3] = CreateMatrix()
    ; What happens:
    ; 1. myMatrix is allocated
    ; 2. Function returns deep copy
    ; 3. Data is copied into myMatrix
    ; 4. Returned temporary is deleted
    ; 5. myMatrix owns its own independent copy

    ; myMatrix will be cleaned up when Main() ends
    Return False
EndFunction

Key Points:

• Pass by reference means modifications affect the original
• Return by value means each variable gets its own independent copy
• All memory management is handled automatically
• No manual cleanup needed - arrays are deleted when they go out of scope
• Returned arrays are independent - modifying one doesn't affect others

You can leverage the pass-by-reference and return-by-value semantics to create a simple array copy function:

Function CopyArray:Int[][](original:Int[][], rows:Int, cols:Int)
    ; Simply return the parameter - creates a deep copy!
    Return original
    ; How it works:
    ; 1. 'original' is passed by reference (no copy on pass)
    ; 2. Return creates automatic deep copy
    ; 3. Caller receives independent copy
EndFunction

Function Main()
    Local myArray:Int[2][3]
    ; ... fill myArray ...

    ; Create a complete copy
    Local copy:Int[2][3] = CopyArray(myArray, 2, 3)

    ; Modify the copy - doesn't affect original
    copy[0][0] = 999

    ; myArray and copy are now independent
    Return False
EndFunction

Why this works:

• The parameter is passed by reference (efficient, no copy on entry)
• The return creates a deep copy automatically
• You get a complete, independent copy of the array
• All memory is managed automatically

This pattern gives you an easy way to duplicate arrays without manual element-by-element copying!

• Array indices start at 0
• Accessing an index outside the array bounds causes undefined behavior (use Safe Build and Run (F6) to catch these errors)
• Arrays have a fixed size once declared
• All elements are initialized to default values (0 for numbers, "" for strings)
• Multi-dimensional arrays (2D, 3D, 4D+) use natural bracket indexing: grid[y][x]
• Local multi-dimensional arrays are dynamically allocated for flexibility
• Arrays can be passed to function parameters: Type[] for 1D, Type[][] for 2D, Type[][][] for 3D, etc.
• Arrays are passed by reference - modifications in functions affect the original
• Arrays are returned by value - a deep copy is automatically created when returning
• All memory management is automatic - no manual cleanup needed

Why Safe Build?

In standard C++ (and normal BambooBasic builds), arrays have no runtime bounds checking. This means accessing an array out of bounds causes undefined behavior:

Local arr:Int[5]
Local badIndex:Int = 10
arr[badIndex] = 99  ; Undefined behavior - may corrupt memory!

This code compiles and runs, but can:

• Corrupt other variables in memory
• Crash unpredictably
• Appear to work but fail later
• Be very difficult to debug

The Solution: Safe Build and Run

Press F6 or select Build -> Safe Build and Run to enable runtime bounds checking (as well as other runtime error trapping). This catches out-of-bounds errors immediately with clear error messages.

Example with Safe Build:

Function Main()
    Local arr:Int[5]
    arr[0] = 10
    arr[4] = 50  ; Valid - last element

    ; This will be caught:
    Local badIndex:Int = 10
    Print "Attempting arr[10]..."
    arr[badIndex] = 99  ; ERROR!

    Return False
EndFunction

Output with Safe Build:

Attempting arr[10]...
Array bounds error: arr[10] dimension 0 out of range [0, 4]

The error message shows:

• Array name: arr
• Invalid index: 10
• Dimension: 0 (first dimension)
• Valid range: [0, 4] (indices 0-4 are valid)

Works with Multi-Dimensional Arrays:

Local grid:Int[3][4]
Local x:Int = 5
grid[x][2] = 99  ; Caught: dimension 0 out of range

Output:

Array bounds error: grid[5][...] dimension 0 out of range [0, 2]

Performance Impact:

• Normal Build: Zero overhead - direct array access, no safety checks
• Safe Build: 2-5% slowdown for typical code, 10-20% for array-heavy code

When to Use Safe Build:

• Development and testing - Catch bugs early
• Debug builds - Find issues during development
• NOT for release builds - Use normal Build and Run (F5) for full performance

Technical Note:

Due to the runtime nature of bounds checking, error messages cannot show the exact line number in your BambooBasic source code. The checks occur in the generated C++ code at runtime, after compilation. However, the error message includes the array name and invalid index, which is usually sufficient to quickly locate the problem by searching your source code.

See the Arrays Examples folder for complete demonstrations:

• Arrays.bam - 1D array examples
• Arrays2D.bam - 2D grid with natural indexing
• Arrays3D.bam - 3D space arrays
• ArrayParameters.bam - Passing 1D, 2D, and 3D arrays to functions
• ArrayPassingAndReturning.bam - Demonstrates pass-by-reference and return-by-value (deep copy)

BambooBasic © 2026 Michael Denathorn