31:T3b4b,32:T5a9,So far, whenever an operation has been applied to a some target cell, such as assigning it a value or cell reference, the result has been _added_ to the target's existing value. When the target cell is 0 prior to the operation (the default for all new list cells), the adding operation effectively assigns the new value to the target. But we are not limited to addition. _Action strands_ allow us to modify an operation to perform different actions, such as multiplication or division. In contrast to data strands, an action strand is defined by a hook that points either down or to the right and is positioned below the hook of the data strand it applies to. In general an action strand implies the following: ${tex`action(n, t)`} where some type of ${tex`action`} is applied to the value of the strand it is paired with (${tex`n \in N`}) and the target's existing value (${tex`t \in T`}). The type of action is determined by the numeric value of the action strand and the lexeme at the non-hook end of the strand. Below is a full list of action numbers and their associated behaviour. Actions can be applied to an individual pair of cells ${tex`n`} and ${tex`t`} (cell-to-cell); an individual cell ${tex`n`} paired with with an entire list ${tex`t_i`} (cell-to-list or λ mapping); or two lists ${tex`n_i`} and ${tex`t_i`} (list-to-list). The example list under each action shows its application to `N = [2, 3, 4, 5]` and `T = [6, 7, 8, 9]`.33:Tbb7,| strand value | cell-to-cell action (`│`) | cell-to-list action (`─`) | list-to-list action ( `╶` or `╴` ) | | :-----------:| ------------------------- | --------------------------- | ------------------- | | **6** | **subtract** ${tex`t \leftarrow n-t`}
`T = [-4, 7, 8, 9]` | ${tex`t_i \leftarrow n-t_i`}
`T = [-4, -5, -6, -7]` | ${tex`t_i \leftarrow n_i-t_i`}
`T = [-4, -4, -4, -4]`

| | **5** | **modulus** ${tex`t \leftarrow t \mod n`}
`T = [0, 7, 8, 9]` | ${tex`t_i \leftarrow t_i \mod n`}
`T = [0, 1, 0, 1]` | ${tex`t_i \leftarrow t_i \mod n_i`}
`T = [0, 1, 0, 4]`

| | **4** | **power** ${tex`t \leftarrow t^n`}
`T = [36, 7, 8, 9]` | ${tex`t_i \leftarrow t_i^n`}
`T = [36, 49, 64, 81]` | ${tex`t_i \leftarrow t_i^{n_i}`}
`T = [36, 343, 4096, 59049]`

| | **3** | **pop & add** ${tex`n`} to ${tex`t`}
`T = [8, 7, 8, 9]`
`N = [3, 4, 5]` | **pop & append** ${tex`n`} to ${tex`T`}
`T = [6, 7, 8, 9, 2]`
`N = [3, 4, 5]` | **pop last of N & append** to ${tex`T`}
`T = [6, 7, 8, 9, 5]`
`N = [2, 3, 4]`

| | **2** | **multiply** ${tex`t \leftarrow nt`}
`T = [12, 7, 8, 9]` | ${tex`t_i \leftarrow n t_i`}
`T = [12, 14, 16, 18]` | ${tex`t_i \leftarrow n_i t_i`}
`T = [12, 21, 32, 45]`

| | **1** | **insert** ${tex`n`} before ${tex`t`}
`T = [2, 6, 7, 8, 9]` | **append** ${tex`n`} to ${tex`T`}
`T = [6, 7, 8, 9, 2]` | **append last of N** to ${tex`T`}
`T = [6, 7, 8, 9, 5]`

| | **0** | **assign** ${tex`t \leftarrow n`}
`T = [2, 7, 8, 9]` | ${tex`t_i \leftarrow n`}
`T = [2, 2, 2, 2]` | ${tex`t_i \leftarrow n_i`}
`T = [2, 3, 4, 5]`

| | **-1** | **subtract** ${tex`t \leftarrow t-n`}
`T = [4, 7, 8, 9]` | ${tex`t_i \leftarrow t_i-n`}
`T = [4, 5, 6, 7]` | ${tex`t_i \leftarrow t_i-n_i`}
`T = [4, 4, 4, 4]`

| | **-2** | **divide** ${tex`t \leftarrow \frac t n`}
`T = [3, 7, 8, 9]` | ${tex`t_i \leftarrow \frac {t_i} n`}
`T = [3, 3.5, 4, 4.5]` | ${tex`t_i \leftarrow \frac {t_i} {n_i}`}
`T = [3, 2.33, 2, 1.8]`

