Control flow#

Ordering, looping, conditions and load-time messages.

11 objects. Every entry is pulled directly from the engine registry, which reads the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros in the libYSE source; the longer notes under each summary are ported from the libYSE documentation. The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects. Links into the patcher guide (messages, time, data, files, …) lead to the libYSE documentation, which also has this category’s page.

`.bangbang`#

Sends a bang out every outlet, right to left, whatever arrives. Each outlet’s branch finishes before the next outlet fires, so it orders ‘do this, then that’.

Dart:: Obj.gBangbang
Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Bang, int, float or list. The value is ignored.

Outlets

#	Label	Type	Range	Description
0	out0	BANG	bang	A bang. The last outlet fires first, outlet 0 last.
1	out1	BANG	bang	A bang. The last outlet fires first, outlet 0 last.

Parameters

Name	Default	Range	Description
outlets	2	1-40	Number of outlets, clamped to 1-40; a float is truncated. Two when absent or not a number. Unlike .trigger, ‘.bangbang 3’ means three outlets.

`.bondo`#

Holds one value per inlet and sends all of them, right to left, whenever any inlet receives one. Keeps a set of related values together, so nothing downstream sees half an update.

Dart:: Obj.gBondo
Kind:: Control-rate

Every inlet is hot: a value arriving at any inlet is stored there, and then every outlet sends what its inlet holds, the last outlet first and outlet 0 last (see Messages and dispatch). Wire outlet 0 to whatever acts on the set and the others to cold inlets, and the whole set is in place when outlet 0 fires.

Stored values stay until replaced, so each send repeats the values that did not change. An inlet that has received nothing sends 0.

Messages

Every inlet takes all of these:

an int, float, list or word: store it here and send the set.
a list that starts with a number: spread over this inlet and the ones to its right, one item each; items past the last inlet are dropped. With the n argument the list is stored whole in this inlet instead.
a message that starts with a word (note 60): stored whole in this inlet.
bang: send the set without storing anything.
set <message>: store as above without sending. A bare set is an ordinary word: it is stored and the set is sent.

Arguments

In order: the number of inlet/outlet pairs (1-256, default 2), then a delay in milliseconds, then n to store lists whole (n may stand anywhere). With a delay, a stored value sends the set that many milliseconds later instead of at once; another value before then restarts the wait, so a burst of changes sends one set. A bang still sends at once. Waits are counted in whole audio blocks; see Time, scheduling and clocks.

.buddy is the other way round: it waits until every inlet has a value.

Inlets

#	Label	Accepts	Range	Description
0	in0	FLOAT, INT, BANG, LIST	any	Stores a value here and sends every outlet. A bang sends without storing; ‘set <message>’ stores without sending.
1	in1	FLOAT, INT, BANG, LIST	any	Stores a value here and sends every outlet. A bang sends without storing; ‘set <message>’ stores without sending.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	What the matching inlet holds: 0 until it receives something.
1	out1	ANY	any	What the matching inlet holds: 0 until it receives something.

Parameters

Name	Default	Range	Description
ports	2	1-256, optional delay in ms, optional ‘n’	Number of inlet/outlet pairs (1-256), then an optional delay in ms, and ‘n’ to store lists whole.

`.buddy`#

Waits until every inlet has received a value, then sends them all at once, right to left, and starts waiting again. Use it to assemble one event from parts that arrive separately.

Dart:: Obj.gBuddy
Kind:: Control-rate

Each inlet stores the last value it received. When the last empty inlet receives one, every outlet sends its inlet’s value, the last outlet first and outlet 0 last (see Messages and dispatch), and all inlets are empty again. Nothing is ever sent twice, and nothing is sent for an incomplete set.

[.buddy 2]   in1 <- 7    =>  nothing
             in0 <- 3    =>  out1: 7, out0: 3
             in0 <- 4    =>  nothing (in1 is empty again)

Messages

an int, float, list or word: stored in this inlet, replacing what it held. A list is stored whole and leaves the matching outlet unchanged.
bang: stores the number 0, so a source with no value of its own can still take part.
clear, on inlet 0 only: empty every inlet without sending. On the other inlets the word is stored like any other value.

To send a set on any change, keeping the values that did not change, use .bondo.

Inlets

#	Label	Accepts	Range	Description
0	in0	FLOAT, INT, BANG, LIST	any	Stores a value here; once every inlet holds one, all are sent. A bang stores 0. On inlet 0, ‘clear’ empties every inlet.
1	in1	FLOAT, INT, BANG, LIST	any	Stores a value here; once every inlet holds one, all are sent. A bang stores 0. On inlet 0, ‘clear’ empties every inlet.

Outlets

