.. This file is auto-generated by the Sphinx pre-build hook in ``documentation/source/conf.py`` from ``documentation/source/_data/patcher_objects.json`` and the notes in ``documentation/source/_data/patcher_notes/``. Do not edit by hand — re-run ``python yse.py dump-patcher-meta`` to refresh the JSON, then ``make html`` to re-render this page. 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 :file:`YseEngine/patcher/pObject.h`). The ``~`` prefix marks DSP / audio-rate objects; ``.`` marks control-rate objects. .. contents:: :local: :depth: 1 ``.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 ``: add elements at the end. - ``insert ``: add elements before position ``index``, in the order given. Inserting at the length appends. - ``set ``: replace one element. - ``get ``: send one element out of outlet 0, or bang outlet 2 when there is no element at ``index``. - ``delete ``: 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 `` 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 :ref:`data-sharing` and :ref:`data-saved`. **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 ``, so outlet 1 of an ``.array`` can be wired straight into them. A reference that names a different array is refused (see :ref:`data-references`). - 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. .. code-block:: text 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 :ref:`data-limits`. Safe on the audio thread: no message allocates memory, takes a lock or waits. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.metro 100] -> [.array.change steps] -> reference -> [.array.iter steps] The walk only runs when ``steps`` has actually changed. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " makes the array's current contents the last state seen, without output. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - compare - BANG, LIST - — - Bang, or the left array's reference "array ": compare the two arrays. * - 1 - right reference - LIST - — - Accepts the right array's reference "array " and ignores it, so its reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the left array's reference "array ": send the two arrays as one list. * - 1 - right reference - LIST - — - Accepts the right array's reference "array " and ignores it, so its reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.every notes $i1 >= 60 && $i1 < 72] are all notes between C4 and B4? **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.expr chord $i1 + 12] chord 60 64 67 -> 72 76 79 **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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: .. code-block:: text [.array.fill steps 16 0] bang -> steps holds 16 zeros set 3 1 -> [.array steps] steps now has a 1 at position 3 **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each fill, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.filter notes $i1 >= 60] notes 48 60 55 72 -> 60 72 **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each change, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the first array's reference "array ": send all the arrays as one list. * - 1 - sources reference - LIST - — - Accepts the reference "array " of any array after the first and ignores it, so their reference outlets can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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 ``. ``.array.remove`` is the opposite operation. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each insert, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the joined word. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the array's length. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - length - INT - 0-256 - The number of elements in the array; 0 when it is empty. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.map chord $i1 + 12] chord 60 64 67 -> 72 76 79 **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each change, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the result. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the result. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the result. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the result. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the result. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": remove the last element and send it. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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 ``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each change, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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 `` to the ``.array``. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": reverse the array. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each reorder, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - route - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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: .. code-block:: text [.array.scramble notes] order outlet -> [.array.indexmap velocities] ``.array.shuffle`` is the same object under another name. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.sect left right] left 60 64 67, right 67 71 74 -> 67 **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the left array's reference "array ": send the result. * - 1 - right reference - LIST - — - Accepts the right array's reference "array " and ignores it, so its reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": remove the first element and send it. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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: .. code-block:: text [.array.shuffle notes] order outlet -> [.array.indexmap velocities] ``.array.scramble`` is the same object under another name. **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.some notes $i1 < 48] is any note below C3? **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": run the expression over the array. Refused when the expression did not compile. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.sort notes] order outlet -> [.array.indexmap velocities] **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the result. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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: .. code-block:: text [.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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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``. .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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 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``. .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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: .. code-block:: text [.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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the converted array. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the converted array. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the converted array. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the left array's reference "array ": 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 " and ignores it, so its reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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. .. code-block:: text [.array.union left right] left 60 64 60, right 64 67 -> 60 64 67 **Inlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the left array's reference "array ": send the result. * - 1 - right reference - LIST - — - Accepts the right array's reference "array " and ignores it, so its reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Accepts - Range - Description * - 0 - trigger - BANG, LIST - — - Bang, or the bound array's reference "array ": send the array without repeats. * - 1 - array reference - LIST - — - Accepts the bound array's reference "array " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - Label - Type - Range - Description * - 0 - reference - LIST - — - The array's reference "array " after each change, so further .array objects can be chained. Nothing is sent when the object has no name. **Parameters** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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 " and ignores it, so the array's reference outlet can be wired here. Anything else is refused. **Outlets** .. list-table:: :header-rows: 1 :widths: 6 18 18 18 40 * - # - 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** .. list-table:: :header-rows: 1 :widths: 22 18 18 42 * - 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.