| | **-3** | _undefined_ | **add** ${tex`t_i \leftarrow t_i + n`}
`T = [8, 9, 10, 11]` | ${tex`t_i \leftarrow t_i + n_i`}
`T = [8, 10, 12, 14]`

| | **-4** | **root** ${tex`t \leftarrow \sqrt[n]t`}
`T = [2.45, 7, 8, 9]` | ${tex`t_i \leftarrow \sqrt[n]t_i`}
`T = [2.45, 2.65, 2.83, 3]` | ${tex`t_i \leftarrow \sqrt[n_i]t_i`}
`T = [2.45, 1.91, 1.68, 1.55]`

| | **-5** | **modulus** ${tex`t \leftarrow n \mod t`}
`T = [2, 7, 8, 9]`

| ${tex`t_i \leftarrow n \mod t_i`}
`T = [2, 2, 2, 2]` | ${tex`t_i \leftarrow n_i \mod t_i`}
`T = [2, 3, 4, 5]`

| | **-6** | **divide** ${tex`t \leftarrow \frac n t`}
`T = [0.33, 7, 8, 9]` | ${tex`t_i \leftarrow \frac n {t_i}`}
`T = [0.33, 0.29, 0.25, 0.22]` | ${tex`t_i \leftarrow \frac {n_i} {t_i}`}
`T = [0.33, 0.43, 0.5, 0.55]` |34:T676,

╭ ╭ ╭─╮ ╭───╮ ╭─╮ ╭─╮ ╭───╮ │ │ │ │ │ │ │ │ │ │ ╰─╮ │ ╰─╯ │ 1 2 1 1 2 1 2 3 1 2 1 2 3 1 2 3

Fig. 3.2: Action strands corresponding to action types 0 to 6.

35:T575,

│ │ │ │ │ │ ╰ ╰─╮ ╭───╯ │ ╰─╮ │ ╰─╮ │ ╭───╯ ╰─╮ 1 2 1 1 2 3 2 1 3 2 1 1 2 3

Fig. 3.3: Cell-based action strands corresponding to actions -1, to -6.

36:T9d9,

1 ╵ ╰─╮ ╰─╮ ╰─╮ ╰─╮ ╰─╮ 2 ╰─ ╰─ ╰─ ╰─ ╰─ ╷ 1 ╵ ╰── ╰── ╰── ╰── ╰── │ │ ╭─╮ ╭─╮ ╭─────╮ ╭─╯ ╰ │ │ │ │ ╷ 1 2 1 1 2 1 2 1 2 3 5

Fig. 3.4: Action strands -2 (division), -1 (subtraction), 2 (multiplication), 4 (exponentiation) and 5 (modulus) each applied to 3 and 2 in a list.

37:T515,

1 ╵ ╰─ ╮ ╰─╮ ╮ ╮ 2 ╰─ ╰─ ╰── ╰─╮ 3 ╰─ ╷ 1 ╵ ╰── ╭─╮ │ │ ─╯ ╷ 1 2

Fig. 3.5: Squaring the numbers 1 to 5 with a list-based action strand.

38:T835,

1 ╵ ╮─╮╮╰─╮ ╮ 2 ╰─╯╰─ ╰─╰── ╮╮ ╰─╮╮ 3 │╰──╮ │╰─╮ 5 ╰── ╰─╰──╰──╷ 1 ╵ ╰─╮ 2 ╴─╯ ╭ │ │ │ ╰─╯ ╷

Fig. 3.6: Applying a cell-to-cell assign action (0) to a reference strand

39:T87c,

1 ╵ ╮─╮╮╰─╮ ╮ 2 ╰─╯╰─ ╰─╰── ╮╮ ╰─╮╮ 3 │╰──╮ │╰─╮ 5 ╰── ╰─╰──╰──╷ 1 ╵ ╰─╮ 2 ╴─╯ ╭ │ ╭─ │ │ ╰─╯ ╷

Fig. 3.7: Applying a cell-to-list assign action (0) to a reference strand

3a:T883,

1 ╵ ╮─╮╮╰─╮ ╮ 2 ╰─╯╰─ ╰─╰── ╮╮ ╰─╮╮ 3 │╰──╮ │╰─╮ 5 ╰── ╰─╰──╰──╷ 1 ╵ ╰─╮ 2 ╴─╯ ╭ │ ╵ │ │ ╰─╯ ╷

Fig. 3.8: Applying the list-to-list assign action (0) to a reference strand

3b:T461,

1 ╵ ╰─╮╭─╯ 2 ╴─╯│╭─ 3 ╭ ╷╯╭ │ ╵ │ │ │ │ ╰─╯ ─╯╷

Fig. 3.9: Function to double the values in input list2 storing the result in output list1

