## Array Opcodes

Array Opcodes

List of Array Opcodes (6.12):

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,

`kArr[] init 10`

creates a one-dimensional array of length 10, whereas

`kArr[][] init 10, 10`

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           ;indexing with brackets```

The same syntax is used for a simple copy via the '=' operator:

```kArr1[] fillarray 1, 2, 3, 4, 5
kArr2[] = kArr1              ;creates kArr2 as copy of kArr1```

## 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:

```kArr[] init 10
kIndx  = 0
until kIndx == lenarray(kArr) do
kArr[kIndx] rnd31 10, 0
kIndx += 1
od```

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]:

`kArr[] fillarray 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

`copyf2array kArr, kfn`

copies data from an ftable to a vector.

`copya2ftab kArr, kfn`

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:

```kArr1[] fillarray 1, 2, 3
kArr2[] = kArr1 + 10    ;(kArr2 is now [11, 12, 13])```

Here is an example of array/scalar operations. It uses the file array_scalar_math.csd.

Example 3. Example of array operations

```<CsoundSynthesizer>
<CsOptions>
-n -m128
</CsOptions>
<CsInstruments>

instr 1

;create array and fill with numbers 1..10
kArr1[] fillarray 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

;print content
printf  "%s", 1, "\nInitial content:\n"
kndx    =       0
until kndx == lenarray(kArr1) do
printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr1[kndx]
kndx    +=      1
od

kArr2[] =       kArr1 + 10

;print content
printf  "%s", 1, "\nAfter adding 10:\n"
kndx    =       0
until kndx == lenarray(kArr2) do
printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr2[kndx]
kndx    +=      1
od

;subtract 5
kArr3[] =       kArr2 - 5

;print content
printf  "%s", 1, "\nAfter subtracting 5:\n"
kndx    =       0
until kndx == lenarray(kArr3) do
printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr3[kndx]
kndx    +=      1
od

;multiply by -1.5
kArr4[] =       kArr3 * -1.5

;print content
printf  "%s", 1, "\nAfter multiplying by -1.5:\n"
kndx    =       0
until kndx == lenarray(kArr4) do
printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr4[kndx]
kndx    +=      1
od

;divide by -3/2
kArr5[] =       kArr4 / -(3/2)

;print content
printf  "%s", 1, "\nAfter dividing by -3/2:\n"
kndx    =       0
until kndx == lenarray(kArr5) do
printf  "kArr[%d] = %f\n", kndx+1, kndx, kArr5[kndx]
kndx    +=      1
od

;turnoff
turnoff
endin

</CsInstruments>
<CsScore>
i 1 0 .1
</CsScore>
</CsoundSynthesizer>
```

### +, -, *, / 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.

Example 4. Example of array operations

```<CsoundSynthesizer>
<CsOptions>
-n -m128
</CsOptions>
<CsInstruments>

instr 1

;create array and fill with numbers 1..10 resp .1..1
kArr1[] fillarray 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
kArr2[] fillarray 1, 2, 3, 5, 8, 13, 21, 34, 55, 89

;print contents
printf  "%s", 1, "\nkArr1:\n"
kndx    =       0
until kndx == lenarray(kArr1) do
printf  "kArr1[%d] = %f\n", kndx+1, kndx, kArr1[kndx]
kndx    +=      1
od
printf  "%s", 1, "\nkArr2:\n"
kndx    =       0
until kndx == lenarray(kArr2) do
printf  "kArr2[%d] = %f\n", kndx+1, kndx, kArr2[kndx]
kndx    +=      1
od

kArr3[] =       kArr1 + kArr2

;print content
printf  "%s", 1, "\nkArr1 + kArr2:\n"
kndx    =       0
until kndx == lenarray(kArr3) do
printf  "kArr3[%d] = %f\n", kndx+1, kndx, kArr3[kndx]
kndx    +=      1
od

;subtract arrays
kArr4[] =       kArr1 - kArr2

;print content
printf  "%s", 1, "\nkArr1 - kArr2:\n"
kndx    =       0
until kndx == lenarray(kArr4) do
printf  "kArr4[%d] = %f\n", kndx+1, kndx, kArr4[kndx]
kndx    +=      1
od

;multiply arrays
kArr5[] =       kArr1 * kArr2

;print content
printf  "%s", 1, "\nkArr1 * kArr2:\n"
kndx    =       0
until kndx == lenarray(kArr5) do
printf  "kArr5[%d] = %f\n", kndx+1, kndx, kArr5[kndx]
kndx += 1
od

;divide arrays
kArr6[] =       kArr1 / kArr2

;print content
printf  "%s", 1, "\nkArr1 / kArr2:\n"
kndx    =       0
until kndx == lenarray(kArr6) do
printf  "kArr5[%d] = %f\n", kndx+1, kndx, kArr6[kndx]
kndx += 1
od

;turnoff
turnoff

endin

</CsInstruments>
<CsScore>
i 1 0 .1
</CsScore>
</CsoundSynthesizer>
```

## Map a Function to an Array

`kArrRes maparray kArrSrc, "fun"`

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:

```kArrSrc[] fillarray 1, 2, 3, 4, 5
kArrRes[] init      5
kArrRes   maparray  kArrSrc, "sqrt"```

See example for opcode maparray.

## Array Operations: min, max, sum, scale, slice

### Minimum and Maximum

`  kMin [,kMinIndx] minarray kArr`

returns the smallest value in an array, and optionally its index.

`  kMax [,kMaxIndx] maxarray kArr`

returns the largest value in an array, and optionally its index. See examples for opcodes minarray and maxarray.

### Sum

`  kSum sumarray kArr`

returns the sum of all values in kArr. See example for opcode sumarray.

### Scale

`  scalearray kArr, kMin, kMax`

scales all values in kArr between kMin and kMax.

```  kArr[] fillarray  1, 3, 9, 5, 6
scalearray kArr, 1, 3```

changes kArr to [1, 1.5, 3, 2, 2.25]. See example for opcode scalearray.

### Slice

`  slicearray kArr, iStart, iEnd`

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 :

```opcode FirstEl, k, k[]
;returns the first element of vector kArr
kArr[] xin
xout   kArr
endop```

Here is an example of an array in an UDO. It uses the file array_udo.csd.

Example 5. Example of an array in an UDO

```<CsoundSynthesizer>
<CsOptions>
-nm128
</CsOptions>
<CsInstruments>

opcode FirstEl, k, k[]
;returns the first element of vector kArr
kArr[] xin
xout kArr
endop

instr 1
kArr[] fillarray 6, 3, 9, 5, 1
kFirst FirstEl kArr
printf "kFirst = %d\n", 1, kFirst
turnoff
endin

</CsInstruments>
<CsScore>
i 1 0 .1
</CsScore>
</CsoundSynthesizer>
```

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