Add types for more clearity (#25)

noeddl · web-flow · commit c351251c3e59 · 2019-10-12T16:35:38.000+02:00
* Add types Semitones and StaffSteps * Replace type Frets with FretID * Use newtype pattern for FretID * Revert "Use newtype pattern for FretID" This reverts commit 72596f0. * Define chart width in semitones * Move type definitions * Update documentation
diff --git a/src/chord/chord.rs b/src/chord/chord.rs
@@ -1,8 +1,8 @@
 use crate::chord::ChordShapeSet;
+use crate::chord::FretID;
 use crate::diagram::ChordDiagram;
 use crate::note::Interval;
 use crate::note::Note;
-use crate::Frets;
 use crate::STRING_COUNT;
 use regex::Regex;
 use std::fmt;
@@ -63,7 +63,7 @@ impl Chord {
         self.notes.contains(&note)
     }
 
-    pub fn get_diagram(self, min_fret: Frets) -> ChordDiagram {
+    pub fn get_diagram(self, min_fret: FretID) -> ChordDiagram {
         let chord_shapes = ChordShapeSet::new(self.quality);
 
         let (frets, intervals) = chord_shapes.get_config(self.root, min_fret);
diff --git a/src/chord/chord_shape.rs b/src/chord/chord_shape.rs
@@ -1,12 +1,14 @@
 use crate::chord::ChordQuality;
+use crate::chord::FretID;
+use crate::chord::FretPattern;
 use crate::note::Interval;
 use crate::note::Note;
-use crate::FretPattern;
-use crate::Frets;
-use crate::IntervalPattern;
+use crate::note::Semitones;
 use crate::STRING_COUNT;
 use std::str::FromStr;
 
+type IntervalPattern = [Interval; STRING_COUNT];
+
 /// A chord shape is a configuration of frets to be pressed to play a
 /// chord with a certain chord quality. The shape can be moved along
 /// the fretboard to derive several chords.
@@ -38,7 +40,7 @@ impl ChordShape {
 
     /// Apply the chord shape while moving it `n` frets forward on the fretboard.
     /// Return the resulting fret pattern.
-    fn apply(self, n: Frets) -> (FretPattern, IntervalPattern) {
+    fn apply(self, n: Semitones) -> (FretPattern, IntervalPattern) {
         let mut frets = self.frets;
 
         for f in &mut frets[..] {
@@ -78,7 +80,7 @@ impl ChordShapeSet {
     }
 
     /// Return a fret pattern to play `chord` starting from fret number `min_fret`.
-    pub fn get_config(self, root: Note, min_fret: Frets) -> (FretPattern, IntervalPattern) {
+    pub fn get_config(self, root: Note, min_fret: FretID) -> (FretPattern, IntervalPattern) {
         let (chord_shape, diff) = self
             .chord_shapes
             .into_iter()
diff --git a/src/chord/mod.rs b/src/chord/mod.rs
@@ -6,3 +6,13 @@ pub use self::chord::Chord;
 pub use self::chord::ChordQuality;
 pub use self::chord_shape::ChordShape;
 pub use self::chord_shape::ChordShapeSet;
+
+use crate::STRING_COUNT;
+
+/// The ID of a fret on the fretboard. 0 corresponds to the nut,
+/// 1 corresponds to the first fret, 2 to the second etc.
+pub type FretID = u8;
+
+/// A pattern of frets to push down for playing a chord.
+/// Each index of the array corresponds to a ukulele string.
+pub type FretPattern = [FretID; STRING_COUNT];
diff --git a/src/diagram/chord_diagram.rs b/src/diagram/chord_diagram.rs
@@ -1,14 +1,15 @@
 use crate::chord::Chord;
+use crate::chord::FretID;
+use crate::chord::FretPattern;
 use crate::diagram::StringDiagram;
 use crate::diagram::CHART_WIDTH;
 use crate::note::Note;
-use crate::FretPattern;
-use crate::Frets;
-use crate::NotePattern;
 use crate::STRING_COUNT;
 use std::fmt;
 use std::str::FromStr;
 
+type NotePattern = [Note; STRING_COUNT];
+
 pub struct ChordDiagram {
     chord: Chord,
     roots: NotePattern,
@@ -38,7 +39,7 @@ impl ChordDiagram {
     /// If the rightmost fret fits on the diagram, show the fretboard
     /// beginning at the first fret, otherwise use the leftmost fret
     /// needed for the chords to be played.
-    fn get_base_fret(&self) -> Frets {
+    fn get_base_fret(&self) -> FretID {
         let max_fret = *self.frets.iter().max().unwrap();
 
         match max_fret {
@@ -169,7 +170,7 @@ mod tests {
             ")
         ),
     )]
-    fn test_to_diagram(chord_name: &str, min_fret: Frets, diagram: &str) {
+    fn test_to_diagram(chord_name: &str, min_fret: FretID, diagram: &str) {
         let chord = Chord::from_str(chord_name).unwrap();
         let chord_diagram = chord.get_diagram(min_fret);
         assert_eq!(chord_diagram.to_string(), diagram);
diff --git a/src/diagram/mod.rs b/src/diagram/mod.rs
@@ -4,7 +4,7 @@ mod string_diagram;
 pub use self::chord_diagram::ChordDiagram;
 pub use self::string_diagram::StringDiagram;
 
-use crate::Frets;
+use crate::note::Semitones;
 
 /// Number of frets shown on the fretboard chart.
-pub const CHART_WIDTH: Frets = 4;
+pub const CHART_WIDTH: Semitones = 4;
diff --git a/src/diagram/string_diagram.rs b/src/diagram/string_diagram.rs
@@ -1,18 +1,18 @@
+use crate::chord::FretID;
 use crate::diagram::CHART_WIDTH;
 use crate::note::Note;
-use crate::Frets;
 use std::fmt;
 
 /// A line within a chord diagram which represents a string of a ukulele.
 pub struct StringDiagram {
     root: Note,
-    base_fret: Frets,
-    fret: Frets,
+    base_fret: FretID,
+    fret: FretID,
     note: Note,
 }
 
 impl StringDiagram {
-    pub fn new(root: Note, base_fret: Frets, fret: Frets, note: Note) -> Self {
+    pub fn new(root: Note, base_fret: FretID, fret: FretID, note: Note) -> Self {
         Self {
             root,
             base_fret,
@@ -77,8 +77,8 @@ mod tests {
     )]
     fn test_format_line(
         root_name: &str,
-        base_fret: Frets,
-        fret: Frets,
+        base_fret: FretID,
+        fret: FretID,
         note_name: &str,
         diagram: &str,
     ) {
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,18 +1,6 @@
 pub mod chord;
 mod diagram;
-mod note;
-
-/// Type for the number of frets (corresponds to the number of semitones)
-/// to move from one note or pitch class to another.
-pub type Frets = u8;
+pub mod note;
 
 /// Number of strings on our string instrument.
 pub const STRING_COUNT: usize = 4;
-
-pub type FretPattern = [Frets; STRING_COUNT];
-
-use crate::note::Interval;
-pub type IntervalPattern = [Interval; STRING_COUNT];
-
-use crate::note::Note;
-pub type NotePattern = [Note; STRING_COUNT];
diff --git a/src/main.rs b/src/main.rs
@@ -1,12 +1,12 @@
 use structopt::StructOpt;
 use ukebox::chord::Chord;
-use ukebox::Frets;
+use ukebox::chord::FretID;
 
 #[derive(StructOpt)]
 struct Cmd {
     #[structopt(short = "f", long, default_value = "0")]
     /// Minimal fret (= minimal position) from which to play <chord>
-    min_fret: Frets,
+    min_fret: FretID,
     /// Name of the chord to be shown
     chord: Chord,
 }
diff --git a/src/note/interval.rs b/src/note/interval.rs
@@ -1,4 +1,5 @@
-use crate::Frets;
+use crate::note::Semitones;
+use crate::note::StaffSteps;
 use std::fmt;
 use std::str::FromStr;
 
@@ -26,7 +27,7 @@ pub enum Interval {
 
 impl Interval {
     /// Return the number of semitones that the interval encompasses.
-    pub fn to_semitones(self) -> Frets {
+    pub fn to_semitones(self) -> Semitones {
         use Interval::*;
 
         match self {
@@ -39,7 +40,7 @@ impl Interval {
 
     /// Return the interval's number. It corresponds to the number of
     /// staff positions that the intervall encompasses.
-    pub fn to_number(self) -> u8 {
+    pub fn to_number(self) -> StaffSteps {
         use Interval::*;
 
         match self {
diff --git a/src/note/mod.rs b/src/note/mod.rs
@@ -8,3 +8,11 @@ pub use self::interval::Interval;
 pub use self::note::Note;
 pub use self::pitch_class::PitchClass;
 pub use self::staff_position::StaffPosition;
+
+/// The number of semitones (corresponds to the number of frets)
+/// to move from one note or pitch class to another.
+pub type Semitones = u8;
+
+/// The number of steps in a staff to move from one staff position
+/// to another.
+type StaffSteps = u8;
diff --git a/src/note/pitch_class.rs b/src/note/pitch_class.rs
@@ -1,10 +1,10 @@
 #![allow(clippy::suspicious_arithmetic_impl)]
-use crate::Frets;
+use crate::note::Semitones;
 use std::ops::Add;
 use std::ops::Sub;
 
 /// Number of pitch classes.
-const PITCH_CLASS_COUNT: Frets = 12;
+const PITCH_CLASS_COUNT: Semitones = 12;
 
 /// A pitch class is "a set of all pitches that are a whole number of octaves
 /// apart, e.g., the pitch class C consists of the Cs in all octaves."
@@ -31,14 +31,14 @@ pub enum PitchClass {
     B,
 }
 
-impl From<Frets> for PitchClass {
+impl From<Semitones> for PitchClass {
     /// Convert an integer into a pitch class.
     ///
     /// To model the fact that e.g. all instances of the note `C` in different
     /// octaves belong to the same pitch class, each integer is placed in the
     /// range of potential pitch classes (between 0 and 11).
     /// For example, 12, 24, 36, etc. all correspond to pitch class 0.
-    fn from(n: Frets) -> Self {
+    fn from(n: Semitones) -> Self {
         use PitchClass::*;
 
         // Make sure we get a value between 0 and 11.
@@ -66,19 +66,19 @@ impl From<Frets> for PitchClass {
     }
 }
 
-impl Add<Frets> for PitchClass {
+impl Add<Semitones> for PitchClass {
     type Output = Self;
 
     /// Get the pitch class that is `n` semitones higher than the current
     /// pitch class.
-    fn add(self, n: Frets) -> Self {
-        let v = self as Frets + n;
+    fn add(self, n: Semitones) -> Self {
+        let v = self as Semitones + n;
         Self::from(v)
     }
 }
 
 impl Sub for PitchClass {
-    type Output = Frets;
+    type Output = Semitones;
 
     /// Get the difference between two pitch classes in number of frets
     /// or semitones.
@@ -90,24 +90,24 @@ impl Sub for PitchClass {
     /// * D - C: both pitch classes are assumed to be in the same octave, D being
     ///          higher than C. The difference is 2.
     /// * D - A: D is higher than A, the difference is 5.
-    fn sub(self, other: Self) -> Frets {
+    fn sub(self, other: Self) -> Semitones {
         let d = self as i8 - other as i8;
 
         let diff = match d {
             d if d >= 0 => d,
             _ => d + PITCH_CLASS_COUNT as i8,
         };
 
-        diff as Frets
+        diff as Semitones
     }
 }
 
-impl Sub<Frets> for PitchClass {
+impl Sub<Semitones> for PitchClass {
     type Output = Self;
 
     /// Get the pitch class that is `n` semitones lower than the current
     /// pitch class.
-    fn sub(self, n: Frets) -> Self {
+    fn sub(self, n: Semitones) -> Self {
         Self::from(self - Self::from(n))
     }
 }
@@ -139,7 +139,7 @@ mod tests {
         case(127, G),
         case(255, DSharp)
     )]
-    fn test_from_int(n: Frets, pitch_class: PitchClass) {
+    fn test_from_int(n: Semitones, pitch_class: PitchClass) {
         assert_eq!(PitchClass::from(n), pitch_class);
     }
 
@@ -154,7 +154,7 @@ mod tests {
         case(C, 13, CSharp),
         case(C, 24, C)
     )]
-    fn test_add_int(pitch_class: PitchClass, n: Frets, result: PitchClass) {
+    fn test_add_int(pitch_class: PitchClass, n: Semitones, result: PitchClass) {
         assert_eq!(pitch_class + n, result);
     }
 
@@ -167,7 +167,7 @@ mod tests {
         case(D, A, 5),
         case(C, CSharp, 11)
     )]
-    fn test_sub_self(pc1: PitchClass, pc2: PitchClass, n: Frets) {
+    fn test_sub_self(pc1: PitchClass, pc2: PitchClass, n: Semitones) {
         assert_eq!(pc1 - pc2, n);
     }
 
@@ -182,7 +182,7 @@ mod tests {
         case(C, 12, C),
         case(C, 13, B)
     )]
-    fn test_sub_int(pc1: PitchClass, n: Frets, pc2: PitchClass) {
+    fn test_sub_int(pc1: PitchClass, n: Semitones, pc2: PitchClass) {
         assert_eq!(pc1 - n, pc2);
     }
 }
diff --git a/src/note/staff_position.rs b/src/note/staff_position.rs
@@ -1,6 +1,7 @@
+use crate::note::StaffSteps;
 use std::ops::Add;
 
-const STAFF_POSITION_COUNT: u8 = 7;
+const STAFF_POSITION_COUNT: StaffSteps = 7;
 
 /// The vertical position of the notehead on the staff (on a line or in a space).
 /// We use the staff position of an enharmonic note to decide whether it is sharp
@@ -21,8 +22,8 @@ pub enum StaffPosition {
     BPos,
 }
 
-impl From<u8> for StaffPosition {
-    fn from(n: u8) -> Self {
+impl From<StaffSteps> for StaffPosition {
+    fn from(n: StaffSteps) -> Self {
         use StaffPosition::*;
 
         // Make sure we get a value between 0 and 6.
@@ -45,12 +46,12 @@ impl From<u8> for StaffPosition {
     }
 }
 
-impl Add<u8> for StaffPosition {
+impl Add<StaffSteps> for StaffPosition {
     type Output = Self;
 
     /// Get the staff position that is `n` positions higher than the current one.
-    fn add(self, n: u8) -> Self {
-        Self::from(self as u8 + n)
+    fn add(self, n: StaffSteps) -> Self {
+        Self::from(self as StaffSteps + n)
     }
 }
 
@@ -71,7 +72,7 @@ mod tests {
         case(5, APos),
         case(6, BPos)
     )]
-    fn test_from_int(n: u8, staff_position: StaffPosition) {
+    fn test_from_int(n: StaffSteps, staff_position: StaffPosition) {
         assert_eq!(StaffPosition::from(n), staff_position);
     }
 
@@ -86,7 +87,11 @@ mod tests {
         case(CPos, 8, DPos),
         case(CPos, 14, CPos)
     )]
-    fn test_pitch_class_add_int(staff_position: StaffPosition, n: u8, result: StaffPosition) {
+    fn test_pitch_class_add_int(
+        staff_position: StaffPosition,
+        n: StaffSteps,
+        result: StaffPosition,
+    ) {
         assert_eq!(staff_position + n, result);
     }
 }
diff --git a/tests/ukebox.rs b/tests/ukebox.rs
