Arrays

Edit

Introduction #

What’s an array? #

Array is a special variable which can hold more than one value at a time.
If you have a list of items (for example viewer names), storing them in single variables would look like this:

  • var name1 = “wolbee”
  • var name2 = “Silverlink”
  • var name3 = “Sebas”

This seems quite inefficient if you happen to have a lot of names to store. The answer is to store them all in an array, which can hold many values under a single name: names = ["wolbee", "Silverlink", "Sebas"].

Representation of an array
Representation of an array

Array manipulation #

If you want to retrieve a specific value (element) from an array, you can use the following formatting:
arrayName[position]
If we have an array names = ["wolbee", "Silverlink", "Sebas"], typing names[1] would retrieve 'Silverlink' (the first value of an array has position of 0).
Array position (also called index) can contain other variables or complex math, too.

Some command boxes allow you to use not only position, but also top for retrieving and manipulating values in an array. Selecting top will target a value at the END of an array (last index). 0 will target a value at the BEGINNING of an array (index of 0).

Array is cleared every time you close or reset SAMMI. If you wish to save it in a file, you can use Stringify Array and INI: Save Text commands.

Convert stacks saved in .ini files from LB1 to arrays in SAMMI #

If you’re using the same .ini files from LioranBoard 1, you will notice that your stringified stacks don’t get properly parsed when loaded back into SAMMI (they end up being objects instead of arrays).

Use this Stack to Array converter button:

Import JSON button


Edit

Create Array #

Creates a new empty array.
You can populate it with Array Insert command.

Box Name Type Description
Array Name String Name of the new array


Edit

Array Insert #

Inserts a value into an array in a specific index (position), shifting other values to the right.
Supports setting the array value directly to objects/arrays without having to parse and stringify them.

The position you can insert the value to can be:

  • top - adds a value to the end of the array (same as Array push in Javascript)

    Add a value to the end of the stack
    Add a value to the end of the stack
  • 0 - adds a value to the beginning of the array (same as Array unshift in Javascript)

    Add a value to the beginning of the stack
    Add a value to the beginning of the stack
  • index (position) to insert the value to (similar to Array splice in JavaScript)

    Visual representation of inserting a value into an array by index
    Visual representation of inserting a value into an array by index
Box Name Type Description
Array Name String Name of the array
Insert Position Position to add the value to. Can be top , 0 or index (position) of the value.
Value To Insert Value you want to add to the array


Edit

Array Replace #

Replaces a value inside an array, overriding the previous one. Position of all values remains the same.
Supports setting the array value directly to objects/arrays without having to parse and stringify them.

Box Name Type Description
Array Name String Name of the array
Replace Position Position to replace the value at. Can be top , 0 or index (position) of the value.
Value Value you want to replace the current value with


Edit

Array Pull #

Pulls a value from an array by removing it from the array and saving it inside the selected variable. All remaining array value will be shifted by one.

Box Name Type Description
Array Name String Name of the array
Pull Position Position to pull the value from. Can be top , 0 or index (position) of the value.
Save Variable As String Variable name to save the pulled value to.


Edit

Array Remove #

Removes a value from an array from a specified index (position), shifting other values to the right.
This is similar to Array splice() method in JavaScript.

Visual representation of removing a value from an array
Visual representation of removing a value from an array
Box Name Type Description
Array Name String Name of the array
Delete Position Position to delete the value at. Can be top , 0 or index (position) of the value.


Edit

Array Find Value #

Finds the first instance of a given value inside the array and returns its index(position) in the array.
Returns -1 if value was not found.

Box Name Type Description
Array Name String Name of the array to search for the value
Save Array Position As String Name of the variable to save the index(position) of the found value
Find value The value to find in the array
Find value array Result
“blue” [“yellow”,”red”,”blue”,”orange”,”blue”] 2
“blue” [“yellow”,”red”,”blue cat”,”orange”] -1 (not found)
“blue” [“yellow”,”Blue”,”blue cat”,”blue”] 3


Edit

Array Random #

