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

Map an array with 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

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

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.

harmonizer(ivls) ⇒ function

Given an array of intervals, create a function that harmonizes a note with this intervals.

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.

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

Map an array with 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#']

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

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

harmonizer(ivls) ⇒ function

Given an array of intervals, create a function that harmonizes a note with this intervals.

Kind: global function
Returns: function - The harmonizer

Param	Type	Description
ivls	Array | String	the array of intervals

Example

import { harmonizer } from 'tonal-arrays'
var maj7 = harmonizer('P1 M3 P5 M7')
maj7('C') // => ['C', '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')