Skip to content

Push

Name - Description Default Type
<input> The value to push into the sequence. Any
<output> The input to this shard is passed through as its output. Any
Name The name of the variable. "" StringVar(Any)
Key The key of the value to write in the table (parameter applicable only if the target variable is a table). none Any
Global If the variable is available to all of the wires in the same mesh. false Bool
Clear Whether to clear this sequence at every wire iteration. This only works if it's the first push. The default is true. true Bool

Pushes a new value into a sequence variable. If the variable does not exist, it will be created.

Details

Push updates sequences and tables by pushing elements and/or sequences into them.

The name of the variable to update should come from the :Name parameter and the new update value(s) should come from the shard's input.

For existing sequences Push pushes in the new elements. If a sequence doesn't exist then Push will create it while pushing in the first element. These elements may be string constants, numerics, or even sequences themselves.

For tables Push can update only those existing keys whose values are of the type sequence. In such cases Push can push in new elements in those key-value pair sequences. The key to be updated must be passed in via the :Key parameter.

Note

  1. Do not use Push to update any variables created by Set (or its aliases >=/>>=). Push is best used to update variables that were themselves created by Push (first push).
  2. Though, if really want to do (1.) you can offload the current sequence into another sequence variable, push new values into it, and update the table with this sequence variable (see the last code example).

The :Global parameter controls whether the created variables can be referenced across wires (:Global set to true) or only within the current wire (:Global set to false, default behaviour).

Variables may be locally scoped (created with (:Global false); exists only for current wire) or globally scoped (created with (:Global true); exists for all wires of that mesh). Hence, in update mode (i.e. when you apply Push to an existing variable) the :Global parameter is used in conjunction with the :Name parameter to identify the correct variable to update.

The parameter :Clear controls whether we should clear out this sequence after every wire iteration (Clear set to true, default behaviour) or should the sequence data persist across wire iterations (Clear set to false).

The input to this shard is the new update value that is to be pushed into the sequence/table being modified. This value is also passed through as this shard's output.

Note

Push has two aliases: >> which is an alias for (Push ... :Clear true), and >>! which is an alias for (Push ... :Clear false). See the code examples at the end to understand how these aliases are used.

See also

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
;; create and update sequence with `Push`; value available only to current wire
1 (Push :Name .seq1)                    ;; create a sequence by pushing the first element
.seq1 (Log ".seq1")                     ;; sequence created => [1]
2 (Push :Name .seq1)                    ;; push one more element into sequence
.seq1 (Log ".seq1")                     ;; sequence updated => [1, 2]

;; create and update sequence with `Push`; value available to all wires on mesh
[10 20] (Push :Name .seq2 :Global true) ;; create sequence with two elements
.seq2 (Log ".seq2")                     ;; sequence created => [10, 20]
30 (Push :Name .seq2 :Global true)      ;; push one more element into sequence
.seq2 (Log ".seq2")                     ;; sequence updated => [10, 20, 30]

;; create empty sequence with `Sequence`; add elements with `Push`
(Sequence :Name .seq3)                  ;; create empty sequence
.seq3 (Log ".seq3")                     ;; empty sequence created => []
1 (Push :Name .seq3 :Clear false)       ;; push an element into sequence
.seq3 (Log ".seq3")                     ;; sequence updated => [1]               
2 (Push :Name .seq3 :Clear false)       ;; push another element into sequence
.seq3 (Log ".seq3")                     ;; sequence updated => [1, 2]    

;; create empty table with `Table`; add/update key sequence values with `Push`
;; (Table :Name .table1)                   ;; created an empty table (one key, no value)
;; .table1 (Log)                           ;; table with one key (no value) created => {A: []}
1 (Push .table1 "A")                    ;; push new key "A" with sequence value "[1]"
.table1 (Log)                           ;; table key/value updated => {A: [1]}
2 (Push .table1 "A")                    ;; push new element into key "A" existing sequence
.table1 (Log)                           ;; table key/value updated => {A: [1, 2]}   

;; create and update local/global sequence variables
"Local" (Push .seq)                     ;; create local sequence variable with first push
"Global" (Push .seq :Global true)       ;; create same-name global sequence variable with first push
(Get .seq) (Log)                        ;; get local variable => [Local]
(Get .seq :Global true) (Log)           ;; get same-name updated global variable => [Global]
"Local2" (Push .seq)                    ;; push new value into local sequence variable
"Global2" (Push .seq :Global true)      ;; push new value into  same-name global sequence variable
(Get .seq) (Log)                        ;; get updated local sequence variable => [Local, Local2]
(Get .seq :Global true) (Log)           ;; get updated global sequence variable => [Global, Global2]

;; Using a `Push` alias: `>>` is alias for `(Push :Clear true)` 
"Hello" >> .seq4                        ;; create sequence by pushing the first element
.seq4 (Log ".seq4")                     ;; sequence created => [Hello]
"World" >> .seq4                        ;; update the sequence by pushing one more element
.seq4 (Log ".seq4")                     ;; sequence updated with second element => [Hello, World]

;; Using a `Push` alias: `>>!` is alias for `(Push :Clear false)`
"Bye" >>! .seq5                         ;; create sequence by pushing the first element
.seq5 (Log ".seq5")                     ;; sequence created => [Bye]
"Universe" >>! .seq5                    ;; update the sequence by pushing one more element
.seq5 (Log ".seq5")                     ;; sequence updated with second element => [Bye, Universe]

;; Technique to update a non-push created Table's sequence values with `Push`
{:k1 [1 2 3]} >= .table2                ;; table is created using `Set`
.table2 (Log)                           ;; table with key/value pair created => {:k1 [1 2 3]}
(Get .table2 "k1") >= .seqvar           ;; target value offloaded into a sequence variable
4 (Push .seqvar)                        ;; update sequence variable using `Push`
.seqvar (Log)                           ;; sequence variable updated => [1, 2, 3, 4] 
{:k1 .seqvar} >= .table2                ;; update table key sequence value with modified sequence variable                      
.table2 (Log)                           ;; targeted table key updated with required sequence values => {:k1 [1 2 3 4]}