Arrays

Arrays#

The .array family: ordered data and the operations on it.

57 objects. Every entry is pulled directly from the engine source via the ADD_DESCRIPTION / INLET_DOC / OUTLET_DOC / PARAM_DOC macros (see YseEngine/patcher/pObject.h). The ~ prefix marks DSP / audio-rate objects; . marks control-rate objects.

`.array`#

An ordered list of values, shared by every .array with the same name in a patcher. Messages add, change, fetch and remove elements by zero-based index; a bang sends the array’s reference, which the other .array objects accept.

Kind:: Control-rate

Each element is a single value: an int, a float or a word. append 0 4 7 adds three elements, and getvalue sends them back as the list 0 4 7. An element keeps the spelling it arrived with, so 7 and 7. are different elements. On the way out, 7 leaves as an int, 7. as a float and anything that is not a number as a symbol.

Messages

append <value...>: add elements at the end.
insert <index> <value...>: add elements before position index, in the order given. Inserting at the length appends.
set <index> <value>: replace one element.
get <index>: send one element out of outlet 0, or bang outlet 2 when there is no element at index.
delete <index>: remove one element and close the gap.
clear: remove every element.
getsize: send the number of elements out of outlet 0.
getvalue: send the whole array out of outlet 0. One element leaves as a single value, several as a list.
bang: send the reference array <name> out of outlet 1.

Positions start at 0. A position outside the array, and any negative position, is refused: nothing is wrapped or clamped. Use .array.wrap or .array.rotate when you want wrapping.

Sharing

Every .array with the same name in a patcher uses the same contents, and two patchers with the same name share theirs. An .array without a name keeps a private array and sends no reference. The contents are saved with the patch. See Sharing a store by name and What is saved with the patch.

The other .array objects

The other objects in this category each work on a named array. They take the array’s name as their first argument, and it cannot be changed while the patch runs. They share these rules:

A bang on the left inlet runs the object. So does the reference array <name>, so outlet 1 of an .array can be wired straight into them. A reference that names a different array is refused (see Dictionaries and arrays travel by name).
The rightmost inlet accepts the array’s reference and does nothing with it, so the wiring can show which array an object works on.
Objects that change the array send its reference after each change, so they can be chained: .array.push into .array.length reports the new length after every push.
A result of one element leaves as a single value. When there is no result (an empty array, a missing position), a separate outlet bangs instead of sending a placeholder value.
Each operation reads or changes the array in one step, so its result is the array as it was at that moment, even if another object changes it right after.
An object without a name works on a private, empty array and sends no reference.

append 60 64 67  ->  [.array chord]
bang             ->  [.array chord]         outlet 1: array chord
array chord      ->  [.array.length chord]  ->  3

Limits

An array holds at most 256 elements of at most 64 characters each. A list sent out of an outlet holds at most 256 items and 1024 characters. A message that does not fit is refused: it changes nothing, sends nothing and is not logged. append and insert are the exception: they add the elements that fit and drop the rest. The same refusal happens when two threads use one array at the same moment, for example a millisecond .metro and the audio thread: the second one does nothing rather than wait. See Size limits.

Safe on the audio thread: no message allocates memory, takes a lock or waits.

Inlets

#	Label	Accepts	Range	Description
0	in	BANG, LIST	at most 256 elements	append, insert, set, get, delete, clear, getsize or getvalue (see the notes). A bang sends the array’s reference out of outlet 1. A refused message changes nothing.

Outlets

#	Label	Type	Range	Description
0	data	ANY	—	The element “get” fetched, the length “getsize” reports, or the whole array for “getvalue”. Numbers leave as an int or a float by their spelling, anything else as a symbol.
1	reference	LIST	—	“array <name>” on a bang: the reference the other .array objects accept. Nothing is sent when the array has no name.
2	miss	BANG	—	Bang when “get” names an index the array does not have.

Parameters

Name	Default	Range	Description
name	—	any identifier	The shared name: every .array with this name in the patcher uses the same contents. Fixed when the object is created. Empty gives this object a private array.

`.array.at`#

Outputs the element at a position in a named array. Send a position to fetch it, or a list of positions to fetch several at once; a bang fetches the last position again. A position the array does not have bangs the miss outlet.

Kind:: Control-rate

An int moves the remembered position even when the fetch misses, so a bang after the array has grown finds the element. A list of positions is a one-off fetch: it does not change the remembered position, and it is answered whole or not at all. Each .array.at keeps its own position, so several of them can read one array independently.

Use .array.wrap when positions past the end should wrap around instead of missing.

Inlets

#	Label	Accepts	Range	Description
0	index	FLOAT, INT, BANG, LIST	0-255	An int fetches the element at that position and remembers the position; a bang fetches at the remembered position, and so does the bound array’s reference. A list of positions fetches them all at once. A float is truncated; a negative position is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	The element, as an int, float or symbol by its spelling. A list of positions gives one list, in the order asked.
1	miss	BANG	—	Bang when a position is not in the array. For a list of positions, one bang if any of them is missing, and nothing leaves outlet 0.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
index	0	0-255	The position a bang fetches before any position arrives.

`.array.change`#

Reports whether a named array has changed since it was last polled. Each bang sends 1 or 0, and on a change also sends the array’s reference, so work further down only runs when something moved.

Kind:: Control-rate

A change is any difference in length, or in the spelling of an element at any position: 7 and 7. differ, and 10 20 differs from 20 10. The object starts out remembering an empty array, so the first poll of an array that already holds elements reports a change.

Use the right inlet when the array was changed on purpose and that change should not count: it takes the current contents as the new starting point and sends nothing. Changing the object’s arguments, or renaming the patcher, also resets the remembered state to empty.

[.metro 100] -> [.array.change steps] -> reference -> [.array.iter steps]

The walk only runs when steps has actually changed.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: compare the array with the last state seen, then remember the array as it is now.
1	set baseline	LIST	—	The bound array’s reference “array <name>” makes the array’s current contents the last state seen, without output. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	“array <name>” when the poll found a change, sent after outlet 1. Nothing is sent when the object has no name.
1	changed	INT	0 or 1	1 when the array differs from the last state seen, 0 when it does not. Sent on every poll.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to watch: the .array with this name in the same patcher. Empty watches a private, empty array.

