Arrays and Collections

Arrays

Rockstar supports JavaScript-style arrays, with array elements accessed using the at keyword. 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" ])

Nested Arrays

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

To initialise an empty array, rock the array.

Be careful modifying arrays inside functions! rock the array (with no parameters) will always declare a new empty array in the current function scope, even if the array is already a global variable – but if you rock the array with 1 and the array exists in global scope, your function will modify it, not create a new one.

MakeLocalArray takes number
Rock array (this will always declare a new, empty array)
Rock array with number
Give back array
Yeah

ModifyGlobalArray takes number
rock array with number (this will mutate a global variable if one exists)
give back array
yeah

Call MakeLocalArray with 1 into array1
Call MakeLocalArray with 2 into array2

Call ModifyGlobalArray with 3 into array3
Call ModifyGlobalArray with 4 into array4

Rock array
(array is now a global variable, so the next two calls
to ModifyGlobalArray will mutate it, not create new ones)

Call ModifyGlobalArray with 5 into array5
Call ModifyGlobalArray with 6 into array6

Print array1 (prints: [ 1 ])
Print array2 (prints: [ 2 ])
Print array3 (prints: [ 3 ])
Print array4 (prints: [ 4 ])
Print array5 (prints: [ 5, 6 ])
Print array6 (prints: [ 5, 6 ])

To put an empty array inside another array, rock my array at 1; to populate a nested array, rock my array at 1 using 2, 3, 4:

Rock my array
Print my array (prints: [ ])

Rock my array at 1
Print my array (prints: [ null, [ ] ])

Rock your array at 1 using 2, 3, 4
Print your array (prints: [ null, [ 2, 3, 4 ] ])

Rock her array at "key" using "a", "b", "c"
Print her array (prints: [ "key": [ "a", "b", "c" ] ])

The array at 1 at 2 at 3 is "yeah"
Print the array at 1 at 2 at 3 (prints: yeah)
Print the array (prints: [ null, [ null, null, [ null, null, null, "yeah" ] ] ])

The words at 2 is "Slash"
Print the words at 2 at 0 (prints: S)
Print the words at 2 (prints: Slash)
Print the words (prints: [ null, null, "Slash" ])

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)

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 <value> of <array> - this will call the loop once for each element in the hash, setting value to the value of that element. If you need the element keys as well, use for <value> and <key> 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 element in the array print the element
For every value and key of the hash print the key with ":" with the value

For every star in the sky
Whisper the star, yeah

For every beat of my heart
Whisper the beat, baby

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" ])