#	Label	Type	Range	Description
0	out0	ANY	any	What the matching inlet received, sent once the set is complete.
1	out1	ANY	any	What the matching inlet received, sent once the set is complete.

Parameters

Name	Default	Range	Description
inlets	2	1-256	Number of inlet/outlet pairs, clamped to 1-256. A float is truncated.

`.if`#

Tests a condition and sends one message when it is true and, optionally, another when it is false: ‘$i1 > 64 then bang else out2 $i1’. The condition and the message items use the .expr language.

Dart:: Obj.gIf
Kind:: Control-rate

The argument is a statement:

<condition> then <message> [else <message>]

[.if $i1 > 64 then bang else out2 $i1]

When the condition is not 0 the then message is sent, otherwise the else message. Without else, a false condition sends nothing, which filters a stream.

The condition is an expression in the language of .expr (see Math): the same $i1-$i9 and $f1-$f9 placeholders, operators, functions and int/float rules.

A message is up to 16 items separated by spaces. Each item is itself an expression without spaces, such as 1, 0.5, $i1 or $i1*2. One item is sent as an int or a float, depending on its type; two or more are sent as a list. bang on its own sends a bang. out2 in front of a message sends it from a second, right outlet, which exists only when a message uses it.

Inlets

There is one inlet per placeholder number, up to the highest one used (at most 9). Inlet 0 stores its number and evaluates; the others only store. A bang on inlet 0 evaluates with the stored numbers, and a list on inlet 0 fills the inlets from the left, then evaluates. An inlet that has received nothing reads 0.

Errors

A statement that cannot be read is reported in the log when the object is created, and the object then sends nothing. Text placeholders ($s) are not supported, and neither is a send <name> message to a named receiver: wire the outlet to a .s instead.

Inlets

#	Label	Accepts	Range	Description
0	$1	FLOAT, INT, BANG, LIST	any float	Value for $i1 / $f1; stores it and evaluates. A bang evaluates with the stored values; a list fills the inlets from the left, then evaluates.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	The then or else message, unless it starts with out2. One item is sent as an int or float, several as a list, ‘bang’ as a bang.

Parameters

Name	Default	Range	Description
statement	—	any statement	<condition> then <message> [else <message>], e.g. ‘$i1 > 64 then bang else out2 $i1’.

`.loadbang`#

Sends a bang when the patch it is in has finished loading, so a saved patch can set up its own starting state. A bang at the inlet sends one by hand.

Dart:: Obj.gLoadbang
Kind:: Control-rate

The bang is sent once, after the whole patch has been loaded with Patcher.parseJson: every object created, every cord connected. Objects inside subpatchers fire in the same pass.

An object created with Patcher.createObject in a running patch does not fire until the patch is saved and loaded again. Send it a bang to fire it by hand; a host that builds a patch object by object can do this to initialise it.

The order in which two .loadbang objects fire is not defined. When one initialisation must come before another, use one .loadbang and a .trigger. See Patch file format for the whole load sequence.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG	bang	A bang sends a bang, as a load does. Use it to initialise a patch built with CreateObject.

Outlets

#	Label	Type	Range	Description
0	out	BANG	bang	A bang when the patch has finished loading, and for each bang in.

`.loadmess`#

Sends its arguments as a message when the patch it is in has finished loading, such as ‘.loadmess 0.5’ to set a gain. A bang at the inlet sends it by hand.

Dart:: Obj.gLoadmess
Kind:: Control-rate

Fires at the same moment as .loadbang and follows the same rules (see there). .loadmess 0.5 into a gain does what .loadbang into a message box holding 0.5 would.

The message is sent in the form it has:

nothing at all when the object has no arguments;
a bang for the single word bang;
an int or a float for a single number, an int when written without a . or an exponent: 60 is an int, 60.0 a float;
otherwise a list with the text unchanged.

Messages

bang: send the stored message.
set <message>: replace the stored message without sending. A bare set empties it. This works from a list and from a message box.
any other list is ignored, so values passing through cannot replace the initialisation.

A set longer than 256 characters is refused, and the old message is kept. Arguments longer than that are cut at the last whole word that fits. set does not change the saved arguments: the patch saves the message the object was created with.

Inlets

#	Label	Accepts	Range	Description
0	trigger/set	BANG, LIST	bang, or ‘set <message>’	A bang sends the stored message, as a load does. ‘set <message>’ replaces it without sending; a bare ‘set’ empties it. Other lists are ignored.

Outlets

#	Label	Type	Range	Description
0	out	ANY	any	The stored message when the patch has finished loading, and for each bang in: a bang, an int, a float or a list, by its form. Nothing when empty.

Parameters