`.array.compare`#

Compares two named arrays. A bang sends 1 when they hold the same elements in the same order, and 0 when they do not.

Kind:: Control-rate

Elements are compared by spelling, so 7 and 7. differ, and order matters: 10 20 does not equal 20 10. Both arguments may name the same array.

Inlets

#	Label	Accepts	Range	Description
0	compare	BANG, LIST	—	Bang, or the left array’s reference “array <name>”: compare the two arrays.
1	right reference	LIST	—	Accepts the right array’s reference “array <name>” and ignores it, so its reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	equal	INT	0 or 1	1 when both arrays have the same length and the same element at every position, otherwise 0. Two empty arrays are equal.

Parameters

Name	Default	Range	Description
left	—	any identifier	Name of the left array: the .array with this name in the same patcher. Empty uses a private, empty array.
right	—	any identifier	Name of the right array, found the same way. Empty uses a private, empty array.

`.array.concat`#

Outputs the elements of two named arrays as one list: the left array followed by the right. Neither array is changed.

Kind:: Control-rate

The result is a list, not a new array. To store it, send it to .array.push on another array, which appends a whole list. If the joined list is longer than a list can be, nothing is sent. Both arguments may name the same array, which sends it twice in a row.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the left array’s reference “array <name>”: send the two arrays as one list.
1	right reference	LIST	—	Accepts the right array’s reference “array <name>” and ignores it, so its reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	concatenation	ANY	—	The left array’s elements followed by the right’s, as one list, repeats included. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when both arrays are empty.

Parameters

Name	Default	Range	Description
left	—	any identifier	Name of the left array: the .array with this name in the same patcher. Empty uses a private, empty array.
right	—	any identifier	Name of the right array, found the same way. Empty uses a private, empty array.

`.array.deserialize`#

Fills a named array from a JSON array such as [60,62.5,”kick”], replacing its contents. The text is parsed in the background, and the array’s reference is sent once the new contents are in place.

Kind:: Control-rate

The document uses the same JSON form a saved patch uses for an .array. Each value becomes one element:

numbers keep their form: 60 becomes an int, 62.5 a float,
strings become words; an empty string is skipped,
true and false become 1 and 0,
null, nested arrays and objects are skipped,
elements longer than 64 characters, and elements past the 256th, are dropped while the rest still loads.

Text that is not a JSON array (malformed text, a number, an object) changes nothing: the array keeps its contents and no reference is sent.

The text is parsed on the engine’s background pool, so the new contents appear one audio block after the message. The object is safe to use from the audio thread.

Limits

A document is at most 255 characters. At most 16 .array.deserialize objects can exist in the engine at the same time; a seventeenth logs an error when it is created and refuses every document.

Inlets

#	Label	Accepts	Range	Description
0	json	LIST	at most 255 characters	A JSON array as one message, for example [60,62.5,”kick”]. Text longer than 255 characters is refused, and so is a document that arrives while the previous one is still being parsed.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	“array <name>” once the parsed contents are in the array, one audio block after the document arrived. Nothing is sent when parsing fails or the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to fill: the .array with this name in the same patcher. Empty fills a private array.

`.array.every`#

Tests every number in a named array with an expression. A bang sends 1 when the expression is true (non-zero) for all of them, and 0 when it is false for any.

Kind:: Control-rate

Words are skipped: the expression only sees elements that read as numbers. An array without numbers passes, because nothing in it fails. The test stops at the first element that fails.

[.array.every notes $i1 >= 60 && $i1 < 72]   are all notes between C4 and B4?

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	verdict	INT	0 or 1	1 when the expression is true for every numeric element, otherwise 0. An array without numbers gives 1.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1 and $2	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the element (as a float or an int), $f2 or $i2 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.expr`#

Evaluates an expression for each element of a named array and sends the results as one list, for example $i1 + 12 to transpose. The array itself is not changed.

Kind:: Control-rate

Each numeric element is replaced in the output by the expression’s result, an int or a float following the expression’s types (see .expr). Words pass through as they are, so the output has one item per element. If the output is longer than a list can be, the items past the limit are dropped.

.array.map performs the same calculation and writes the results back into the array.

[.array.expr chord $i1 + 12]   chord 60 64 67  ->  72 76 79

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	results	ANY	—	One result per element, in order; words pass through unchanged. A single result leaves as an int or float, several as a list.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1 and $2	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the element (as a float or an int), $f2 or $i2 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.fill`#

Fills a named array with a number of copies of one value, replacing its contents. Use it to clear an array, or to give it a size before writing to it by position.

Kind:: Control-rate

A fill replaces everything: the array becomes exactly count copies of the value, so a smaller count shrinks the array and 0 empties it.

Because the other objects refuse positions past the end of an array, a fill is the usual way to give an array its size before writing to it by position:

[.array.fill steps 16 0]   bang  ->  steps holds 16 zeros
set 3 1  ->  [.array steps]       steps now has a 1 at position 3

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	one atom, at most 64 characters	A bang fills with the stored count and value, and so does the bound array’s reference. An int, float or word fills with that value instead, without storing it. A list of more than one item is refused.
1	count	FLOAT, INT	0-256	Sets the number of copies for the next fill. A float is truncated; values outside 0-256 are refused.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each fill, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to fill: the .array with this name in the same patcher. Empty fills a private array.
count	0	0-256	The number of copies a fill makes. 0 (the default) makes a fill empty the array.
value	0	one atom, at most 64 characters	The value a bang fills with: one item of at most 64 characters. 7 is stored as an int, 7. as a float, anything else as a word.

`.array.filter`#

Removes from a named array every element for which an expression is false (zero), keeping the rest in order. Words are removed too, because the expression only sees numbers.

Kind:: Control-rate

An element stays when the expression gives a non-zero result for it. Words are always removed, because the expression cannot see them. The elements that stay keep their order and move down to close the gaps, so positions change for every object that uses the array.

