List type

A list contains multiple values of the same type. To create a list you just have to wrap a number of values in square brackets.

a list of numbers: [ 1, 2, 3 ]
a list of text: [ "red", "green", "blue" ]

You can declare lists in any of your rules. If you want to use the same list in various places, you can for example put it in a value component. 

Input

A list can also be used as input for a rule. It works the same for them as for any other value:

Input or [1, 2, 3]

In this example, if input contains a list, that list is used – otherwise the list [1,2,3] is used.

This example only works when input is a list. By default, the input is of the same type as the rule, so the easiest way to change the type of input is to change the outcome of the rule. For example, start with the rule [1, 2, 3] to turn the rule (and its input) into a list, then you can change the rule to Input or [1, 2, 3] .
In a value component, you also have the option to change the type of the input directly with the input type field. In this example, the required type would be List<Number>

Input lists can be modified with signals & slots in various ways: you can add, remove or change items or replace the entire list.

Signals & slots can only modify an input list, not a list declared in a rule.

If the input is empty, it is not considered a list and thus you cannot add items to it. Therefore, if you want to be able to modify a list input with Signals & slots, you should provide a default input list – an empty list [] works too.

Empty Lists ([])

You can create a list without any items in it with a pair of square brackets ([]).

Empty lists only work in places where the type of the list can be inferred!

A common use case is to use an empty list as starting point of a value component. First, ensure that the component returns a list of some kind, e.g. the rule [1] would produce a list of numbers. Now that the component and its input are lists, you can use the empty list syntax in your rule:

Input or []

The empty list will be of the same type as the input, a list of numbers in our example. This also works in more complex scenarios, for example if you are working with a list of records the following pattern may be useful:

Input or
if false then
  // sample format
  [
    { 
	  id: "item-1",
	  name: "this is an example for a list of records",
	  price: 13.37,
	  description: "these values will never be used (due to 'if false'), they are just examples",
	  options: [ 3, 4, 5],
	  language: [ "de", "en" ],
	  parts: [{
		id: "part-1",
		name: "nested lists and records also work",
		price: 0.815
	  }]
	}
  ]
else 
  []
end 

In this example, we have a list of records that describe some imaginary products. The list is meant to store all records (products) that a user chooses, so we have to use the input variable for that. As starting point, we want to use an empty list. Now we have to describe the record in some way. We could directly write the type into the input type field (which would start like this: List<Record<{id=Text,name=Text,price=Number,...) but that is not very convenient.

Instead, we can provide an example record that will not be used, but allows the system to infer the type of the record and list that we want to use. To achieve this, we can simply put the example record into an if false then expression. The empty list in the else case will then automatically be a list of such records too.

Initially, or when we want to add new columns to our record, or change existing ones, we can simply change the example record and the type of the empty list and the rule itself will update automatically. There is one caveat though: we must temporarily remove or comment the first line in the example (Input or), so that the type of the input variable can be updated too. Otherwise it will remain set to the current type and cause an error.

Functions

length

Returns the number of items in the list.

get(index)

Returns the item at the specified index.

Any numerical index returns a list item, based on these rules:

• The first item has index 1, but 0 also returns it.

• When the index is negative, items are counted from right to left.

• When the index is greater than the number of items in the list, it is automatically capped.

• If the list contains no items, Empty is returned. Check the length of the list to explicitly handle this case.

contains(item)

Returns true if a list contains the specified item.
When looking for items, contains uses the default equality operator as defined by the type of items in the list.
In the example, the list contains text items and by default texts are compared in a case-sensitive fashion. That is why "Blue" cannot be found, but "blue" can.