Sequences - BambooBasic

Sequences

A Sequence is a general-purpose list. It holds basic data types (Int, Double, String) or your own Elements (value records). You can have as many Sequences as you like, store them in variables, pass them around, and iterate them.

Types are never held in a Sequence. A Type is a tracked entity with its own internal list (EachIn, First, Last). When you want records in a list of your own, that's exactly what an Element is for – Local x:Sequence Of TSomeType is a compile error, on purpose.

Declaring a Sequence

Use Sequence Of <Type>. Each Sequence holds a single element type:

Local scores:Sequence Of Int
Local names:Sequence Of String
Local mobs:Sequence Of Particle    ' Particle is an Element

A new Sequence starts empty. Adding a value of the wrong type is a compile-time error.

Adding and Inserting

SeqAdd appends to the end, SeqAddFirst prepends, and SeqInsert places a value at an index (existing items shuffle up). Indexes are zero-based.

Local scores:Sequence Of Int
SeqAdd scores, 10        ' -> 10
SeqAdd scores, 20        ' -> 10, 20
SeqAddFirst scores, 5    ' -> 5, 10, 20
SeqInsert scores, 1, 7   ' -> 5, 7, 10, 20

Reading and Writing

SeqGet returns the element at an index, SeqSet overwrites it, and SeqLength returns the number of elements.

Print "Count: " & ToString(SeqLength(scores))
Print "Item 2: " & ToString(SeqGet(scores, 2))
SeqSet scores, 0, 99   ' replace index 0

Removing

SeqDeleteAt removes by index, SeqDelete removes the first element matching a value, and SeqClear empties the Sequence.

SeqDeleteAt scores, 0   ' remove index 0
SeqDelete scores, 20    ' remove the value 20
SeqClear scores         ' now empty

Note: SeqDelete, SeqContains and SeqFind compare by value. For primitives that's the obvious thing; for a Sequence of Elements, two elements are equal when all their fields match.

Iterating with EachSeq

The EachSeq ... NextSeq loop walks every element in order. The loop variable is declared for you, and for Element Sequences it is a reference – so you can edit elements in place.

Local names:Sequence Of String
SeqAdd names, "Alice"
SeqAdd names, "Bob"

EachSeq name In names
    Print name
NextSeq

Sequences of Elements

This is what Sequences are really for. An Element is a value record; a Sequence Of that Element owns its elements outright – they are copied in, and they vanish when removed. No references, no cleanup.

Element Particle
    Field x:Int
    Field y:Int

    Method Show()
        Print "(" & ToString(this\x) & "," & ToString(this\y) & ")"
    EndMethod
EndElement

Function Main()
    Local pts:Sequence Of Particle

    Local a:Particle
    a\x = 5
    a\y = 5
    SeqAdd pts, a          ' 'a' is COPIED into the sequence

    ' EachSeq gives a REFERENCE - edits happen in place
    EachSeq p In pts
        p\x = p\x + 10
    NextSeq

    ' Value semantics: the original 'a' is untouched
    a\Show()               ' still (5,5) - the sequence holds a copy

    Return False
EndFunction

So SeqAdd copies an element in, EachSeq lets you edit the stored elements in place, and SeqGet hands back a copy. The Sequence is the owner throughout.

Finding and Testing

You can search by value. For a Sequence of Elements, "equal" means all fields match:

Print SeqContains(nums, 10)   ' 1 if present, 0 if not
Print SeqFind(nums, 20)       ' index, or -1 if not found
Print SeqIsEmpty(nums)        ' 1 if empty, 0 if not

Removing from the ends

Local first:Int = SeqRemoveFirst(nums)   ' remove and return the first
Local last:Int  = SeqRemoveLast(nums)    ' remove and return the last

Reversing and Sorting

SeqReverse reverses in place. SeqSort sorts in place, ascending by default; pass False for descending. Primitive Sequences sort by natural order:

SeqReverse nums
SeqSort nums          ' ascending
SeqSort nums, False   ' descending

To sort a Sequence of Elements, give the Element a Compare method that returns a negative number, zero, or a positive number (only the sign matters). SeqSort uses it automatically; an Element without one is a compile-time error.

Element Particle
    Field x:Int
    Field y:Int

    Method Compare:Int(other:Particle)
        Return (this\x + this\y) - (other\x + other\y)
    EndMethod
EndElement

' ... fill a Sequence Of Particle called pts ...
SeqSort pts          ' ascending by x+y
SeqSort pts, False   ' descending

Arrays and Swapping

Convert between a Sequence and a normal array, and swap two Sequences wholesale:

Local arr:Int[] = SeqToArray(nums)   ' copy the Sequence into an array
SeqFromArray nums, arr               ' replace the Sequence contents from an array

Local other:Sequence Of Int
SeqAdd other, 99
SeqSwap nums, other                  ' exchange the contents of the two Sequences

Keyword Reference

Local x:Sequence Of <Int|Double|String|Element>   Declare a Sequence

SeqAdd       seq, value        Append value to the end
SeqAddFirst  seq, value        Prepend value to the start
SeqInsert    seq, index, value Insert value at index
SeqSet       seq, index, value Overwrite the element at index
SeqDelete    seq, value        Remove the first element equal to value
SeqDeleteAt  seq, index        Remove the element at index
SeqClear     seq               Remove all elements
SeqReverse   seq               Reverse the order in place
SeqSort      seq [, ascending] Sort in place (Elements need a Compare method)
SeqSwap      seqA, seqB        Exchange the contents of two Sequences
SeqFromArray seq, array        Replace the Sequence contents from an array

SeqGet(seq, index)             Return the element at index
SeqLength(seq)                 Return the number of elements
SeqIsEmpty(seq)                1 if the Sequence has no elements
SeqContains(seq, value)        1 if an equal value is present
SeqFind(seq, value)            Index of an equal value, or -1
SeqFirst(seq) / SeqLast(seq)   The first / last element
SeqNext(seq)  / SeqBefore(seq) Walk the internal cursor
SeqRemoveFirst(seq)            Remove and return the first element
SeqRemoveLast(seq)             Remove and return the last element
SeqToArray(seq)                Return the elements as an array

EachSeq item In seq            Iterate every element in order
    ...
NextSeq

Key Points

A Sequence holds basic data types or Elements – never Types
Declare with Sequence Of Type; one element type per Sequence; indexes are zero-based
Elements are stored by value – the Sequence owns them, and copies them on add
EachSeq gives a reference, so you can edit Element fields in place; SeqGet returns a copy
SeqSort needs a Compare method on the Element; primitives sort naturally
SeqDelete/SeqContains/SeqFind compare by value – for Elements, "equal" means all fields match
An empty Sequence iterates zero times (not an error)

See Also

Elements - the value records a Sequence is built to hold
Arrays - fixed-size indexed storage
Custom Types - tracked entities (with their own list, not for Sequences)

Examples

See Sequences.bam for a full tour, and Bullets.bam for the classic "spaceship fires bullets" pattern using a Sequence of Elements.