Arrays and Collections

Arrays

Rockstar supports JavaScript-style arrays. Arrays are zero-based, and dynamically allocated when values are assigned using numeric indexes. Array elements are initialised to null; passing an out-of-range index returns mysterious:

Absolution at 0 is "Intro"
Absolution at 1 is "Apocalypse Please"
My favourite is 7
Absolution at my favourite is "Hysteria"
Absolution at 2 + 3 is "Stockholm Syndrome"

Print Absolution at 0 (prints: Intro)
Print Absolution at 7 (prints: Hysteria)
Print Absolution at 2 (prints: null)
Print Absolution at 999 (prints: mysterious)

Array indexers can be primary values or arithmetic expressions, but you can’t use a logical expression as an array indexer.

Consider My array at 2 is 4

If not for this restriction, the parser would consume 2 is 4 as a comparison (“2 is 4 - true or false?”), return false, try to set My array at false and then blow up ‘cos there’s nothing to put in it.

Returning an array in a numeric context will return the current length of the array:

Let the array at 5150 be "Van Halen".
Print the array + 0 (prints: 5151)
Print the array at 0 (prints: null)

Rock my array with 1, 2, 3
The counter is 0
While the counter ain't my array
Print "Counting " with the counter
Build the counter up, yeah

(prints:
Counting 0
Counting 1
Counting 2)

Under the hood, a Rockstar array actually contains two collections, known as the list and the hash. The list is an integer-indexed linear list of values; when you push, pop, rock and roll arrays, you’re modifying the list. If you set elements whose key is not a non-negative integer, those elements are stored in the hash.

Array indexes can be of any type, and you can mix key types within the same array. The array length only considers keys whose values are non-negative integers:

My string is "s"
My decimal is 1.2
My negative is -4
My boolean is true

The array at my string is "Sweet"
The array at my decimal is "Child"
The array at my negative is "O"
The array at my boolean is "Mine"

Print the array
(prints: [ "s": "Sweet"; 1.2: "Child"; -4: "O"; true: "Mine" ])

The array at 0 is "Whoa"
Print the array
(prints: [ "Whoa"; "s": "Sweet"; 1.2: "Child"; -4: "O"; true: "Mine" ])

Arrays in Rockstar are one-dimensional, but they can contain other arrays:

My string is "s"
My decimal is 1.2
My negative is -4
My boolean is true

The array at my string is "Sweet"
The array at my decimal is "Child"
The array at my negative is "O"
The array at my boolean is "Mine"

Print the array
(prints: [ "s": "Sweet"; 1.2: "Child"; -4: "O"; true: "Mine" ])

The array at 0 is "Whoa"
Print the array
(prints: [ "Whoa"; "s": "Sweet"; 1.2: "Child"; -4: "O"; true: "Mine" ])

You can use indexes to read characters from strings, and extract bits from numbers. You can also use indexers to modify individual characters in a string:

X is 43605. Index is 0
Until index is 16
If x at index write 1 else write 0
Index is with 1
end (writes: 1010101001010101)

The string is "Han Valen"
The string at 0 is "V"
The string at 4 is "H"
Shout the string (prints: Van Halen)

X is 0. Print X (prints: 0)
X at 0 is true. Print X. (prints: 1)
X at 2 is true. Print X. (prints: 5)
X at 4 is true. Print X. (prints: 21)

Trying to assign an indexed value to an existing variable which is not an array will cause an error:

The truth takes nothing giving nothing
The truth at 1 is 2
(runtime error: The truth is not an indexed variable)

Looping over arrays

To loop over the list elements of an array, use for <value> in <array> If you also need the index of each element, use for <value> and <index> in <array>:

Rock ints with 9, 8, 7

For int in ints
Write int with "!"
yeah
(writes: 9!8!7!)

For int and index in ints write index with ":" with int with ", "
(writes: 0:9, 1:8, 2:7, )

The storm is silent
Rock the storm like Buenos Aires 
Rock the storm like raging thunder
Rock the storm like guitar hellfire
Rock the storm like tearin' asunder
Shatter the storm into the sky

For every star in the sky
Write the star
Yeah
(writes: ACDC)

To loop over the hash elements of an array, use for <key> of <array> - this will call the loop once for each element in the hash, setting key to the key of that element. If you need the element values as well, use for <key> and <value> of <array>:

Hash at "a" is 1
Hash at "b" is true
Hash at false is "nope"

For value and key of hash
Write key with ":" with value with " "
End
(writes: a:1 b:true false:nope )

Vixen at "vocals" is "Janet"
Vixen at "guitar" is "Jan"
Vixen at "bass" is "Share"
Vixen at "drums" is "Roxy"

For every member and role of Vixen
Shout the member with " (" with the role with ")"
Yeah