Returns a random value inside an array.
Very useful for displaying a random image or playing a random sound.
The randomization will happen with an equal chance for each value.

Box Name Type Description
Array Name String Name of the stack
Save Variable As String Variable name to save the random value into
Save Variable As (position) String (optional) You can enter another variable name if you wish to get the index(position) of the random value in the array


Edit

Array Sort #

Sorts an array alphabetically or numerically (depending on its values) in an ascending/descending order.
If you have a mix of real and string values in your array, it will sort it based on the first array value.

Box Name Type Description
Array Name String Name of the array you want to sort
Ascending Checkbox Checked = sort in ascending order, unchecked = sort in descending order


Edit

Array Shuffle #

Shuffles an array, randomizing the order of every value in it.

Box Name Type Description
Array Name String Name of the array you want to shuffle


Edit

Array Get Size #

Returns the size of the array (= how many items it holds) and saves it into the given variable.
Returns 0 if the array is empty.

Box Name Type Description
Array Name String Name of the array
Save Variable As String Variable name to save the size of the array


Edit

Array Concat #

Joins two arrays together. Appends another array at the end of first array.
Both arrays must already exist.

Array Concat Visual Representation
Array Concat Visual Representation
Box Name Type Description
Array Name String The array to append to
Array To Transfer String The array to append at the end of the first array


Edit

Stringify Array #

Returns a JSON string of the whole array.
You can use this command together with File: Save String command to save the whole array into a file. Once loading it back from the file, you can use Parse Array/Object command to turn the JSON string back into the original array.

Box Name Type Description
Save Variable As String Variable to save the JSON string of the array into
Array Name String Name of the array to stringify


Edit

Parse Array/Object #

Turns a JSON string into an array/object. Must be properly formatted (SAMMI will give you a warning if it finds any formatting errors).
This way you can easily create a prepopulated object/array, as it supports nesting.
Read more about JSON syntax at w3schools.com.

Box Name Type Description
Array/Object Name String Name of the variable to save the parsed array/object into
String Array/JSON JSON String JSON string to parse
JSON string before conversion Result saved in the variable
["Lioran", "Melonax", "Cyanidesugar"] Parsed JSON string
["Hello", "Hi", {"MyObject": [1, 2, 3]}]
["Lioran", "Melonax", ["cat", "rabbit", "dog"]] The inner array does NOT get parsed. Parsed JSON string


Edit

Array Format to String #

Creates and returns a new string by concatenating all of the elements in an array, separated by a specified separator string.

Box Name Type Description
Array Name String Name of your array
Separator String How the values of the array are being separated
Save Variable As String Variable to save the string as


Edit

Array Filter #

Saves in an array all the number values (of the original array) matching the specified criteria.

Box Name Type Description
New Array Name String Name of the array to save the matching values.
Array Name String Name of the array to filter.
Compare Dropdown menu Operator you wish to use to compare the array values with.
Variable/Number Number to compare the array values with.
Array Compare Type Number Returned Array
[1,2,3,4,5,6,7] > 5 [6,7]
[25,38,100,22,6] <= 25 [25,22,6]
[“text”,1,2,3,”more text”] > 2 [3]


Edit

Array Map #

Saves in an array the result of doing math with every value of the original array.

Box Name Type Description
New Array Name String Name of the array to save the returned array.
Array Name String Name of the array to do math.
Operator Dropdown menu Operator you wish to use on the array values.
Value Value to do Math.
Array Operator Value Returned Array
[1,2,3,4,5,6,7] += 5 [6,7,8,9,10,11,12]
[1,2,3,4] concat ” player” [1 player,2 player,3 player,4 player]


Edit

Array Get Value #

Similar to ‘Array Pull’ but without removing the value from the array.

Box Name Type Description
Array Name String Name of the array.
Pull Position Position to get the value at. Can be top , 0 or index (position) of the value.
Save Variable As String Variable name the response will be saved to.


Edit

Array Clear #

Clears all the contents of an array, leaving it empty. Does not delete the array itself, you must use Delete Variable command for that instead.

Box Name Type Description
Array Name String Array name you wish to clear