harmonex v0.6.0 Harmonex.Interval View Source
Provides functions for working with intervals between pitches on the Western dodecaphonic scale.
Link to this section Summary
Types
A Harmonex.Interval
struct
The qualified variation of an interval’s size
The distance in half steps across an interval
The number of staff lines and spaces spanned by an interval
An expression describing an interval
Functions
Enharmonically compares the specified interval1
and interval2
Computes the interval between the specified pitch1
and pitch2
Constructs a new interval with the specified definition
Constructs a new interval with the specified quality
and size
Computes the distance in half steps across the specified interval
Determines if the specified interval
cannot be simplified (see simplify/1
)
Computes the simple interval that corresponds to the specified interval
Link to this section Types
A Harmonex.Interval
struct.
quality :: :perfect | :minor | :major | :diminished | :augmented | :doubly_diminished | :doubly_augmented
The qualified variation of an interval’s size.
The distance in half steps across an interval.
The number of staff lines and spaces spanned by an interval.
An expression describing an interval.
Link to this section Functions
compare(t, t) :: Harmonex.comparison | Harmonex.error
Enharmonically compares the specified interval1
and interval2
.
Enharmonic comparison is made on the basis of semitones/1
.
It returns:
:eq
if they are identical or enharmonically equivalent:lt
ifinterval1
is enharmonically narrower:gt
ifinterval1
is enharmonically wider
Examples
iex> Harmonex.Interval.compare %{quality: :perfect, size: 4}, %{quality: :perfect, size: 4}
:eq
iex> Harmonex.Interval.compare %{quality: :major, size: 3}, %{quality: :diminished, size: 4}
:eq
iex> Harmonex.Interval.compare %{quality: :doubly_diminished, size: 6}, %{quality: :doubly_augmented, size: 4}
:lt
iex> Harmonex.Interval.compare %{quality: :minor, size: 10}, %{quality: :major, size: 9}
:gt
from_pitches(Harmonex.Pitch.t, Harmonex.Pitch.t) :: interval | Harmonex.error
Computes the interval between the specified pitch1
and pitch2
.
Examples
iex> Harmonex.Interval.from_pitches %{natural_name: :a, accidental: :sharp, octave: 4}, %{natural_name: :c, octave: 6}
%Harmonex.Interval{quality: :diminished, size: 10}
iex> Harmonex.Interval.from_pitches :a_sharp, :c
%Harmonex.Interval{quality: :diminished, size: 3}
iex> Harmonex.Interval.from_pitches :d_double_sharp, :a_double_sharp
%Harmonex.Interval{quality: :perfect, size: 4}
iex> Harmonex.Interval.from_pitches :c_flat, :c_natural
%Harmonex.Interval{quality: :augmented, size: 1}
iex> Harmonex.Interval.from_pitches :a_flat, :e_sharp
%Harmonex.Interval{quality: :doubly_diminished, size: 4}
iex> Harmonex.Interval.from_pitches :a_flat, :e_double_sharp
{:error, "Invalid interval"}
Constructs a new interval with the specified definition
.
Examples
iex> Harmonex.Interval.new %{quality: :perfect, size: 1}
%Harmonex.Interval{quality: :perfect, size: 1}
iex> Harmonex.Interval.new %{quality: :augmented, size: 17}
%Harmonex.Interval{quality: :augmented, size: 17}
iex> Harmonex.Interval.new %{quality: :minor, size: 1}
{:error, "Quality of unison must be in [:perfect, :augmented, :doubly_augmented]"}
iex> Harmonex.Interval.new %{quality: :major, size: 8}
{:error, "Quality of octave must be in [:perfect, :diminished, :augmented, :doubly_diminished, :doubly_augmented]"}
iex> Harmonex.Interval.new %{quality: :perfect, size: 0}
{:error, "Size must be a positive integer"}
iex> Harmonex.Interval.new %{quality: :minor, size: -3}
{:error, "Size must be a positive integer"}
iex> Harmonex.Interval.new %{quality: :minor}
{:error, "Size must be a positive integer"}
new(quality, size) :: interval | Harmonex.error
Constructs a new interval with the specified quality
and size
.
Examples
iex> Harmonex.Interval.new :perfect, 1
%Harmonex.Interval{quality: :perfect, size: 1}
iex> Harmonex.Interval.new :augmented, 17
%Harmonex.Interval{quality: :augmented, size: 17}
iex> Harmonex.Interval.new :minor, 1
{:error, "Quality of unison must be in [:perfect, :augmented, :doubly_augmented]"}
iex> Harmonex.Interval.new :major, 8
{:error, "Quality of octave must be in [:perfect, :diminished, :augmented, :doubly_diminished, :doubly_augmented]"}
iex> Harmonex.Interval.new :imperfect, 1
{:error, "Invalid quality -- must be in [:perfect, :minor, :major, :diminished, :augmented, :doubly_diminished, :doubly_augmented]"}
iex> Harmonex.Interval.new :perfect, 0
{:error, "Size must be a positive integer"}
iex> Harmonex.Interval.new :minor, -3
{:error, "Size must be a positive integer"}
iex> Harmonex.Interval.new :minor, nil
{:error, "Size must be a positive integer"}
Computes the distance in half steps across the specified interval
.
Examples
iex> Harmonex.Interval.semitones %{quality: :major, size: 3}
4
iex> Harmonex.Interval.semitones %{quality: :doubly_diminished, size: 9}
11
iex> Harmonex.Interval.semitones %{quality: :doubly_diminished, size: 16}
23
iex> Harmonex.Interval.semitones %{quality: :augmented, size: 300}
514
Determines if the specified interval
cannot be simplified (see simplify/1
).
Simple intervals are no more than 11 semitones across (see semitones/1
).
Examples
iex> Harmonex.Interval.simple? %{quality: :major, size: 10}
false
iex> Harmonex.Interval.simple? %{quality: :major, size: 3}
true
iex> Harmonex.Interval.simple? %{quality: :augmented, size: 8}
false
iex> Harmonex.Interval.simple? %{quality: :diminished, size: 8}
true
Computes the simple interval that corresponds to the specified interval
.
Simple intervals are no more than 11 semitones across (see semitones/1
).
Examples
iex> Harmonex.Interval.simplify %{quality: :major, size: 10}
%Harmonex.Interval{quality: :major, size: 3}
iex> Harmonex.Interval.simplify %{quality: :major, size: 3}
%Harmonex.Interval{quality: :major, size: 3}
iex> Harmonex.Interval.simplify %{quality: :augmented, size: 8}
%Harmonex.Interval{quality: :augmented, size: 1}
iex> Harmonex.Interval.simplify %{quality: :diminished, size: 8}
%Harmonex.Interval{quality: :diminished, size: 8}