tonal-array

tonal-array

tonal-array is a collection of functions to create and manipulate arrays of notes or intervals.

This is part of tonal music theory library.

You can install via npm: npm i --save tonal-array

API Reference

asArr(source) ⇒ Array

Convert anything to array. Speifically, split string separated by spaces, commas or bars. The arrays are passed without modifications and the rest of the objects are wrapped.

This function always returns an array (null or undefined values are converted to empty arrays)

Thanks to this function, the rest of the functions of this module accepts any object (or more useful: strings) as an array parameter.

map(fn, arr) ⇒ Array

Return a new array with the elements mapped by a function. Basically the same as the JavaScript standard array.map but with two enhacements:

• Arrays can be expressed as strings (see [asArr])
• This function can be partially applied. This is useful to create mapped versions of single element functions. For an excellent introduction of the adventages read this

cMap(fn, list) ⇒ Array

Compact map: map an array with a function and remove nulls. Can be partially applied.

compact(list) ⇒ Array

Return a copy of the array with the null values removed

filter(fn, arr) ⇒ Array

Filter an array with a function. Again, almost the same as JavaScript standard filter function but:

• It accepts strings as arrays
• Can be partially applied

harmonics(notes) ⇒ Array

Given a list of notes, return the distance from the first note to the rest.

harmonizer(ivls) ⇒ function

Given an array of intervals, create a function that harmonizes a note with this intervals. Given a list of notes, return a function that transpose the notes by an interval.

harmonize(ivl, note) ⇒ Array

Harmonizes a note with an array of intervals. It's a layer of sintatic sugar over harmonizer.

sort(comp, arr)

Sort an array or notes or intervals. It uses the JavaScript standard sort function.

shuffle(arr) ⇒ Array

Randomizes the order of the specified array using the Fisher–Yates shuffle.

rotate(times, list) ⇒ Array

Rotates a list a number of times. It's completly agnostic about the contents of the list.

rotateAsc(times, list) ⇒ Array

Rotates an ascending list of pitches n times keeping the ascending property. This functions assumes the list is an ascending list of pitches, and transposes the them to ensure they are ascending after rotation. It can be used, for example, to invert chords.

select(numbers, list) ⇒ Array

Select elements from a list.

listFn(fn) ⇒ function

Decorates a function to so it's first parameter is an array of pitches in array notation. Also, if the return value is a pitch or an array of pitches in array notation, it convert backs to strings.

asArr(source) ⇒ Array

Convert anything to array. Speifically, split string separated by spaces, commas or bars. The arrays are passed without modifications and the rest of the objects are wrapped.

This function always returns an array (null or undefined values are converted to empty arrays)

Thanks to this function, the rest of the functions of this module accepts any object (or more useful: strings) as an array parameter.

Kind: global function
Returns: Array - the object as an array

Param	Type	Description
source	*	the thing to get an array from

Example

import { asArr } from 'tonal-arrays'
asArr('C D E F G') // => ['C', 'D', 'E', 'F', 'G']

map(fn, arr) ⇒ Array

Return a new array with the elements mapped by a function. Basically the same as the JavaScript standard array.map but with two enhacements:

• Arrays can be expressed as strings (see [asArr])
• This function can be partially applied. This is useful to create mapped versions of single element functions. For an excellent introduction of the adventages read this

Kind: global function

Param	Type	Description
fn	function	the function
arr	Array | String	the array to be mapped

Example

var arr = require('tonal-arr')
var toUp = arr.map(function(e) { return e.toUpperCase() })
toUp('a b c') // => ['A', 'B', 'C']

Example

var tonal = require('tonal')
tonal.map(tonal.transpose('M3'), 'C D E') // => ['E', 'F#', 'G#']

cMap(fn, list) ⇒ Array

Compact map: map an array with a function and remove nulls. Can be partially applied.

Kind: global function
See: map

Param	Type
fn	function
list	Array | String

compact(list) ⇒ Array

Return a copy of the array with the null values removed

Kind: global function

Param	Type
list	String | Array

