Lists

A list is an ordered collection of values. In System Modeler, lists are values like any other: they travel along wires, flow from node to node, and obey the same type rules as any other data. A wire that carries a list connects to any input port that accepts that list type. In other programming languages, the same concept is often called an array.

Lists are zero-indexed. The first item is at index 0, the second at index 1, and so on.

A list can hold any type of value: numbers, strings, booleans, geometry objects, or other lists.

Creating a list

The most direct way to create a list from individual values is the Merge Lists In Order node. Connect individual values or existing lists to its inputs and it assembles them into a single ordered list.

Lists also arise naturally from other operations:

A For-Each loop returns a Loop Results list (one entry per iteration)
Merge Lists combines two lists into one (optionally as a flat list or a list-of-lists)
Many System, Design, and Manufacture nodes return collections (for example, a list of BRep faces or a list of CAM operations)

Working with lists

The List category in the Base package provides nodes for the most common list operations.

Get List Size: Returns the number of items
Get First Item / Get Last Item: Retrieves the item at either end
Get Item By Index: Retrieves the item at a specific position
Contains List Item: Returns true if a value is present in the list
Reverse List: Reverses the order of items
Sort List Of Numbers / Sort List Of Strings: Sorts items in ascending or descending order, controlled by a property on the node
Merge Lists: Combines two lists into one. By default, each input list becomes a nested entry, producing a list-of-lists. Enable the Return a flat list property to flatten the result into a single list of individual items automatically. The node also has a Remove null entries property that filters out nulls from the merged result.
Merge Lists In Order: Assembles individual values or lists into a single ordered list. Use it to build a list from scratch by connecting individual items, or to combine existing lists into one sequence.
Flatten List: Collapses a list of lists into a single flat list. Use this when a Merge Lists node (without Return a flat list enabled) or a nested For-Each loop produces nested lists that downstream nodes expect as a flat sequence.
Convert Item To List: Wraps a single value in a one-item list
Convert List To String: Joins all items into a single formatted string
Is List Empty: Returns true if the list contains no items

Example

The List Operations sample graph from the Base package. Six constant nodes supply numbers to a Build List node, which produces an integer list. From there, wires branch to a Reverse node, a Sort node (set to ascending order), a Contains 23? node, and a Contains 50? node. Each result is converted to a string, labeled, and written to a Log Results node.

Base - List Operations

The example shows several of these nodes working together on the same list. One list output connects to five downstream nodes simultaneously. Each receives the same list and processes it independently. This illustrates a key property of lists: sharing a list between nodes doesn't consume it. Every connected node gets its own read of the same data.

Processing each item in a list

When you need to apply an operation to every item in a list individually, use a For-Each loop. The loop takes a list on its Items input, runs its inner graph once for each item, and collects the results into a Loop Results list.

The FOR-EACH and Subgraphs sample graph in the Base package shows this pattern in full: a list of numbers feeds into a FOR-EACH loop, the inner graph filters negatives using conditional logic, and Remove Nulls cleans up the output list before further processing.

See For-Each and While loops for how to build a For-Each loop.

Handling empty and null results

When a For-Each loop uses conditional logic to keep or discard items, discarded items often produce null instead of a value. The resulting Loop Results list contains a mix of values and nulls. Use Remove Nulls after the loop to produce a clean list of only the items that passed the condition.

Use Is List Empty to guard against an empty list reaching a node that requires at least one item. Pair it with a conditional or an error node to handle the empty case explicitly rather than letting a downstream node fail.