Name	Default	Range	Description
message	—	any message, up to 256 characters	The message to send, such as ‘60’ or ‘mode 2’. At most 256 characters; with none, the object sends nothing.

`.match`#

Watches a stream of numbers and sends the last few as a list when they match the pattern in its arguments. The word ‘nn’ matches any number, so ‘.match 1 nn 3’ sends ‘1 5 3’ after 1, 5, 3.

Dart:: Obj.gMatch
Kind:: Control-rate

The object keeps the most recent numbers, as many as the pattern is long. When those spell the pattern, it sends them as a list and forgets them, so matches never overlap.

[.match 1 nn 3]   1, 5, 3       =>  1 5 3
[.match 1 2 3]    1 2 1 2 3     =>  1 2 3
[.match 1 1 1]    1 1 1 1 1     =>  1 1 1   (once)

A value that ends one attempt can start the next, as in the second example.

Matching

A number in the pattern matches only that exact number. Ints and floats are compared as floats, so 5 matches 5.0. A calculated float can miss a number that looks equal; put .round in front.
nn matches any number.
A word in the stream, or a value that is not finite, takes a place and matches nothing, not even nn.
A pattern word other than nn (NN included) matches nothing, so the object never fires. With no pattern at all it never fires either.

The output keeps the values as they arrived, so the places filled by nn show what came in. An int is sent as an int and a float as a float.

Messages

an int, float or list: each number, or each list item, takes the next place in the stream.
clear: forget the numbers received so far. The pattern stays.
set <pattern>: a new pattern, written like the arguments. It also forgets the numbers received so far. A bare set leaves no pattern. The saved arguments do not change.

The pattern holds at most 256 elements.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, LIST	any	Int, float or list: each number takes the next place in the stream. Also ‘clear’ and ‘set <pattern>’.

Outlets

#	Label	Type	Range	Description
0	match	LIST	list of numbers	The values that matched, in arrival order and spelling, as a list as long as the pattern.

Parameters

Name	Default	Range	Description
pattern	—	any list of numbers and nn	The sequence to watch for: numbers, matched exactly, and ‘nn’ for any number. At most 256 elements.

`.next`#

Tells the first message of a burst from the rest: a bang leaves the left outlet when a message starts a new logical event, and the right outlet when it belongs to the same event as the message before it.

Dart:: Obj.gNext
Kind:: Control-rate

A logical event is everything one stimulus causes: one host call, one GUI action, one tick of a timed object, one MIDI message (see Logical events in Messages and dispatch). Time does not matter: two host calls are two events however close together, and the whole fan-out of one .trigger is one event however long it takes.

The first message of an event sends a bang from the left outlet, and every later message of the same event sends one from the right. Exactly one outlet fires per message. Typical use is to do something once per burst, such as resetting a counter at the start of a .coll dump without knowing how long the dump is.

[.uzi 3] -> [.next]   bang   =>  left, right, right

The content of a message is ignored, so a 0 counts like any other value.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Bang, int, float or list. Only which event it belongs to matters; every word is an ordinary message.

Outlets

#	Label	Type	Range	Description
0	separated	BANG	bang	A bang when this message starts a new logical event. The first message ever always goes here.
1	same	BANG	bang	A bang when this message belongs to the same event as the previous one.

`.onebang`#

A one-shot: lets one message through as a bang from the left outlet, then sends every further message out the right outlet until the right inlet re-arms it.

Dart:: Obj.gOnebang
Kind:: Control-rate

The object is a gate with two states. When armed, the next message on the left inlet sends a bang from the left outlet and closes the gate. When closed, a message sends a bang from the right outlet instead. Every message gives exactly one bang, so the right outlet can count or report the triggers that were blocked; leave it unconnected for a plain one-shot.

Anything on the right inlet arms the gate, including the word stop. Arming an armed gate changes nothing: five arms and five triggers give one pass and four rejects.
Everything on the left inlet is a trigger, including 0. The one exception is the bare word stop, which closes the gate without sending anything. stop 1 is a trigger.
The gate starts closed. A non-zero argument starts it armed; 0.5 counts as non-zero, and an argument that is not a number counts as 0.

To open and close a path with numbers, use .gate.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Bang, int, float or list, treated as a bang: it leaves outlet 0 if the gate is armed, outlet 1 if not. The bare word ‘stop’ closes the gate silently.
1	arm	FLOAT, INT, BANG, LIST	any	Anything here arms the gate, silently. Arming twice still passes only once.

Outlets

#	Label	Type	Range	Description
0	pass	BANG	bang	A bang when a message arrives while the gate is armed. The gate closes.
1	reject	BANG	bang	A bang when a message arrives while the gate is closed.

Parameters