[.array.filter notes $i1 >= 60]   notes 48 60 55 72  ->  60 72

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each change, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1 and $2	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the element (as a float or an int), $f2 or $i2 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.flatten`#

Outputs the elements of several named arrays as one list, in the order the arrays are named, up to 16 arrays. None of the arrays is changed.

Kind:: Control-rate

An element is a single value, so an array cannot contain other arrays. To work with a group of arrays, give each one a name and list the names: .array.flatten verse chorus bridge sends the three arrays, one after the other, as one list. A name may appear more than once.

The arrays are read one after the other, not all in the same instant. If the combined list is longer than a list can be, nothing is sent.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the first array’s reference “array <name>”: send all the arrays as one list.
1	sources reference	LIST	—	Accepts the reference “array <name>” of any array after the first and ignores it, so their reference outlets can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	flattened	ANY	—	Every array’s elements, in the order the arrays are named, as one list. Repeats are kept. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when every array is empty.

Parameters

Name	Default	Range	Description
first	—	any identifier	Name of the first array: the .array with this name in the same patcher. Empty uses a private, empty array.
others	—	up to 15 identifiers	The names of up to 15 more arrays, in the order their elements are sent. With more than 16 arrays in all, every bang is refused.

`.array.foreach`#

Evaluates an expression for each element of a named array and sends the results one at a time, first to last, then bangs its done outlet.

Kind:: Control-rate

Works like .array.iter with the expression applied on the way out: each numeric element leaves as the expression’s result, an int or a float following the expression’s types (see .expr). Words leave unchanged.

The object walks a copy of the array taken when the bang arrives. Changes to the array during the walk, including changes made by the objects connected to outlet 0, do not affect it. A bang that arrives during a walk, for example through a cord from an outlet back to the inlet, is refused.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	result	ANY	—	One result per element, first to last, as an int or a float. Words pass through unchanged.
1	done	BANG	—	Bang after the last result, also when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1 and $2	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the element (as a float or an int), $f2 or $i2 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.group`#

Groups the equal elements of a named array. A bang sends one list per distinct value, holding that value as many times as it occurs, then bangs the done outlet.

Kind:: Control-rate

Elements are equal when they are spelled the same, so 7 and 7. form separate groups. The length of each group is how often its value occurs.

notes 60 64 60 67 64 60  ->  60 60 60,  then 64 64,  then 67,  then done

The groups come from a copy of the array taken when the bang arrives. If any group would be longer than a list can be, nothing is sent. A bang that arrives while the groups are being sent is refused.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the groups, then bang the done outlet. A trigger that arrives while the groups are being sent is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	group	ANY	—	One message per distinct value, in order of first appearance, holding the value as many times as it occurs. A value that occurs once leaves as a single int, float or symbol.
1	done	BANG	—	Bang after the last group, also when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.index`#

Looks up a value in a named array. The position of the first matching element leaves the left outlet; when no element matches, the right outlet bangs.

Kind:: Control-rate

A value matches an element with exactly the same spelling: an int 7 finds 7 but not 7., and a float 7. finds 7. but not 7. Words match case-sensitively. Only the first match is reported.

.array.indexof does the same search but reports a miss as -1 instead of on a separate outlet.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	one atom	An int, float or word searches for that value and remembers it; a bang searches for the remembered value again, and so does the bound array’s reference. A list of more than one item is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	position	INT	0-255	The position of the first matching element.
1	miss	BANG	—	Bang when no element matches.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to search: the .array with this name in the same patcher. Empty searches a private, empty array.
value	—	one atom	The value a bang searches for before any value arrives. Without it, a bang is refused until a value has arrived.

`.array.indexmap`#

Reorders a named array by a list of positions: the new array holds the elements at those positions, in that order. Positions may repeat or be left out.

Kind:: Control-rate

Each entry in the map picks one element of the array as it was before the reorder. An entry may appear more than once, which copies the element, and positions that are left out drop their element. A position past the end of the array picks nothing, so the result can be shorter than the map.

notes 60 62 64 67,  map 3 2 1 0  ->  67 64 62 60
notes 60 62 64 67,  map 0 0 2    ->  60 60 64

.array.sort, .array.scramble and .array.shuffle send the order they applied in this form. Send that order to the left inlet of an .array.indexmap on a second array, and the second array gets the same new order.

Inlets

#	Label	Accepts	Range	Description
0	trigger	FLOAT, INT, BANG, LIST	0-255 each	A bang applies the stored map, and so does the bound array’s reference. A list of positions, or a single int, is applied at once and not stored. A float is truncated; a negative position refuses the whole list.
1	index map	FLOAT, INT, LIST	0-255 each	A list of positions, or a single int, to store for the next bang. A float is truncated. A list with a negative position, or more than 256 entries, is refused.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to reorder: the .array with this name in the same patcher. Empty uses a private, empty array.
map	—	0-255 each	The positions a bang applies before a map arrives on the middle inlet. Without a map, a bang is refused.

`.array.indexof`#

Outputs the position of the first element of a named array that matches a value, or -1 when no element matches.

Kind:: Control-rate

A value matches an element with exactly the same spelling: an int 7 finds 7 but not 7., and a float 7. finds 7. but not 7. Words match case-sensitively. Only the first match is reported.

.array.index does the same search but bangs a separate outlet on a miss, which is easier to route on.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	one atom	An int, float or word searches for that value and remembers it; a bang searches for the remembered value again, and so does the bound array’s reference. A list of more than one item is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	position	INT	-1, or 0-255	The position of the first matching element, or -1 when no element matches.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to search: the .array with this name in the same patcher. Empty searches a private, empty array.
value	—	one atom	The value a bang searches for before any value arrives. Without it, a bang is refused until a value has arrived.

`.array.insert`#

Inserts a value or a list into a named array at a stored position, moving later elements up. Set the position on the middle inlet, then send what to insert to the left inlet.

Kind:: Control-rate

A list is inserted in the order sent: a b c inserted at position 1 leaves a b c starting at position 1. The insert is all or nothing: if the position is past the end, or the array cannot take the whole list, nothing is inserted.

The array’s reference is refused on the left inlet, so a cord wired there by mistake does not insert the words array <name>. .array.remove is the opposite operation.

Inlets

#	Label	Accepts	Range	Description
0	element	FLOAT, INT, LIST	at most 256 elements	An int, float, word or list to insert at the stored position. A list keeps its order and is inserted whole, or refused whole when the position is past the end or the array cannot take all of it.
1	position	FLOAT, INT	0-256	Sets the position for the next insert, from 0 to the array’s length (the length appends). A float is truncated; a negative value is refused.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each insert, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
index	0	0-256	The insert position before one arrives on the middle inlet.

`.array.iter`#

Sends the elements of a named array one at a time, first to last, then bangs its done outlet. Use it to do something for each element.

Kind:: Control-rate

Each element’s message is fully handled by everything connected to outlet 0 before the next one leaves. The object walks a copy of the array taken when the bang arrives, so changes to the array during the walk, including changes made by the objects connected to outlet 0, do not affect it: every element the array held at that moment is sent exactly once.

A bang that arrives during a walk, for example through a cord from an outlet back to the inlet, is refused.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send every element, then bang the done outlet. A trigger that arrives while the elements are being sent is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	One element per message, first to last, as an int, float or symbol by its spelling.
1	done	BANG	—	Bang after the last element, also when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.join`#

