Type Iteration (Keywords)

Type Iteration with Keywords

BambooBasic provides special keywords to navigate and manipulate the instance list: First, Last, Before, After, and Insert.

First - Get First Instance

Use First TypeName to get the first instance in the list:

Type TPlayer
    Field name:String
    Field score:Int
EndType

Function Main()
    ; Create players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"
    p1\score = 100

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"
    p2\score = 250

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"
    p3\score = 175

    ; Get the first player created
    Local firstPlayer:TPlayer = First TPlayer
    Print "First player: " & firstPlayer\name  ; Output: Alice

    Return False
EndFunction

Returns: The first instance, or Null if no instances exist.

Last - Get Last Instance

Use Last TypeName to get the last instance in the list:

Function Main()
    ; Create players (same as above)
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"

    ; Get the last player created
    Local lastPlayer:TPlayer = Last TPlayer
    Print "Last player: " & lastPlayer\name  ; Output: Charlie

    Return False
EndFunction

Returns: The last instance, or Null if no instances exist.

After - Get Next Instance

Use After instance to get the instance that comes after a specific instance:

Function Main()
    ; Create players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"

    ; Get first player
    Local firstPlayer:TPlayer = First TPlayer
    Print "First: " & firstPlayer\name  ; Alice

    ; Get the player after Alice
    Local secondPlayer:TPlayer = After firstPlayer
    Print "Second: " & secondPlayer\name  ; Bob

    ; Get the player after Bob
    Local thirdPlayer:TPlayer = After secondPlayer
    Print "Third: " & thirdPlayer\name  ; Charlie

    Return False
EndFunction

Returns: The next instance in the list, or Null if this is the last instance.

Before - Get Previous Instance

Use Before instance to get the instance that comes before a specific instance:

Function Main()
    ; Create players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"

    ; Get last player
    Local lastPlayer:TPlayer = Last TPlayer
    Print "Last: " & lastPlayer\name  ; Charlie

    ; Get the player before Charlie
    Local secondLast:TPlayer = Before lastPlayer
    Print "Second to last: " & secondLast\name  ; Bob

    ; Get the player before Bob
    Local firstPlayer:TPlayer = Before secondLast
    Print "First: " & firstPlayer\name  ; Alice

    Return False
EndFunction

Returns: The previous instance in the list, or Null if this is the first instance.

Manual Iteration with After

You can manually iterate using First and After:

Function Main()
    ; Create players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"
    p1\score = 100

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"
    p2\score = 250

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"
    p3\score = 175

    Print "=== Manual Iteration ==="

    ; Start at first
    Local current:TPlayer = First TPlayer

    ; Loop until we reach the end
    While current <> Null
        Print current\name & ": " & ToString(current\score)
        current = After current  ; Move to next
    Wend

    Return False
EndFunction

Output:

=== Manual Iteration ===
Alice: 100
Bob: 250
Charlie: 175

Null Checking

Always check for Null when using navigation keywords:

Function Main()
    ; Create only two players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"

    ; Get last player
    Local last:TPlayer = Last TPlayer

    ; Try to go beyond the list
    Local beyondLast:TPlayer = After last

    If beyondLast = Null
        Print "No player after the last one!"
    Else
        ; This won't execute
        Print "Found: " & beyondLast\name
    EndIf

    Return False
EndFunction

Insert - Add Instance at Position

Use Insert instance After/Before other to insert an instance at a specific position in the list:

Function Main()
    ; Create three players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"
    p1\score = 100

    Local p2:TPlayer = Create TPlayer
    p2\name = "Charlie"
    p2\score = 175

    Local p3:TPlayer = Create TPlayer
    p3\name = "David"
    p3\score = 200

    Print "=== Original List ==="
    Local player:TPlayer
    For player EachIn TPlayer
        Print player\name
    Next

    ; Create a new player
    Local newPlayer:TPlayer = Create TPlayer
    newPlayer\name = "Bob"
    newPlayer\score = 250

    ; Insert Bob after Alice
    Insert newPlayer After p1

    Print ""
    Print "=== After Inserting Bob ==="
    For player EachIn TPlayer
        Print player\name
    Next

    Return False
EndFunction

Output:

=== Original List ===
Alice
Charlie
David
Bob
=== After Inserting Bob ===
Alice
Bob
Charlie
David

Note: New instances are normally added to the end. Insert lets you control the position.

Insert Before

Function Main()
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"

    Local p2:TPlayer = Create TPlayer
    p2\name = "Charlie"

    ; Insert Bob before Charlie
    Local bob:TPlayer = Create TPlayer
    bob\name = "Bob"

    Insert bob Before p2

    Print "=== Player List ==="
    Local player:TPlayer
    For player EachIn TPlayer
        Print player\name
    Next

    ; Output: Alice, Bob, Charlie

    Return False
EndFunction

Priority Queue Example

Type TTask
    Field description:String
    Field priority:Int  ; Higher = more important
EndType

Function AddTask(desc:String, pri:Int)
    Local newTask:TTask = Create TTask
    newTask\description = desc
    newTask\priority = pri

    ; Find where to insert based on priority
    Local task:TTask = First TTask

    ; If list is empty, just create (already done)
    If task = Null
        Return
    EndIf

    ; Find the right position
    While task <> Null
        If pri > task\priority
            ; Insert before this task
            Insert newTask Before task
            Return
        EndIf
        task = After task
    Wend

    ; If we got here, it has lowest priority (already at end)
EndFunction

Function ShowTasks()
    Local task:TTask

    Print "=== Task List (by priority) ==="
    For task EachIn TTask
        Print "[" & ToString(task\priority) & "] " & task\description
    Next
EndFunction

Function Main()
    ; Add tasks with various priorities
    AddTask("Write documentation", 3)
    AddTask("Fix critical bug", 5)
    AddTask("Refactor code", 2)
    AddTask("Update tests", 4)
    AddTask("Add new feature", 1)

    ShowTasks()

    Return False
EndFunction

Output:

=== Task List (by priority) ===
[5] Fix critical bug
[4] Update tests
[3] Write documentation
[2] Refactor code
[1] Add new feature

Finding Middle Instance

Function GetMiddlePlayer:TPlayer()
    ; Count total players
    Local count:Int = 0
    Local p:TPlayer
    For p EachIn TPlayer
        count = count + 1
    Next

    ; Find middle index
    Local middleIndex:Int = count / 2

    ; Navigate to middle
    Local current:TPlayer = First TPlayer
    For i:Int = 0 To middleIndex - 1
        current = After current
    Next

    Return current
EndFunction

Function Main()
    ; Create 5 players
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"

    Local p4:TPlayer = Create TPlayer
    p4\name = "David"

    Local p5:TPlayer = Create TPlayer
    p5\name = "Eve"

    Local middle:TPlayer = GetMiddlePlayer()
    Print "Middle player: " & middle\name  ; Output: Charlie

    Return False
EndFunction

Reverse Iteration

Function ShowPlayersReverse()
    Print "=== Players (Reverse Order) ==="

    Local current:TPlayer = Last TPlayer

    While current <> Null
        Print current\name & ": " & ToString(current\score)
        current = Before current  ; Move backward
    Wend
EndFunction

Function Main()
    Local p1:TPlayer = Create TPlayer
    p1\name = "Alice"
    p1\score = 100

    Local p2:TPlayer = Create TPlayer
    p2\name = "Bob"
    p2\score = 250

    Local p3:TPlayer = Create TPlayer
    p3\name = "Charlie"
    p3\score = 175

    ShowPlayersReverse()

    Return False
EndFunction

Output:

=== Players (Reverse Order) ===
Charlie: 175
Bob: 250
Alice: 100

Key Points

First TypeName - Returns first instance (or Null if empty)
Last TypeName - Returns last instance (or Null if empty)
After instance - Returns next instance (or Null if at end)
Before instance - Returns previous instance (or Null if at start)
Insert instance After/Before other - Insert at specific position
Always check for Null when navigating
Instance list maintains creation order (unless modified with Insert)
Can manually iterate using First/Last and Before/After
Insert allows custom ordering (priority queues, sorting, etc.)

See Also

Custom Types - Defining Types
Type Instances - Creating and removing instances
Type Iteration (Loops) - For EachIn and For Each In
Control Flow - While loops

Examples

See the TypeIteration.bam example for complete demonstrations.