3c:T49c,

1 ╵ ╰─ ╮ ╰─╮ ╮ ╮ 2 ╰─ ╰─ ╰── ╰─╮ 3 ╰─ ╷ 1 ╵ ╮ 2 ╰──── ╭ │ ╷

Fig. 3.10: Inserting an 8 at the start of a list.

3d:T621,

1 ╵ ╰─ ╮ ╰─╮ ╮ ╮ 2 ╰─ ╰─ ╰── ╰─╮ 3 ╰─ ╷ 1 ╵ ╰──╮ ╰──╮ ╮ 2 ─╯ ─╯ ╰──── ╭ │ ╷

Fig. 3.11: Inserting an 8 at the middle of a list.

3e:T4e3,

1 ╵ ╰─ ╮ ╰─╮ ╮ ╮ 2 ╰─ ╰─ ╰── ╰─╮ 3 ╰─ ╷ 1 ╵ ╮ 2 ╰──── ╭ │ ╰─ ╷

Fig. 3.12: Appending an 8 to the end of a list.

3f:Taab,

1 ╵ ╮─╮╮╰─╮ ╮ 2 ╰─╯╰─ ╰─╰── ╰─╮ ╮ ╮ ─╮╰─╮ 3 ╰─╰──╰───╯ ╰── ╷ 1 ╵ ╰──╮╰──╮╰──╮╰──╮ ╰─╮ 2 ─╯ ─╯ ─╯ ─╯ ╭ ╷ ╰───╮ │ ╷ 1 2 3

Fig. 3.13: Using the pop action to move a value from list2 to the end of list1

40:T7f2,

1 ╵ ╮─╮╮╰─╮ ╮ 2 ╰─╯╰─ ╰─╰── ╰─╮ ╮ ╮ ─╮╰─╮ 3 ╰─╰──╰───╯ ╰── ╷ 1 ╵ ╰─╮ 2 ╭ ╷ ╰───╮ │ ─╯ ╷ 1 2 3

Fig. 3.14: Using the pop list action to move a value from list2 to the end of list 1

41:Tad8,

1 ╵ 2 ╰─╮ ╮ ╮ ─╮ ╰─╮ 3 ╰─ ╰── ╰───╯ ╰── ╷ 1 ╵ ╰─╮ ╰─╮ ╰─╮ ╰─╮ 2 ╭ ╷ ╭ ╷ ╭ ╷ ╭ ╷ ╰───╮╰───╮╰───╮╰───╮ │ │ │ │ ╴╯ ╴╯ ╴╯ ╴╯╷

Fig. 3.15: Reversing a list's contents using the list-to-list pop action.