Joins the elements of a named array into a single word, with an optional separator between them: c4 e4 g4 joined with - gives c4-e4-g4.

Kind:: Control-rate

The result leaves as the value it spells: c4 e4 g4 joined with - gives the symbol c4-e4-g4, and 1 2 joined without a separator gives the int 12.

The joined word may be up to 1280 characters long, which is more than an array element can hold, so storing it back into an array can be refused. A longer result is not sent.

.array.tosymbol joins without a separator and always sends a symbol; .array.tostring separates the elements with spaces.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the joined word.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	joined	ANY	—	The joined word. When it reads as a number it leaves as an int or a float, otherwise as a symbol.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
separator	—	any token	Text placed between each pair of elements, one word without spaces. Empty joins the elements directly.

`.array.length`#

Outputs the number of elements in a named array when it receives a bang.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the array’s length.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	length	INT	0-256	The number of elements in the array; 0 when it is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to measure: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.map`#

Applies an expression to every numeric element of a named array and writes the results back, for example $i1 + 12 to transpose. Words stay where they are.

Kind:: Control-rate

Each numeric element is replaced by the expression’s result, an int or a float following the expression’s types (see .expr). Words stay where they are, so the length and the positions do not change. The whole array is rewritten in one step; no other object sees it half done.

.array.expr performs the same calculation and sends the results without changing the array.

[.array.map chord $i1 + 12]   chord 60 64 67  ->  72 76 79

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each change, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1 and $2	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the element (as a float or an int), $f2 or $i2 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.max`#

Outputs the largest number in a named array. Words are skipped.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the result.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	maximum	ANY	—	The largest numeric element, as the int or float it is spelled as. When several are equal (7 and 7. count as equal), the first one.
1	empty	BANG	—	Bang when the array holds no numbers.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.mean`#

Outputs the average of the numbers in a named array, as a float. Words are skipped.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the result.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	mean	FLOAT	—	The average of the numeric elements, always a float, also when they are all ints.
1	empty	BANG	—	Bang when the array holds no numbers.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.median`#

Outputs the median of the numbers in a named array, as a float. Words are skipped, and the array itself is not reordered.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the result.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	median	FLOAT	—	The middle value in sorted order; with an even count, the average of the two middle values. Always a float.
1	empty	BANG	—	Bang when the array holds no numbers.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.min`#

Outputs the smallest number in a named array. Words are skipped.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the result.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	minimum	ANY	—	The smallest numeric element, as the int or float it is spelled as. When several are equal (7 and 7. count as equal), the first one.
1	empty	BANG	—	Bang when the array holds no numbers.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.mode`#

Outputs the element that occurs most often in a named array. Words count too, and elements are compared by spelling, so 7 and 7. are different elements.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the result.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	mode	ANY	—	The most frequent element, as an int, float or symbol by its spelling. On a tie, the one that appears first.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.pop`#

Removes the last element of a named array and outputs it. On an empty array, the empty outlet bangs instead.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: remove the last element and send it.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	The removed element, as an int, float or symbol by its spelling.
1	empty	BANG	—	Bang when the array is empty: the end of a loop that empties the array.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.push`#

Appends a value or a list to the end of a named array, then sends the array’s reference. With .array.pop it makes a stack, with .array.shift a queue.

Kind:: Control-rate

Pair it with .array.pop for a stack (last in, first out) or with .array.shift for a queue (first in, first out).

The array’s reference is refused on the left inlet, so a cord wired there by mistake does not append the words array <name>.

Inlets

#	Label	Accepts	Range	Description
0	element	FLOAT, INT, LIST	at most 256 elements	An int, float, word or list to append. A list is appended whole, in order, or refused whole when the array cannot take all of it.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each change, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.random`#

Outputs a randomly chosen element of a named array. A seed makes the sequence of picks repeat on every run.

Kind:: Control-rate

Every pick is independent, so the same element can come up twice in a row. Use .urn to draw without repeats.

A bang on an empty array does not use up a random number, so a seeded sequence of picks is not shifted by it.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send one element picked at random.
1	seed	FLOAT, INT	any int	An int restarts the random sequence. A non-zero seed repeats the same picks every run; 0 gives an unpredictable sequence. A float is truncated.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	The picked element, as an int, float or symbol by its spelling.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to pick from: the .array with this name in the same patcher. Empty uses a private, empty array.
seed	0	any int	Random seed. A non-zero seed repeats the same picks every run; 0 gives an unpredictable sequence.

`.array.reduce`#

Combines the numbers in a named array into one value with an expression, such as $f1 + $f2 for a sum. $f1 is the result so far and $f2 the next element.

Kind:: Control-rate

The running result starts as the first numeric element. The expression then runs once for each following numeric element, and its result becomes the new running result. Words are skipped.

$f1 + $f2: the sum,
$f1 * $f2: the product,
max($f1, $f2): the largest value.

With a single numeric element, that element is the answer and the expression does not run.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	result	ANY	—	The final value, an int or a float. With a single numeric element, that element as it is.
1	empty	BANG	—	Bang when the array holds no numbers.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1, $2 and $3	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the running result, $f2 or $i2 the element and $f3 or $i3 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.regexp`#

