List
List operations on data values: get, push, insert, remove, slice, sort, unique, flatten, join, range, sum, minimum, maximum, mean, shuffle and more.
- Data
- Since 0.2.0
- list
- array
- splice
- sort
- unique
- join
- sum
- range
- data
List reads, edits and summarises lists of values.
What it does#
The list input is read as a list (a single value becomes a one-item list). Operation chooses what to do with it. Some operations need an item: it comes from the b input or, when b is not connected, from the node's B text field, read as JSON when it parses (72, [1, 2]) and as text otherwise. Index and Count come from the parameters; a connected index input overrides Index.
| Operation | Result |
|---|---|
| Length, First, Last, Get | a number or one element (Get uses Index; no value out of range) |
| Push, Prepend | the list with B added at the end or the start |
| Pop, Shift | the list without its last or first element |
| Insert, Set | B inserted at Index, or the element at Index replaced by B |
| Remove | Count elements removed from Index |
| Slice, Take, Drop | Count elements from Index, the first Count, or all but the first Count |
| Concatenate | the list followed by B |
| Reverse, Sort ascending, Sort descending | the reordered list |
| Unique, Compact | duplicates removed, or empty values removed |
| Flatten | nested lists opened Count levels deep (0 opens all) |
| Join | text with B (a comma by default) between elements |
| Index of | position of B, or -1 |
| Range | Count numbers starting at Index |
| Sum, Minimum, Maximum, Mean | a number from the numeric elements |
| Shuffle | the list in a random order set by Seed |
Negative Index counts from the end. Sort puts numbers before text, numbers in numeric order and text by character, and keeps equal elements in their original order. Lists are limited to 4 096 items.
When to use it#
Use it to keep a list of notes or settings, to pick one element, to tidy imported data (Unique, Compact, Sort) or to reduce a list to one number (Sum, Mean, Maximum). Use String Split to turn text into a list and Join here to turn it back.
Ports#
| Port | Direction | Signal | Lanes |
|---|---|---|---|
list | Input | Data (any) | 1 |
b | Input | Data (any) | 1 |
index | Input | Data (any) | 1 |
value | Output | Data (any) | 1 |
Parameters#
| Parameter | Label | Range | Default | Unit | Scale | Notes |
|---|---|---|---|---|---|---|
op | Operation | 0 to 28 | 0 | linear | List operation; b and index are its arguments. Choices: 0 Length, 1 Get, 2 First, 3 Last, 4 Push, 5 Prepend, 6 Pop, 7 Shift, 8 Insert, 9 Remove, 10 Set, 11 Slice, 12 Concatenate, 13 Reverse, 14 Sort ascending, 15 Sort descending, 16 Unique, 17 Flatten, 18 Compact, 19 Join, 20 Index of, 21 Range, 22 Sum, 23 Minimum, 24 Maximum, 25 Mean, 26 Shuffle, 27 Take, 28 Drop. | |
index | Index | -4096 to 4096 | 0 | linear | Position while the index port is unconnected; negative counts from the end. Shown when op is 1 or 8 or 9 or 10 or 11 or 21. | |
count | Count | 0 to 4096 | 1 | linear | Items removed, sliced, flattened, generated, taken or dropped. Shown when op is 9 or 11 or 17 or 21 or 27 or 28. | |
seed | Seed | 0 to 65535 | 0 | linear | Seed for Shuffle, so the order is reproducible. Shown when op is 26. |
b: text.
Operation (op)#
The list operation, a discrete choice. See the table above for what each one does and which fields it uses.
Index (index)#
An element position from -4 096 to 4 096. 0 is the first element and -1 the last. Used by Get, Insert, Remove, Set and Slice, and as the first number for Range. A value on the index input replaces it.
Count (count)#
A number of elements from 0 to 4 096: how many Remove takes out, Slice keeps (0 keeps the rest), Take keeps, Drop skips and Range makes, or how many levels Flatten opens (0 opens all).
Seed (seed)#
From 0 to 65 535. Shuffle mixes the list in an order set by Seed and by how many times it has run, so a recording replays the same way.
Tips#
- To sort a list, use Sort ascending or Sort descending; chain Unique first to drop repeats.
- Sum, Minimum, Maximum and Mean ignore elements that are not numbers, so a mixed list still gives a number.
- Splice is Remove followed by Insert: remove Count elements at Index, then insert B at the same Index.
- Join with B set to
/turns["kick", "snare"]intokick / snare.
See also#
Help patches
Each help patch is an ordinary Toy that teaches one idea. The diagram shows the Patch; the preview shows its Frame. Open it in TuneToys to play and edit it.
1. Build a list
beginner Teaches: op, index, count
A list of note numbers edited with Get, Push, Insert, Remove, Slice and Range.
Connections as text
- Oscillator audio output connected to Patch outputs audio input
- Value value output connected to List list input
- Value parses the JSON text [60, 64, 67] into a list. Push appends B (72).
- Insert puts B at Index; Remove takes Count items from Index. Negative Index counts from the end.
- Range ignores the input and makes Count numbers starting at Index.
- Data cables carry values, not sound. Select a data node to see its newest value in the inspector; the tone only keeps the Toy audible.
2. Sort, unique and sum
intermediate Teaches: op
Duplicates removed from a list, then sorted or summarised.
Connections as text
- Oscillator audio output connected to Patch outputs audio input
- Value value output connected to List “tidy” list input
- List “tidy” value output connected to List “result” list input
- Unique keeps the first of each value: [5, 3, 1, 8].
- Sort ascending gives [1, 3, 5, 8]; Sum gives 17; Mean gives 4.25.
- Sum, Minimum, Maximum and Mean skip anything that is not a number.
- Data cables carry values, not sound. Select a data node to see its newest value in the inspector; the tone only keeps the Toy audible.
Related nodes
- Value A literal source, the data domain's number box and message box.
- String Text operations on data values: length, case, trim, split, replace, slice, pad, repeat, search, regular expressions, format and JSON.
- Math Arithmetic on data values, with the same operations as signal Math. Numbers in, numbers out; lists are worked element by element.