42:[] 2f:{"title":"3. Rivulet Action Strands","cells":[{"id":0,"value":"# 3. Rivulet Action Strands\n\n

[Data Strands](https://observablehq.com/@jwolondon/rivulet-data-strands)

","pinned":false,"hidden":false,"mode":"md"},{"id":1563,"value":"$31","pinned":false,"hidden":false,"mode":"html"},{"id":496,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":1750,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":1439,"value":"This example raises the target cell ${tex`t`} value (2) to the power ${tex`n`} (6) by applying action 4 (exponentiation) leaving 64 in `list1[0]`.","pinned":false,"hidden":false,"mode":"md"},{"id":517,"value":"

\n1 ╵ ╮ ╵ ╮\n2 ╰─ ╷ ╰───\n ╭─╮\n │\n │ ╷\n

Fig. 3.1: Action type 4 is applied to 6 (second data strand) and 2 (prior value set by the first data strand)

\n","pinned":false,"hidden":false,"mode":"md"},{"id":521,"value":"It's easiest to think of action strands a little like 90° rotations of data strands. Values are assigned to them with vertical dashes `│` rather than the horizontal dashes `─` of data strands. Vertical dashes progressing downward (when traversing from the hook) increment, while dashes progressing upward decrement. Movement left or right changes the multiplier associated with each increment/decrement, following the 1,2,3,5,7... prime sequence, _relative to the column in which the action strand's hook was placed_. The prime sequence extends both left and right of this anchor column 1.","pinned":false,"hidden":false,"mode":"md"},{"id":1037,"value":"Here is a snippet showing a series of action strands representing the action types 0 to 6 with the column numbers marked:","pinned":false,"hidden":false,"mode":"md"},{"id":526,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":529,"value":"Each action strand represents, from left to right: **0** (2×1 - 1×2); **1** (1×1); **2** (1×2); **3** (1×3); **4** (2×2); **5** (1×2 + 1×3) and **6** (2×3). Unlike the row numbers of data strands, column numbers proceed in column steps of 2. This is to account for the fact that typically the space given to each lexeme is twice as tall as its width. The extra horizontal padding allows for more pleasing and intuitive strand shapes. This is just one set of possible ways of encoding those action types, because like all strands, there are many ways to encode any given number.\n\nSimilarly, we can use action strands to represent the numbers -1 to -6. In the example below, the column values variously extend to the left and to the right of each anchor column; using columns in either direction is permissible. ","pinned":false,"hidden":false,"mode":"md"},{"id":536,"value":"$35","pinned":false,"hidden":false,"mode":"md"},{"id":1087,"value":"## 3.1 Arithmetic actions\n\nAction types -2, -1, 2, 4, and 5 correspond to division, subtraction, multiplication, exponentiation and modulus operations respectively. Consider the following example:","pinned":false,"hidden":false,"mode":"md"},{"id":1091,"value":"$36","pinned":false,"hidden":false,"mode":"md"},{"id":1097,"value":"The first glyph (first two rows) creates `list1` as `[3, 3, 3, 3, 3]` (our initial target values). The second glyph specifies values `2, 2, 2, 2, 2` (our ${tex`n`} values) but instead of adding them to the targets, the action strand modifiers generate **1.5** (3÷2); **1** (3-2); **6** (3×2); **9** (3²) and **1** (3 mod 2).","pinned":false,"hidden":false,"mode":"md"},{"id":566,"value":"To apply actions to individual cells, the end of the action strand (i.e. opposite end to the hook) should be vertical. But we can also apply actions to an entire list by adding a horizontal dash to the end (known as a _list indicator_). For most operations, this is effectively a _map_ or _lambda_ function applied to list.\n\nFor example, the strands below create a list `[1, 4, 9, 16, 25]` by raising each number in target `list1` (`[1, 2, 3, 4, 5]`) to the power 2. The action strand is a 4 (exponentiation action) with the horizontal list indicator ensuring the action is applied to all cells in the target list.","pinned":false,"hidden":false,"mode":"md"},{"id":571,"value":"$37","pinned":false,"hidden":false,"mode":"md"},{"id":1363,"value":"## 3.2 Copying lists","pinned":false,"hidden":false,"mode":"md"},{"id":1365,"value":"Action type 0 is the assignment operator that will modify a reference strand, assigning its source to its target instead of the default add operation. Consider its effect on two lists:","pinned":false,"hidden":false,"mode":"md"},{"id":1369,"value":"$38","pinned":false,"hidden":false,"mode":"md"},{"id":1390,"value":"The first glyph creates two lists: `list1 = [1, 2, 3, 4]` and `list2 = [10, 11, 12, 13]`. The reference strand (top strand in glyph2) transfers `list2[0]` to `list1[0]` but is modified by the action strand below it to assign the new value. So the resulting `list1` becomes `[10, 2, 3, 4]` (and not the `[11, 2, 3, 4]` we would get with the default add operation).","pinned":false,"hidden":false,"mode":"md"},{"id":1393,"value":"To copy the entire `list2` to `list1`, we might think we just need to add a list indicator to the action strand:","pinned":false,"hidden":false,"mode":"md"},{"id":1373,"value":"$39","pinned":false,"hidden":false,"mode":"md"},{"id":1415,"value":"Although it applies the action to the entire target `list1`, the source reference is still just `list2[0]`, so the result is `list1 = [10, 10, 10, 10]`.\n\nTo copy the entire `list2` over to `list1` we add a _list-to-list indicator_ (a broken dash `╵` `╷` `╴` `╶` depending on the strand direction) at the non-hook end of the action strand, giving `list1 = [10, 11, 12, 13]` :","pinned":false,"hidden":false,"mode":"md"},{"id":1375,"value":"$3a","pinned":false,"hidden":false,"mode":"md"},{"id":1541,"value":"## 3.3 Providing values from the command-line","pinned":false,"hidden":false,"mode":"md"},{"id":1537,"value":"Rather than hardcode all values directly with data strands, we can instead specify values directly from the command-line using the `riv -i` option. This is allows us to create functions that take some input, process that input in some way and generate output in `list1`. Any comma-separated list of numbers provided via the `-i` option initialises `list2` with that input. \n\nHere's a simple example that takes any input list and doubles all its values in the output `list1`. Assuming the program is called `doubler.riv`, try running it from the command line to check it works with any input list, such as \n```\nriv -i \"1, 2, 3, 4\" -o numeric doubler.riv\n```\nwhich should generate the output `2 4 6 8`","pinned":false,"hidden":false,"mode":"md"},{"id":1550,"value":"$3b","pinned":false,"hidden":false,"mode":"md"},{"id":1553,"value":"The first strand uses list copying (as in Section 3.2) to copy the input list to the output list. The next strand sets `list3[0] = 2` before using the list modified multiplier action to multiply all values in `list1` by that 2.\n\nThe list indicator and the list-to-list indicator are especially useful when handling input lists as we often don't know exactly how long the input list will be when writing the Rivulet code. Later we will see patterns that can count the number items in a list provided at runtime.","pinned":false,"hidden":false,"mode":"md"},{"id":1126,"value":"## 3.4 Inserting and removing list cells","pinned":false,"hidden":false,"mode":"md"},{"id":1224,"value":"New values can be inserted into target lists (rather than replacing existing values) by specifying action type 1 where ${tex`n`} is inserted at the position of the target, shifting all values after the target cell to the right.\n\nHere's a simple example where glyph 1 sets `list1` to be `[1, 2, 3, 4, 5]` then glyph 2 inserts an `8` at the start of `list1` giving `[8, 1, 2, 3, 4, 5]`.","pinned":false,"hidden":false,"mode":"md"},{"id":1321,"value":"$3c","pinned":false,"hidden":false,"mode":"md"},{"id":1329,"value":"To insert values at other positions in a target list, we could simply add some other operations to the left of the insert strand pairing. For example, the following pads with two `+=0` data strands to insert the 8 at cell position 2 in the `list1` giving `[1, 2, 8, 3, 4, 5]`","pinned":false,"hidden":false,"mode":"md"},{"id":1331,"value":"$3d","pinned":false,"hidden":false,"mode":"md"},{"id":1352,"value":"For convenience, inserting a value at the end of a target list (appending) is achieved by adding a list indicator to the action 1 modifier. This is especially useful for long lists or input lists whose length we don't know at the code writing stage.","pinned":false,"hidden":false,"mode":"md"},{"id":1355,"value":"$3e","pinned":false,"hidden":false,"mode":"md"},{"id":1360,"value":"Removing items from a list follows a similar procedure except we use action type 3. Consider the following:","pinned":false,"hidden":false,"mode":"md"},{"id":1469,"value":"$3f","pinned":false,"hidden":false,"mode":"md"},{"id":1486,"value":"The first glyph creates two lists: `list1 = [1, 2, 3, 4]` and `list2 = [5, 6, 7, 8]`. The second glyph pads the reference strand with 4 zero strands meaning its marker from `list2[0]` will target `list1[4]` (it's the 4th hook read from left-to-right). The action strand modifies the reference strand to pop it from its marker location (i.e. remove it) adding it to its target location. The result is `list2 = [6, 7, 8]` and `list1 = [1, 2, 3, 4, 5]`.\n\nIf we know we wish to append the popped value to the end of a list, we don't need to pad the reference strand as above because the list marker version of the pop action will append the popped value to the end of the target list. The following therefore does exactly as above, but with a single list action:","pinned":false,"hidden":false,"mode":"md"},{"id":1471,"value":"$40","pinned":false,"hidden":false,"mode":"md"},{"id":1512,"value":"The list-to-list modifier, when applied to the pop action, will pop from the end of the source list. This gives us a convenient way of reversing a list's contents when moving it from one list to another:","pinned":false,"hidden":false,"mode":"md"},{"id":1474,"value":"$41","pinned":false,"hidden":false,"mode":"md"},{"id":1523,"value":"The result is `list1 = [8, 7, 6, 5]` and `list2` being empty since all its original values of `[5, 6, 7, 8]` have been popped.","pinned":false,"hidden":false,"mode":"md"},{"id":1525,"value":"Data and action strands give us the core capabilities of list manipulation but they don't yet give us a ([Turing](https://en.wikipedia.org/wiki/Turing_completeness)) complete programming language. For that we need to consider conditional operations, which we will cover in the [next section](https://observablehq.com/@jwolondon/rivulet-levels-and-decisions).","pinned":false,"hidden":false,"mode":"md"},{"id":1295,"value":"[Levels and Decisions](https://observablehq.com/@jwolondon/rivulet-levels-and-decisions)","pinned":false,"hidden":false,"mode":"md"},{"id":76,"value":"---\n\n## Appendices","pinned":false,"hidden":false,"mode":"md"},{"id":1165,"value":"_For formatting Rivulet code snippets:_","pinned":false,"hidden":false,"mode":"md"},{"id":78,"value":"import { rivFormat } from \"@jwolondon/rivulet-intro\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":1162,"value":"rivFormat()","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W42","stdlib":"1","titling":"auto"}