The Top 10 Most Useful Functions

[fileicon] Download top10.sal

The Top 10 most useful functions for algorithmic composition, by category. Familarity with these functions will greatly improve your ability to design interesting musical programs! For more information about these functions click on their names in the main entries.

Math: plus, times, minus, divide, modulo, min, max, expt, int, abs
Lists: list, concat, reverse, length, first, rest, butlast, last, nth,
Predicates: number?, even?, odd?, list?, null?, string?, equal?, member
Randomness: random, between, pick, shuffle, odds, vary
Mapping: key, note, scale, scale-order, rescale, discrete, interp, segs, fit

Math

plus(...)

Adds numbers or a list of numbers together.

plus()
⇒ 0
plus(2, 3, 4)
⇒ 9
plus({2 3 4})
⇒ 9
plus({2 3 4}, 5)
⇒ {7 8 9}

minus(...)

Subtracts numbers or a list of numbers.

minus(1)
⇒ -1
minus(2, 3, 4)
⇒ -5
minus({2 3 4})
⇒ -1
minus({1 2 3}, 2)
⇒ {-1 0 1}

times(...)

Multiplies numbers or a list of numbers together.

times()
⇒ 1
times(2, 3, 4)
⇒ 24
times({2 3 4})
⇒ 24
times({2 3 4}, 5)
⇒ {10 15 20}

divide(...)

Divides numbers or a list of numbers.

divide(2)
⇒ .5
divide(2, 3, 4)
⇒ 1/6
divide({2 3 4})
⇒ 1/6
divide({2 3 4}, 2)
⇒ {1 3/2 2}

modulo(n, m)

Returns the modulus (remainder after division) of n and m.

modulo(12, 12)
⇒ 0
modulo(14, 12)
⇒ 2
modulo(-1, 12)
⇒ 11

min(...)

Returns the minimum value.

min(10, 20, -1)
⇒ -1

max(...)

Returns the maximum value.

max(10, 20, -1)
⇒ 20

expt(b, p)

Raises base b to power p.

expt(2, 0)
⇒ 1
expt(10, 2)
⇒ 100
expt(2, -1)
⇒ 1/2
expt(2, 1/12)
⇒ 1.0594631

int(n)

Rounds a number or list of numbers to the nearest integer.

int(60.1)
⇒ 60
int(60.6)
⇒ 61
int({50.1 60.6 99.2})
⇒ {50 61 99}

abs(n)

Returns the absolute value of n.

abs(1)
⇒ 1
abs(-.2)
⇒ .2

Lists

list(...)

Creates a list out of its inputs.

list(1)
⇒ {1}
list(1,2,3)
⇒ {1 2 3}
list( 1 , expt(2, -3), 4, {5 6 7}, 8 * 9, 10)
⇒ {1 .25 4 {5 6 7} 72 10}

concat(...)

Concatentes (joins together) input arguments to form a single list. Each input can be a value or list

concat({a b c}, {d e f})
⇒ {a b c d e f}
concat(1, {a b c}, 2)
⇒ {1 a b c 2}

reverse(list)

Reverses the order of elements in list.

reverse({0 1 2 3 4 5})
⇒ {5 4 3 2 1 0}
reverse({{c e g} {d f a} {e g b}})
⇒ {{e g b} {d f a} {c e g}}

length(list)

Returns the number of elements in list.

length({})
⇒ 0
length({c e g})
⇒ 3
length({{c e g} {d f a}})
⇒ 2

first(list)

Returns the first element in list. (Also: second ... tenth.)

first({a b c d e})
⇒ a

rest(list)

Returns all but the first element in list.

rest({a b c d e})
⇒ {b c d e}

butlast(list)

Returns all but the last element in list.

butlast({a b c d e})
⇒ {a b c d}

last(list)

Returns the last element in list.

last({a b c d e})
⇒ e

nth(list, index)

Returns the element at index in list.

nth({a b c d}, 0)
⇒ a

Predicates

number?(x)

Returns true if x is a number otherwise false.

number?(2)
⇒ #t
number?("2")
⇒ #f

even?(x)