(prints:
Janet (vocals)
Jan (guitar)
Share (bass)
Roxy (drums))

This can lead to some slightly odd-sounding lyrics:

For star in the sky
Whisper star
Yeah

so you can use the every keyword, which will prepend the to the variable names assigned inside the body of the loop:

For every star in the sky
Whisper the star
Yeah

Queue operations

Rockstar arrays can also be created and manipulated by the queue operations rock and roll. push and pop are supported for Rockstar developers who are into 80s dance music.

Pushing elements onto an array

To create a new empty array, push or rock the name of the array. To push an element onto the end of the array, push <array> <expression>.

Rock my array
Print my array (prints: [ ])
Rock my array with 123
Print my array (prints: [ 123 ])
Print my array at 0 (prints: 123)
Roll my array into the result
Print the result (prints: 123)
Print my array (prints: [ ])

You can rock list expressions, so you can push multiple elements onto the end of an array:

Rock Tommy "yeah!". Rock Tommy 12345. Rock Tommy true
Rock Tommy like a renegade razorblade
Rock Tommy with nothing
Rock Tommy with lies
Rock Tommy 5, 6, 7, 8
Shout Tommy + 0 (prints: 10)

While Tommy ain't nothing
Roll Tommy into the fire
Write the fire; write ", ", yeah
(writes: yeah!, 12345, true, 180, null, false, 5, 6, 7, 8, )

If it makes for better lyrics, you can use the with keyword - rock <array> with <expression>. Remember the with keyword is context-sensitive, so in this example:

Rock ints with 1, 2 with 3, 4, 5
          ^         ^
          |         +-- this 'with' is the binary addition operator
          |
          +------------ this 'with' is part of the array push syntax

(ints is now [ 1, 5, 4, 5 ])

This syntax is very useful for initialising strings without using string literals - see below. It also means that the following is valid Rockstar:

The Scorpions say here I am
Rock you like a hurricane

Shout it at 0
Shout it at 1

Popping elements from an array

The roll keyword will remove the first element from an array and return the element that was removed.

Rock ints with 1, 2, 3
Print roll ints (prints: 1)
Print pop ints (prints: 3)
Print roll ints (prints: 2)
Print pop ints (prints: mysterious)

The string is "abcde"
Roll the string into the letter
Print the letter (prints: a)
Print the string (prints: bcde)

roll can be used in assignments:

Rock ints with 1, 2, 3
Let the first be roll ints
Let the second be roll ints
Let the third be roll ints
Shout the first (prints: 1)
Shout the second (prints: 2)
Shout the third (prints: 3)

Rockstar also supports a special roll x into y syntax for removing the first element from an array and assigning it to a variable:

Rock the list with 4, 5, 6
Roll the list into foo
Roll the list into bar
Roll the list into baz
Shout foo (prints: 4)
Shout bar (prints: 5)
Shout baz (prints: 6)

Array Arithmetic

As with strings, Rockstar tries hard to return something in every scenario, just in case one day somebody out there finds it useful.

Adding arrays to numbers adds the length of the array (this is the same logic that kicks in when you test an array to see if there’s anything left in it.) Adding anything else to an array will append it to the end of the array.

Rock my array with 1, 2, 3
Put my array with "rock!" into Array B
Put my array with true into Array C
Put my array with null into Array D
Put my array with 5 into the number

Shout my array  (prints: [ 1, 2, 3 ])
Shout Array B (prints: [ 1, 2, 3, "rock!" ])
Shout Array C (prints: [ 1, 2, 3, true ])
Shout Array D (prints: [ 1, 2, 3, null ])
Shout the number (prints: 8)

Subtracting arrays from arrays will return a new array, created by removing any elements in the second array from the elements of the first.

• List elements are removed if the value is present
• Hash elements will be removed if they match both the key and the value.

Subtracting any other value from an array returns a new array with any instances of the subtracted element removed.

Rock ABBA with "Agnetha", "Anni-Frid", "Benny" 'n' "Björn"
Rock the guys with "Björn" & "Benny"

Shout ABBA without the guys (prints: [ "Agnetha", "Anni-Frid" ])
Put ABBA without "Benny" with "Lemmy" into Abbahead
Shout ABBA (prints: [ "Agnetha", "Anni-Frid", "Benny", "Björn" ])
Shout Abbahead (prints: [ "Agnetha", "Anni-Frid", "Björn", "Lemmy" ])

Let Rush at "guitars" be "Alex"
Let Rush at "drums" be "Neil"
Let Rush at "bass" be "Geddy"
Shout Rush (prints: [ "guitars": "Alex"; "drums": "Neil"; "bass": "Geddy" ])

Let Testament at "guitars" be "Alex"
Shout Rush without Testament (prints: [ "drums": "Neil"; "bass": "Geddy" ])