Outputs the elements of a named array that match a regular expression, as one list. When nothing matches, the right outlet bangs. The array itself is not changed.

Kind:: Control-rate

Each element is matched as text, and the pattern may match anywhere in it: ^c keeps elements that start with c, and ^[0-9]+$ keeps whole numbers. Anchor the pattern with ^ and $ to match the whole element.

The result is sent whole or not at all: when the matching elements do not fit in one list, or the matching takes too long, nothing is sent.

For capture groups or substitutions per element, feed .array.iter into .regexp.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: match every element against the pattern. Refused when the pattern is missing or did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	matched	ANY	—	The matching elements, in order, as one list; a single match leaves as an int, float or symbol.
1	no match	BANG	—	Bang when no element matches, or the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to search: the .array with this name in the same patcher. Empty searches a private, empty array.
pattern	—	any pattern	The regular expression, as one word in .regexp syntax; write s for a space. A malformed pattern is logged and the object then does nothing.

`.array.remove`#

Removes the element at a position from a named array and outputs it; later elements move down. A position the array does not have bangs the miss outlet.

Kind:: Control-rate

An int moves the remembered position even when nothing is removed. Only one position can be removed per message: after each removal the later elements move down, so a list of positions would no longer point at the elements it meant.

.array.insert is the opposite operation. .array’s own delete removes an element without sending it.

Inlets

#	Label	Accepts	Range	Description
0	position	FLOAT, INT, BANG, LIST	0-255	An int removes the element at that position and remembers the position; a bang removes at the remembered position, and so does the bound array’s reference. A float is truncated; a negative position is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	The removed element, as an int, float or symbol by its spelling.
1	miss	BANG	—	Bang when there is no element at the position.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
index	0	0-255	The position a bang removes at before any position arrives.

`.array.replace`#

Replaces every occurrence of a value in a named array with another value. Sends how many elements were replaced, then the array’s reference.

Kind:: Control-rate

Matches are exact: 7 replaces elements spelled 7 but not 7., and words match case-sensitively. Positions do not change; only the matching elements get the new value.

A replacement value must be set, as the third argument or on the middle inlet, before anything can be replaced. To replace only the first occurrence, find it with .array.indexof and send set <index> <value> to the .array.

Inlets

#	Label	Accepts	Range	Description
0	find	FLOAT, INT, BANG, LIST	one atom, at most 64 characters	An int, float or word: replace every element spelled this way, and remember the value. A bang replaces with the remembered values, and so does the bound array’s reference. A list of more than one item is refused.
1	replacement	FLOAT, INT, LIST	one atom, at most 64 characters	An int, float or word to write in place of each match. Stored for the next replace; nothing changes until the left inlet triggers.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each replace, also when nothing matched. Sent after outlet 1. Nothing is sent when the object has no name.
1	count	INT	0-256	How many elements were replaced; 0 when none matched. Sent before the reference.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to change: the .array with this name in the same patcher. Empty uses a private, empty array.
find	—	one atom, at most 64 characters	The value a bang replaces before one arrives on the left inlet.
replace	—	one atom, at most 64 characters	The value written in place of each match. Until one is set here or on the middle inlet, every trigger is refused.

`.array.reverse`#

Reverses the order of the elements of a named array, then sends the array’s reference.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: reverse the array.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to reorder: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.rotate`#

Rotates the elements of a named array by a number of positions, wrapping around the ends. Positive amounts move elements toward the end, negative toward the start.

Kind:: Control-rate

Rotating 1 2 3 4 by 1 gives 4 1 2 3; by -1 it gives 2 3 4 1. Any amount works: it is taken modulo the length, so rotating by the length leaves the array as it was.

Inlets

#	Label	Accepts	Range	Description
0	trigger	FLOAT, INT, BANG, LIST	any int	A bang rotates by the stored amount, and so does the bound array’s reference. An int rotates by that amount instead, without storing it. A float is truncated.
1	amount	FLOAT, INT	any int	Sets the amount for the next bang. Any int; positive moves elements toward the end, negative toward the start. A float is truncated.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to reorder: the .array with this name in the same patcher. Empty uses a private, empty array.
amount	0	any int	The amount a bang rotates by before one arrives on the middle inlet.

`.array.routepass`#

Routes a named array by what it contains: its reference leaves the outlet of the first listed value the array holds, or the rightmost outlet when it holds none of them.

Kind:: Control-rate

The values after the name each get an outlet, in order, and one more outlet on the right catches the arrays that hold none of them. A trigger checks the values from left to right and sends the array’s reference, not its contents, out of the outlet of the first value the array holds anywhere. Exactly one outlet fires.

[.array.routepass chord 60 61 62]
chord 64 61 67  ->  outlet 1 (61)
chord 64 67     ->  outlet 3 (none of the values)

A value matches an element with exactly the same spelling, so 5 does not match 5.0. A value that appears twice in the arguments only uses its first outlet. An empty array always goes to the rightmost outlet, so a chain of .array.routepass objects can test one array against more values.

A trigger that arrives while a reference is being sent, for example through a cord from an outlet back to the inlet, is refused.

Inlets

#	Label	Accepts	Range	Description
0	route	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the array’s reference out of the outlet of the first value it holds. A trigger that arrives while a reference is being sent is refused.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	none	LIST	—	The array’s reference when the array holds none of the values, or is empty. Wire it to another .array.routepass to keep testing.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to route: the .array with this name in the same patcher. Without a name, the object sends nothing.
values	—	any list of numbers and symbols	The values to test for, one outlet each from left to right, plus a rightmost outlet for no match. A value matches an element with exactly the same spelling. At most 256.

`.array.scramble`#

Shuffles the elements of a named array into a random order, and sends the order it applied so another array can be put in the same order. The same object as .array.shuffle.

Kind:: Control-rate

The order outlet sends, for each new position, the position the element came from. Send it to the left inlet of an .array.indexmap on a second array, and that array is shuffled the same way:

[.array.scramble notes]  order outlet  ->  [.array.indexmap velocities]

.array.shuffle is the same object under another name.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: shuffle the array into a new random order.
1	seed	FLOAT, INT	any int	An int restarts the random sequence. A non-zero seed repeats the same shuffles every run; 0 gives an unpredictable sequence. A float is truncated.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name.
1	order	LIST	0-255 each	The order applied: for each new position, the position the element came from. Sent before the reference. Send it to .array.indexmap to put another array in the same order. Nothing is sent for an empty array.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to reorder: the .array with this name in the same patcher. Empty uses a private, empty array.
seed	0	any int	Random seed. A non-zero seed repeats the same shuffles every run; 0 gives an unpredictable sequence.

`.array.sect`#

Outputs the elements two named arrays have in common, each once, as one list in the left array’s order. Neither array is changed.

Kind:: Control-rate

Elements are compared by spelling, so 7 and 7. are different elements. A value that repeats in the left array appears once in the result.

[.array.sect left right]   left 60 64 67,  right 67 71 74  ->  67

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the left array’s reference “array <name>”: send the result.
1	right reference	LIST	—	Accepts the right array’s reference “array <name>” and ignores it, so its reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	intersection	ANY	—	The left array’s elements that the right array also holds, each once, in the left array’s order. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when the arrays have no element in common.

Parameters

Name	Default	Range	Description
left	—	any identifier	Name of the left array: the .array with this name in the same patcher. Empty uses a private, empty array.
right	—	any identifier	Name of the right array, found the same way. Empty uses a private, empty array.

`.array.shift`#

Removes the first element of a named array and outputs it; the other elements move down one position. On an empty array, the empty outlet bangs instead.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: remove the first element and send it.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	The removed element, as an int, float or symbol by its spelling.
1	empty	BANG	—	Bang when the array is empty: the end of a loop that empties the array.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.shuffle`#

