Skip to content

string2array

Reads a list of numbers from a string into an array.

Use string2array to turn a text list of pitches, durations or other settings into numbers an instrument can use. It accepts decimal numbers separated by whitespace or commas.

Syntax

iarray[] = string2array(Svalues)
karray[] = string2array(Svalues)

iarray[] string2array Svalues
karray[] string2array Svalues

Initialization

Svalues contains the numbers to read. Spaces, tabs, newlines and commas separate values. Repeated separators are allowed. Use a decimal point for fractions, since a comma separates two numbers.

The output holds numeric values in the order they appear in the string. Both i-rate and k-rate arrays are supported. The opcode reads the string at initialization only, including when reinitialization runs. Changing the string during performance does not update a k-rate output array.

For a new array, the opcode creates a one-dimensional array with one element per number. An existing one-dimensional output takes that size too. You do not need to allocate it first.

A preallocated multidimensional output keeps its shape. The opcode fills it in row-major order, with the last index changing fastest. Extra values beyond its element count are ignored, and elements beyond the supplied values keep their previous contents.

String format

Numbers can have a sign, a fractional part or an exponent written with e or E.

Input string Output values
"60 64 67" [60, 64, 67]
"0.5, -2, +3" [0.5, -2, 3]
"1e2 2.5E-1" [100, 0.25]

Supply plain numeric data. Expressions, note names, comments and quoted text fields are not supported. The parser does not reliably report malformed numbers, so check text from outside the instrument before passing it in. Keep each numeric token to at most 127 characters.

The output contains numbers, not strings or character codes. Use strchar to read a character code or strtod to convert a single number.

Examples

The example passes pitch steps in a score string. The instrument reads them into an i-rate array, adds each step to MIDI note 60 and schedules the notes 0.4 seconds apart.

The first phrase uses 0, 4, 7, 12 for a major arpeggio. The second uses 0 3 7 12 for a minor arpeggio. This lets the score choose the phrase without changing the instrument.

It uses string2array.csd.

Play pitch steps supplied as text
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<CsoundSynthesizer>
<CsOptions>
-d -o dac
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

instr Phrase
  // p4 supplies pitch steps as text, separated by spaces or commas.
  SSteps = strget(p4)
  iSteps[] = string2array(SSteps)

  // Read the array once and schedule a note for each step.
  iIndex = 0
  while iIndex < lenarray(iSteps) do
    iStart = iIndex * 0.4
    iMidiNote = 60 + iSteps[iIndex]
    schedule("Tone", iStart, 0.35, iMidiNote)
    iIndex += 1
  od
endin

instr Tone
  iFrequency = cpsmidinn(p4)
  aEnvelope = linen(0.2, 0.01, p3, 0.05)
  aTone = oscili(aEnvelope, iFrequency)
  out(aTone)
endin
</CsInstruments>
<CsScore>
// Major, then minor. Both separator styles work.
i "Phrase" 0 0.01 "0, 4, 7, 12"
i "Phrase" 2 0.01 "0 3 7 12"
// Allow the last scheduled notes to finish.
f 0 4
e
</CsScore>
</CsoundSynthesizer>

See also

fillarray, strget, strtod, strchar, Array opcodes, String conversion

Credits

Author John ffitch, 2019.

New in Csound 6.13.