filter(fn, arr) ⇒ Array

Filter an array with a function. Again, almost the same as JavaScript standard filter function but:

• It accepts strings as arrays
• Can be partially applied

Kind: global function

Param	Type
fn	function
arr	String | Array

harmonics(notes) ⇒ Array

Given a list of notes, return the distance from the first note to the rest.

Kind: global function
Returns: Array - the intervals

Param	Type	Description
notes	Array | String	the list of notes

Example

tonal.harmonics('C E g') // => ['1P', '3M', '5P']

harmonizer(ivls) ⇒ function

Given an array of intervals, create a function that harmonizes a note with this intervals. Given a list of notes, return a function that transpose the notes by an interval.

Kind: global function
Returns: function - The harmonizer

Param	Type	Description
ivls	Array | String	the list of pitches

Example

import { harmonizer } from 'tonal-arrays'
var maj7 = harmonizer('P1 M3 P5 M7')
maj7('C') // => ['C', 'E', 'G', 'B']
var C = harmonizer('C D E')
C('M3') // => ['E', 'G#', 'B']

harmonize(ivl, note) ⇒ Array

Harmonizes a note with an array of intervals. It's a layer of sintatic sugar over harmonizer.

Kind: global function
Returns: Array - the resulting notes

Param	Type	Description
ivl	String | Array	the array of intervals
note	String | Pitch	the note to be harmonized

Example

var tonal = require('tonal')
tonal.harmonise('P1 M3 P5 M7', 'C') // => ['C', 'E', 'G', 'B']

sort(comp, arr)

Sort an array or notes or intervals. It uses the JavaScript standard sort function.

Kind: global function

Param	Type	Description
comp	Boolean | function	the comparator. true means use an ascending comparator, false a descending comparator, or you can pass a custom comparator (that receives pitches in array notation)
arr	Array | String	the array of notes or intervals

Example

import { sort } from 'tonal-arrays'
sort(true, 'D E C') // => ['C', 'D', 'E']

Example

var tonal = require('tonal')
tonal.sort(false, 'D E C') // => ['E', 'D', 'C']

shuffle(arr) ⇒ Array

Randomizes the order of the specified array using the Fisher–Yates shuffle.

Kind: global function
Returns: Array - the shuffled array

Param	Type	Description
arr	Array | String	the array

Example

import { shuffle } from 'tonal-arrays'

Example

var tonal = require('tonal')
tonal.shuffle('C D E F')

rotate(times, list) ⇒ Array

Rotates a list a number of times. It's completly agnostic about the contents of the list.

Kind: global function
Returns: Array - the rotated array

Param	Type	Description
times	Integer	the number of rotations
list	Array | String	the list to be rotated

rotateAsc(times, list) ⇒ Array

Rotates an ascending list of pitches n times keeping the ascending property. This functions assumes the list is an ascending list of pitches, and transposes the them to ensure they are ascending after rotation. It can be used, for example, to invert chords.

Kind: global function
Returns: Array - the rotated array

Param	Type	Description
times	Integer	the number of rotations
list	Array | String	the list to be rotated

select(numbers, list) ⇒ Array

Select elements from a list.

Kind: global function
Returns: Array - the selected elements (with nulls if not valid index)

Param	Type	Description
numbers	String | Array	a 1-based index of the elements
list	String | Array	the list of pitches

Example

import { select } from 'tonal-array'
select('1 3 5', 'C D E F G A B') // => ['C', 'E', 'G']
select('-1 0 1 2 3', 'C D') // => [ null, null, 'C', 'D', null ]

listFn(fn) ⇒ function

Decorates a function to so it's first parameter is an array of pitches in array notation. Also, if the return value is a pitch or an array of pitches in array notation, it convert backs to strings.

Kind: global function
Returns: function - the decorated function

Param	Type	Description
fn	function	the function to decorate

Example

import { listFn } from 'tonal-arrays'
var octUp = listFn((p) => { p[2] = p[2] + 1; return p[2] })
octUp('C2 D2 E2') // => ['C3', 'D3', 'E3']