Shuffles the elements of a named array into a random order, and sends the order it applied so another array can be put in the same order. The same object as .array.scramble.

Kind:: Control-rate

The order outlet sends, for each new position, the position the element came from. Send it to the left inlet of an .array.indexmap on a second array, and that array is shuffled the same way:

[.array.shuffle notes]  order outlet  ->  [.array.indexmap velocities]

.array.scramble is the same object under another name.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: shuffle the array into a new random order.
1	seed	FLOAT, INT	any int	An int restarts the random sequence. A non-zero seed repeats the same shuffles every run; 0 gives an unpredictable sequence. A float is truncated.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name.
1	order	LIST	0-255 each	The order applied: for each new position, the position the element came from. Sent before the reference. Send it to .array.indexmap to put another array in the same order. Nothing is sent for an empty array.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to reorder: the .array with this name in the same patcher. Empty uses a private, empty array.
seed	0	any int	Random seed. A non-zero seed repeats the same shuffles every run; 0 gives an unpredictable sequence.

`.array.slice`#

Outputs a range of elements of a named array, from a start position up to but not including an end position. The array itself is not changed.

Kind:: Control-rate

The range runs from start up to, but not including, end. An end of 0, or one past the end of the array, means “to the end”. When end is at or before start, the range is empty.

notes 60 62 64 67
[.array.slice notes 1 3]  ->  62 64
[.array.slice notes 2]    ->  64 67

.array.subarray includes the end position and can read backwards.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the elements in the range.
1	start	FLOAT, INT	0-255	Sets the first position of the range. A float is truncated; a negative value is refused.
2	end	FLOAT, INT	0-256	Sets the position where the range stops; that element is not included. 0, or past the end of the array, means the end. A float is truncated; a negative value is refused.
3	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	piece	ANY	—	The elements from start up to, but not including, end, as one list. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when the range holds no elements, for example when the array is empty or the start is past its end.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.
start	0	0-255	The first position of the range before one arrives on the start inlet.
end	—	0-256	The position where the range stops (not included). Empty or 0 means the end of the array.

`.array.some`#

Tests the numbers in a named array with an expression. A bang sends 1 when the expression is true (non-zero) for at least one of them, and 0 when it is true for none.

Kind:: Control-rate

Words are skipped: the expression only sees elements that read as numbers. An array without numbers gives 0. The test stops at the first element that passes.

[.array.some notes $i1 < 48]   is any note below C3?

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: run the expression over the array. Refused when the expression did not compile.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	verdict	INT	0 or 1	1 when the expression is true for at least one numeric element, otherwise 0. An array without numbers gives 0.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
expression	—	any expression over $1 and $2	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the element (as a float or an int), $f2 or $i2 its position. It only runs for numeric elements. A malformed expression is logged and the object then does nothing.

`.array.sort`#

Sorts the elements of a named array, ascending or descending, with numbers before words. Also sends the order it applied, so another array can be put in the same order.

Kind:: Control-rate

Numbers come before words in both directions. Numbers are compared by value, so 7 and 7. count as equal; words are compared character by character, with the shorter first when one starts the other. Equal elements keep their order.

The order outlet sends, for each new position, the position the element came from. Send it to the left inlet of an .array.indexmap on a second array, and that array is put in the same order. This keeps, for example, an array of velocities matched to an array of notes after the notes are sorted.

[.array.sort notes]  order outlet  ->  [.array.indexmap velocities]

Inlets

