Array Opcodes
List of Array Opcodes (6.12):
- init initiatlise array
- fillarray fill array with values
- genarray create array with artithmetic sequence
- = create or reset array as copy of another array
- slicearray take slice of an array
- maparray apply a function to an array
- scalearray scale values in an array
- sorta sort an array in ascending order
- sortd sort an array in descending order
- limit and limit1 limit array values
- reshapearray change dimensions of an array
- trim adjust size of a one-dimensional array
- copya2ftab copy array to a function table
- copyf2array copy function table to an array
- tab2array copy a slice from a table to an array
- dot calculate dot product from two arrays
- interleave interleave two arrays to a single one
- deinterleave deinterleave an array to two ones
- getrow get a row from a two-dimensional array
- getcol get a column from a two-dimensional array
- setrow set a row of a two-dimensional array
- setcol set a column of a two-dimensional array
- lenarray returns length of an array
- minarray returns minimum value in an array
- maxarray returns maximum value in an array
- sumarray returns sum of values in an array
- cmp compare two arrays
- printarray print an array
- product calculates the product of an array
- the unary functions ceil, floor round, int, frac, powoftwo, abs, log2, log10, log, exp, sqrt, cos, sin, tan, cosinv, sininv, taninv, sinh, cosh, tanh, cbrt, limit1, and the binary functions taninv2, pow, hypot, fmod, fmax, fmin accept arrays as input.
Some instructions to work with arrays in Csound (see also the array chapter in the Csound FLOSS Manual:)
Variable Name
An array must be created (via init or fillarray) as kMyName plus_ ending brackets. The brackets determine the dimensions of the array. So,
creates a one-dimensional array of length 10, whereas
creates a two-dimensional array with 10 rows and 10 columns.
After the initalization of the array, referring to the array as a whole is done without any brackets. Brackets are only used if an element is indexed:
kArr[] init 10 ;with brackets because of initialization
kLen = lenarray(kArr) ;without brackets
kFirstEl = kArr[0] ;indexing with brackets
The same syntax is used for a simple copy via the '=' operator:
k-rate
Note that most array operations are currently k-rate only. So like any other k-rate opcode, an operation on arrays will be automatically repeated every k-cycle. For instance, this code will repeat re-writing the array with different random values every k-cycle, as long as the instrument runs:
If you want to avoid this, you must organize it in one of the usual ways, for instance by using a trigger:
kArr[] init 10
kTrig metro 1
if kTrig == 1 then ;do the following once a second
kIndx = 0
until kIndx == lenarray(kArr) do
kArr[kIndx] rnd31 10, 0
kIndx += 1
od
endif
Creation/Initialization
The usual way to create an array is with init:
kArr[] init 10 ;creates one-dimensional array with length 10
kArr[][] init 10, 10 ;creates two-dimensional array
A one-dimensional array can also be created and filled with distinct values by the opcode fillarray. This line creates a vector with length 4 and puts in the numbers [1, 2, 3, 4]:
Length
The function lenarray(kArr) reports the length of an array. See example for function lenarray.
Copy Arrays to/from Tables
copies data from an ftable to a vector.
copies data from a vector to an function table.
See examples for opcodes copyf2array and copya2ftab.
Array Operations: Math
+, -, *, / on a Number
If the four basic math operators are used between an array and a scalar (number), the operation is applied to each element. The safest way to do this is to store the result in a new array:
Here is an example of array/scalar operations. It uses the file array_scalar_math.csd.
+, -, *, / on a Second Array
If the four basic math operators are used between two arrays, the operation is applied element by element. The result can be straightforward stored in a new array:
kArr1[] fillarray 1, 2, 3
kArr2[] fillarray 10, 20, 30
kArr3[] = kArr1 + kArr2 ;(kArr3 is now [11, 22, 33])
Here is an example of array operations. It uses the file array_array_math.csd.
Map a Function to an Array
maps the k-rate 1-arg function in the string to every element of the vector.
Possible functions are for instance abs, ceil, exp, floor, frac, int, log, log10, round, sqrt. This is a simple example:
See example for opcode maparray.
Array Operations: min, max, sum, scale, slice
Minimum and Maximum
returns the smallest value in an array, and optionally its index.
returns the largest value in an array, and optionally its index. See examples for opcodes minarray and maxarray.
Sum
returns the sum of all values in kArr. See example for opcode sumarray.
Scale
scales all values in kArr between kMin and kMax.
changes kArr to [1, 1.5, 3, 2, 2.25]. See example for opcode scalearray.
Slice
returns a slice of kArr from index iStart to index iEnd (included).
The array for receiving the slice must have been created in advance:
kArr[] fillarray 1, 2, 3, 4, 5, 6, 7, 8, 9
kArr1[] init 5
kArr2[] init 4
kArr1 slicearray kArr, 0, 4 ;[1, 2, 3, 4, 5]
kArr2 slicearray kArr, 5, 8 ;[6, 7, 8, 9]
See example for opcode slicearray.
Reshape
Use reshapearray to change the shape of an array without changing its capacity (change a 1D to a 2D array and viceversa). See example for opcode reshapearray.
Arrays in UDOs
The dimension of an input array must be declared in two places:
- as k[] or k[][] in the type input list
- as kName[], kName[][] etc in the xin list.
For instance :
Here is an example of an array in an UDO. It uses the file array_udo.csd.
Note that if an opcode (for example inrg), alters arguments on its right hand argument list, an array index should not be used there. Unlike a normal variable, the array won't changed by the opcode.
Credits
This manual page has been written by Joachim Heintz.
July 2013
New in Csound 6.00