Returns true if x is an even integer otherwise false.

even?(2)
⇒ #t
even?(1)
⇒ #f

odd?(x)

Returns true if x is an odd integer otherwise false.

odd?(2)
⇒ #f
odd?(1)
⇒ #t

list?(x)

Returns true if x is a list otherwise false.

list?({})
⇒ #t
list?({1 2 3})
⇒ #t
list?(1)
⇒ #f

null?(x)

Returns true if x is an empty list otherwise false.

null?({})
⇒ #t
null?({1 2 3})
⇒ #f

string?(x)

Returns true if x is a string otherwise false.

string?("")
⇒ #t
string?("Hi ho!")
⇒ #t
string?({hi ho!})
⇒ #f

equal?(x, y)

Returns true if values are all generally equal otherwise false.

equal?(2, 3 - 1)
⇒ t
equal?({1 2 3}, {1 2 3})
⇒ #t
equal?("Hello", "Goodbye")
⇒ #f

member(x, list)

Returns the tail of list whose first element is x otherwise (x is not in list) it returns false.

member(2, {0 1 2 3})
⇒ {2 3}
member(4, {0 1 2 3})
⇒ #f

Random Selection

random(ub)

Returns a random integer r such that 0 <= r < ub.

random(5)
⇒ 4
random(1.0)
⇒ 0.239

between(lb, ub)

Returns lb + random(ub - lb). If avoid is provided that value will not be chosen.

between(60, 90)
⇒ 87
between(60.1, 90.1)
⇒ 72.33241

pick(...)

Returns an input value selected at random.

pick(10, -20, 30, -99)
⇒ -20
pick({a b c d e})
⇒ d

shuffle(list)

Returns a copy of list with its elements randomly reordered.

shuffle({a b c d e})
⇒ {b c d a e}

odds(prob [, true] [, false])

Returns true or false input based on a probability factor prob, where 0.0 <= prob <=1.0. Boolean true or false are return if true or false inputs are not specified.

odds(.25 )
⇒ #f
odds(.5, "Heads!",  "Tails!")
⇒ Heads!

vary(n, v)

Returns a random value that differs from n by +- 1/2v amount.

vary(60, .1)
⇒ 61.923
vary(60, .1)
⇒ 58.055

Mapping

key(n)

Converts note or list of notes into key numbers.

key("c4")
⇒ 60
key({c4 d e })
⇒ {60 62 64}

note(k)

Converts key or list of keys to notes

note(60)
⇒ c4
note(60.5)
⇒ c>4
note({60 61 62})
⇒ {c4 cs4 d4}

scale(len, key steps...)

Return a list of len keys beginning with key and incremented by each interval in steps...

scale(16, 60, 1, 2)
⇒ {60 61 63 64 66 67 69 70}

scale-order(list, mode)

Reorders a list of notes or keynums according to mode: 1 is ascending order, -1 is decending order and 0 is random order.

scale-order( {60 63 67 62 65 69}, -1)
⇒ {69 67 65 63 62 60}

rescale(x, lb1, ub1, lb2, ub2)

Converts x between lb1 and lb2 to the corresponding value between lb2 and ub2.

rescale(.5, 0, 1, 0, 1000)
⇒ 500
rescale(.5, 0, 1, 0, -1000)
⇒ -500

discrete(x, lb1, ub1, ...)

Like rescale but maps x onto descrete values.

discrete(.5, 0, 1, {a b c d e})
⇒ c

interp(x, ...)

Returns an interplated y value for x in coordinates.

interp(.75, 0, 0, .5, 1, 1, 0)
⇒ .25
interp(.75, {0 0 1 200})
⇒ 100

segs(len, sum, mode)

Returns a list of len number adding up to sum and related by mode: 1 is exponential, 2 is geometric, 3 is random.

segs(3, 10, 1)
⇒ {2.59921050071716 3.27480053901672 4.12598896026611}

fit(num, min, max, mode)

Returns numner or list bounded by min and max according to mode: 1 is wrap, 2 is reflect 3 is min or max.

fit(13, 0, 10, 2)
⇒ 7