Arrays

On this page

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

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

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

index (position) to insert the value to (similar to Array splice in JavaScript)

Visual representation of inserting a value into an array by index

You can insert other strings and numbers into an array, but not another array or object, unless you use Set Button Variable command instead.

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

You can also use Variable Delete command and populate it with yourArrayName[valueIndex] to remove a value, both commands will achieve the same.

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.

The value you're trying to find needs to be an exact match (case sensitive) to the array value.

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.

Need to add weights? Create a second array with the same name +_weight added to its name and add values that will act as weights (chances to happen) to add to the randomization.

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.

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.

Parsing an array that's directly within another array is not supported.

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"]`
`["Hello", "Hi", {"MyObject": [1, 2, 3]}]`
`["Lioran", "Melonax", ["cat", "rabbit", "dog"]]`	The inner array does NOT get parsed.

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.

Value box can only contain a string if you are using the concat operator. All the other operators need numbers (the command will skip any string in the array).

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