Name	Default	Range	Description
initial	0	0 or non-zero	Non-zero starts the gate armed, so the first message passes. Closed by default.

`.trigger`#

Sends its input out every outlet, right to left, converted per outlet to an int, a float, a bang, a list or text, or replaced by a constant. Use it to make the order of two branches explicit.

Dart:: Obj.gTrigger
Kind:: Control-rate

Each argument makes one outlet, in order. When a message arrives, every outlet sends, the last outlet first and outlet 0 last. Each outlet’s branch finishes before the next outlet sends (see Messages and dispatch).

[.trigger b i]   7   =>  out1: 7, then out0: bang

The common use is .trigger b i: the number reaches a cold inlet first, and only then does the bang make the object compute with it.

Formats

i: an int. A float is truncated toward zero; a list or a bang sends 0.
f: a float. A list or a bang sends 0.
b: a bang, whatever arrived.
l: a list unchanged. Anything else sends the list 0.
s: text unchanged. Text travels as a list, so a list passes through s too; a number or a bang sends the empty symbol.

i and f do not read lists: a list 5 6 sends 0 from an i outlet. Use .unpack or .route to take numbers out of a list.

Any other argument is a constant, sent on every input whatever arrived: a number without a . or an exponent is an int (7), one with them is a float (0.5), and anything else is sent as text. The format letters are lower case and single characters, so I or bang are constants.

With no arguments there are two i outlets. At most 256 outlets.

Inlets

#	Label	Accepts	Range	Description
0	in	FLOAT, INT, BANG, LIST	any	Bang, int, float or list, sent out every outlet, right to left.

Outlets

#	Label	Type	Range	Description
0	out0	INT	any int	The input as an int: a float is truncated toward zero, a list or a bang sends 0.
1	out1	INT	any int	The input as an int: a float is truncated toward zero, a list or a bang sends 0.

Parameters

Name	Default	Range	Description
formats	i i	any list of i/f/b/l/s letters and constants	One argument per outlet: ‘i’, ‘f’, ‘b’, ‘l’ or ‘s’ to convert the input, or any other token as a constant. Two ‘i’ outlets by default, at most 256.

`.uzi`#

Sends a burst of bangs at once, each preceded by its index, then a carry bang when the run is done. The patcher’s loop: ‘.uzi 16’ runs sixteen iterations inside one message.

Dart:: Obj.gUzi
Kind:: Control-rate

A bang starts a run. For each iteration, the index goes out the right outlet, then a bang out the left outlet, so whatever the bang drives already has the new index. After the last iteration the middle outlet sends a bang.

[.uzi 3]     bang   =>  index 1, bang, index 2, bang, index 3, bang, carry
[.uzi 4 0]   bang   =>  indices 0 1 2 3

Each send finishes everything it triggers before the next one, and the whole run is one logical event (see Messages and dispatch). A run of 0 iterations still sends the carry bang.

Messages

On the left inlet:

bang: run.
int or float: set the count, then run. A float is truncated.
pause (or break): stop the run that is in progress after the current iteration. Only a message triggered by the run itself can arrive during a run, so this is how a loop exits early, such as stopping a search once the value is found. A paused run sends no carry bang. Outside a run it does nothing.
resume (or continue): finish a paused run, numbering on from where it stopped. It does nothing if no run is paused.
offset <n>: skip the first n iterations of every run from now on, so the run sends count minus n bangs and the index starts at base plus n. offset 0 turns this off.

Other words are ignored. The right inlet sets the count for the next run without starting it.

Limits

The count is clamped to 0-4096. A creation argument above that is reported in the log. A bang or resume that arrives while a run is in progress, for example from an outlet wired back to the left inlet, is ignored, so such a loop always ends. A count changed during a run applies to the next run.

Inlets

#	Label	Accepts	Range	Description
0	start	FLOAT, INT, BANG, LIST	any	A bang runs the loop; an int or float sets the count, then runs it. Also ‘pause’, ‘resume’ and ‘offset <n>’.
1	count	FLOAT, INT	0-4096	Sets the count for the next run without starting it. Clamped to 0-4096; a float is truncated.

Outlets

#	Label	Type	Range	Description
0	bang	BANG	bang	One bang per iteration, right after its index.
1	carry	BANG	bang	A bang once a run has finished. Not sent when a run is paused.
2	index	INT	base to base+count-1	The iteration’s number, sent just before its bang.

Parameters

Name	Default	Range	Description
count	1	0-4096	Bangs per run, clamped to 0-4096 (a larger value is logged). A float is truncated.
base	1	-1000000000 to 1000000000	The first index. ‘.uzi 8 0’ counts 0 to 7.

Control flow

Contents

Control flow#