#	Label	Accepts	Range	Description
0	trigger	FLOAT, INT, BANG, LIST	any int	A bang sorts in the stored direction, and so does the bound array’s reference. An int sorts in that direction instead, without storing it: negative is descending, anything else ascending. A float is truncated.
1	direction	FLOAT, INT	any int	Sets the direction for the next bang: negative sorts descending, anything else ascending. A float is truncated.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each sort, so further .array objects can be chained. Nothing is sent when the object has no name.
1	order	LIST	0-255 each	The order applied: for each new position, the position the element came from. Sent before the reference. Send it to .array.indexmap to put another array in the same order. Nothing is sent for an empty array.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to sort: the .array with this name in the same patcher. Empty uses a private, empty array.
direction	0	any int	The direction a bang sorts in: negative is descending, anything else (including the default 0) ascending.

`.array.split`#

Splits a named array in two at a position: the elements before it leave the left outlet and the rest leave the right outlet, right first. The array itself is not changed.

Kind:: Control-rate

The position is the number of elements in the left half: 0 puts everything in the right half, and the length (or more) puts everything in the left half. An empty half sends nothing, which a patch that keeps splitting off the first element can use to stop.

[.array.split notes 1]   notes 60 62 64  ->  right: 62 64,  then left: 60

If either half is longer than a list can be, nothing is sent.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: split at the stored position.
1	position	FLOAT, INT	0-256	Sets the split position: the number of elements in the left half. A float is truncated; a negative value is refused.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	head	ANY	—	The elements before the split position, sent after the right half. Nothing is sent when this half is empty.
1	tail	ANY	—	The elements from the split position on, sent first. Nothing is sent when this half is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.
position	0	0-256	The split position before one arrives on the middle inlet: the number of elements in the left half.

`.array.stddev`#

Outputs the standard deviation of the numbers in a named array, as a float. Words are skipped.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the result.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	standard deviation	FLOAT	0 or more	The population standard deviation (divided by the count, not the count minus one), as a float. A single number gives 0.
1	empty	BANG	—	Bang when the array holds no numbers.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.stream`#

Appends incoming values to a named array and keeps only the most recent ones: a sliding window of a set size. Sends the array’s reference each time the window is full.

Kind:: Control-rate

Each value is appended to the array. Once the array holds size values, every new value pushes the oldest one off the front, so the array always holds the latest size values. A list counts as one value per item.

After every message the right outlet reports how many values are still missing, and the reference leaves only when the window is full. Wire the reference to a statistics object to analyse each full window:

[.array.stream recent 8]  reference  ->  [.array.mean recent]

A bang reports the current state without adding a value. A smaller size takes effect at the next message, which drops the extra elements.

Inlets

#	Label	Accepts	Range	Description
0	value	FLOAT, INT, BANG, LIST	one or more atoms, each at most 64 characters	An int, float, word or list to append; once the window is full, the oldest elements drop off the front. A bang reports again without appending, and so does the bound array’s reference.
1	size	FLOAT, INT	1-256	Sets the window size. A float is truncated; values outside 1-256 are refused.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each message, but only when the window is full. Sent after outlet 1. Nothing is sent when the object has no name.
1	shortfall	INT	0-255	How many more values the window needs before it is full; 0 when it is full. Sent after every value or bang.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to fill: the .array with this name in the same patcher. Empty uses a private array.
size	0	1-256	The window size: how many of the latest values the array keeps. Without one, everything is refused until a size arrives on the middle inlet.

`.array.sub`#

Outputs a range of elements of a named array, both ends included; with the end before the start, the range is sent in reverse. The same object as .array.subarray.

Kind:: Control-rate

The range runs from start to end, both included. A missing end, or one past the last element, means “to the end”. When end is before start, the elements are sent from start down to end.

notes 60 62 64 67
[.array.sub notes 1 2]  ->  62 64
[.array.sub notes 3 1]  ->  67 64 62

.array.subarray is the same object under another name. .array.slice leaves out the end position.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the elements in the range.
1	start	FLOAT, INT	0-255	Sets the first position of the range. A float is truncated; a negative value is refused.
2	end	FLOAT, INT	0-255	Sets the last position of the range, which is included. Past the end of the array means the end; before the start sends the range reversed. A float is truncated; a negative value is refused.
3	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	piece	ANY	—	The elements from start to end, both included, as one list; reversed when the end is before the start. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when the range holds no elements, for example when the array is empty or the start is past its end.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.
start	0	0-255	The first position of the range before one arrives on the start inlet.
end	—	0-255	The last position of the range (included). Empty, or past the end of the array, means the end. Before the start sends the range reversed.

`.array.subarray`#

Outputs a range of elements of a named array, both ends included; with the end before the start, the range is sent in reverse. The same object as .array.sub.

Kind:: Control-rate

notes 60 62 64 67
[.array.subarray notes 1 2]  ->  62 64
[.array.subarray notes 3 1]  ->  67 64 62

.array.sub is the same object under another name. .array.slice leaves out the end position.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the elements in the range.
1	start	FLOAT, INT	0-255	Sets the first position of the range. A float is truncated; a negative value is refused.
2	end	FLOAT, INT	0-255	Sets the last position of the range, which is included. Past the end of the array means the end; before the start sends the range reversed. A float is truncated; a negative value is refused.
3	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	piece	ANY	—	The elements from start to end, both included, as one list; reversed when the end is before the start. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when the range holds no elements, for example when the array is empty or the start is past its end.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to read: the .array with this name in the same patcher. Empty uses a private, empty array.
start	0	0-255	The first position of the range before one arrives on the start inlet.
end	—	0-255	The last position of the range (included). Empty, or past the end of the array, means the end. Before the start sends the range reversed.

`.array.thin`#

Removes elements of a named array that repeat the element kept before them. With a tolerance, numbers that close to it count as repeats too, which thins out a stream of values that barely change.

Kind:: Control-rate

Each element is compared with the last element that was kept. It is removed when it is spelled the same, or, with a tolerance above 0, when both are numbers no further apart than the tolerance. Because the comparison is with the last kept element, a slow drift still shows:

[.array.thin values 0.5]   values 0 0.4 0.8 1.2  ->  0 0.8

Words are only removed when they repeat exactly. A value that comes back later, not next to its earlier copy, is kept; use .array.unique to remove every repeat.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: thin the array now.
1	tolerance	FLOAT, INT	0 or greater, finite	Sets the largest difference between two numbers that still counts as a repeat. 0 means exact repeats only. Negative values are refused.
2	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each thin, so further .array objects can be chained. Sent after outlet 1. Nothing is sent when the object has no name.
1	removed	INT	0-255	How many elements were removed; 0 when none. Sent before the reference.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to thin: the .array with this name in the same patcher. Empty uses a private, empty array.
tolerance	0	0 or greater, finite	The largest difference between two numbers that still counts as a repeat. 0 means exact repeats only.

`.array.tolist`#

Outputs all elements of a named array as one list. An array of one element sends that element as a single int, float or symbol.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the converted array.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	list	ANY	—	The elements in order, as a list; a single element leaves as an int, float or symbol. Items past what a list can hold are dropped.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.tostring`#

Outputs all elements of a named array as one text message, separated by spaces. Unlike .array.tolist, a single number is sent as text, ready for objects that work on text.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the converted array.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	string	LIST	—	The elements in order, separated by spaces, always as text. Items past what a list can hold are dropped.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.tosymbol`#

Joins all elements of a named array, without spaces, into one symbol: kick and .wav become kick.wav. The result is always a symbol, even when it looks like a number.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the converted array.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	symbol	LIST	—	The elements joined into one word, always a symbol. Nothing is sent when the array is too long to fit in one message.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.tuplewise`#

Combines two named arrays position by position with an expression, such as $f1 + $f2, and outputs the results as one list. The result is as long as the shorter array.

Kind:: Control-rate

For each position up to the length of the shorter array, the expression runs with the left and right elements. Its result is an int or a float, following the expression’s types (see .expr). Where one of the two elements is a word, the left element is sent unchanged in that position.

[.array.tuplewise a b $i1 + $i2]   a 1 2 3,  b 10 20  ->  11 22

If the result is longer than a list can be, nothing is sent. Both arguments may name the same array.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the left array’s reference “array <name>”: combine the two arrays. Refused when the expression is missing or did not compile.
1	right reference	LIST	—	Accepts the right array’s reference “array <name>” and ignores it, so its reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	combined	ANY	—	One result per position, as a list. Where either element is a word, the left element is passed through. A single result leaves as an int, float or symbol.
1	empty	BANG	—	Bang when either array is empty.

Parameters

Name	Default	Range	Description
left	—	any identifier	Name of the left array: the .array with this name in the same patcher. Empty uses a private, empty array.
right	—	any identifier	Name of the right array, found the same way. Empty uses a private, empty array.
expression	—	any expression over $1..$3	The expression: the rest of the arguments, in .expr syntax. $f1 or $i1 is the left element, $f2 or $i2 the right element and $f3 or $i3 their position. A malformed expression is logged and the object then does nothing.

`.array.union`#

Outputs the elements held by either of two named arrays, each once, as one list. Neither array is changed.

Kind:: Control-rate

Elements are compared by spelling, so 7 and 7. are different elements. Repeats within either array appear once in the result.

[.array.union left right]   left 60 64 60,  right 64 67  ->  60 64 67

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the left array’s reference “array <name>”: send the result.
1	right reference	LIST	—	Accepts the right array’s reference “array <name>” and ignores it, so its reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	union	ANY	—	The left array’s elements, then the right array’s elements the left does not hold, each once. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when both arrays are empty.

Parameters

Name	Default	Range	Description
left	—	any identifier	Name of the left array: the .array with this name in the same patcher. Empty uses a private, empty array.
right	—	any identifier	Name of the right array, found the same way. Empty uses a private, empty array.

`.array.unique`#

Outputs the elements of a named array with repeats removed, each at its first occurrence. The array itself is not changed.

Kind:: Control-rate

Elements are compared by spelling, so 7 and 7. are both kept. To remove only repeats that sit next to each other, or values that are close together, use .array.thin.

Inlets

#	Label	Accepts	Range	Description
0	trigger	BANG, LIST	—	Bang, or the bound array’s reference “array <name>”: send the array without repeats.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	unique	ANY	—	Each distinct element once, in order of first appearance. A single element leaves as an int, float or symbol.
1	empty	BANG	—	Bang when the array is empty.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.unshift`#

Inserts a value or a list at the front of a named array, moving the other elements up, then sends the array’s reference.

Kind:: Control-rate

Inlets

#	Label	Accepts	Range	Description
0	element	FLOAT, INT, LIST	at most 256 elements	An int, float, word or list to insert at the front. A list keeps its order and is inserted whole, or refused whole when the array cannot take all of it.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	reference	LIST	—	The array’s reference “array <name>” after each change, so further .array objects can be chained. Nothing is sent when the object has no name.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.

`.array.wrap`#

Outputs the element at a position in a named array, wrapping around: positions past the end start again at the beginning, and -1 is the last element.

Kind:: Control-rate

Every position is taken modulo the array’s length: with three elements, position 3 reads element 0, position 5 reads element 2, and -1 reads the last element. Fed from a counter, .array.wrap loops over the array forever, like a step sequencer.

Use .array.at when a position past the end should be reported as a miss.

Inlets

#	Label	Accepts	Range	Description
0	index	FLOAT, INT, BANG, LIST	any int	An int fetches the element at that position, wrapped around the array’s length, and remembers the position; a bang fetches at the remembered position, and so does the bound array’s reference. A list of positions fetches them all at once. A float is truncated.
1	array reference	LIST	—	Accepts the bound array’s reference “array <name>” and ignores it, so the array’s reference outlet can be wired here. Anything else is refused.

Outlets

#	Label	Type	Range	Description
0	element	ANY	—	The element, as an int, float or symbol by its spelling. A list of positions gives one list, in the order asked.
1	empty	BANG	—	Bang when the array is empty, so there is nothing to wrap onto. One bang for a list of positions.

Parameters

Name	Default	Range	Description
name	—	any identifier	Name of the array to use: the .array with this name in the same patcher. Empty uses a private, empty array.
index	0	any int	The position a bang fetches before any position arrives. Any int; -1 is the last element.

Arrays

Contents

Arrays#