Replace Song::new by Song::from_path

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## bliss 0.5.0
 * Remove all traces of the "analyse" word vs "analyze" to make the codebase
   more coherent.
+* Rename `Song::new` to `Song::from_path`.
 
 ## bliss 0.4.6
 * Bump ffmpeg crate version to allow for cross-compilation.

README.md

@@ -48,8 +48,8 @@ Ready to use code examples:
 use bliss_audio::{BlissError, Song};
 
 fn main() -> Result<(), BlissError> {
-    let song1 = Song::new("/path/to/song1")?;
-    let song2 = Song::new("/path/to/song2")?;
+    let song1 = Song::from_path("/path/to/song1")?;
+    let song2 = Song::from_path("/path/to/song2")?;
         
     println!("Distance between song1 and song2 is {}", song1.distance(&song2));
     Ok(())
@@ -65,7 +65,7 @@ fn main() -> Result<(), BlissError> {
     let paths = vec!["/path/to/song1", "/path/to/song2", "/path/to/song3"];
     let mut songs: Vec<Song> = paths
         .iter()
-        .map(|path| Song::new(path))
+        .map(|path| Song::from_path(path))
         .collect::<Result<Vec<Song>, BlissError>>()?;
 
     // Assuming there is a first song

examples/analyze.rs

@@ -9,7 +9,7 @@ use std::env;
 fn main() {
     let args: Vec<String> = env::args().skip(1).collect();
     for path in &args {
-        match Song::new(&path) {
+        match Song::from_path(&path) {
             Ok(song) => println!("{}: {:?}", path, song.analysis),
             Err(e) => println!("{}: {}", path, e),
         }

examples/distance.rs

@@ -13,8 +13,8 @@ fn main() -> Result<(), String> {
     let first_path = paths.next().ok_or("Help: ./distance <song1> <song2>")?;
     let second_path = paths.next().ok_or("Help: ./distance <song1> <song2>")?;
 
-    let song1 = Song::new(&first_path).map_err(|x| x.to_string())?;
-    let song2 = Song::new(&second_path).map_err(|x| x.to_string())?;
+    let song1 = Song::from_path(&first_path).map_err(|x| x.to_string())?;
+    let song2 = Song::from_path(&second_path).map_err(|x| x.to_string())?;
 
     println!(
         "d({:?}, {:?}) = {}",

examples/playlist.rs

@@ -73,7 +73,7 @@ fn main() -> Result<()> {
             .map(|p| p.to_owned())
             .collect(),
     )?;
-    let first_song = Song::new(file)?;
+    let first_song = Song::from_path(file)?;
     let mut analyzed_songs = vec![first_song.to_owned()];
     for (path, result) in rx.iter() {
         match result {

src/lib.rs

@@ -5,7 +5,7 @@
 //! The core of the library is the `Song` object, which relates to a
 //! specific analyzed song and contains its path, title, analysis, and
 //! other metadata fields (album, genre...).
-//! Analyzing a song is as simple as running `Song::new("/path/to/song")`.
+//! Analyzing a song is as simple as running `Song::from_path("/path/to/song")`.
 //!
 //! The [analysis](Song::analysis) field of each song is an array of f32, which makes the
 //! comparison between songs easy, by just using euclidean distance (see
@@ -27,8 +27,8 @@
 //! use bliss_audio::{BlissResult, Song};
 //!
 //! fn main() -> BlissResult<()> {
-//!     let song1 = Song::new("/path/to/song1")?;
-//!     let song2 = Song::new("/path/to/song2")?;
+//!     let song1 = Song::from_path("/path/to/song1")?;
+//!     let song2 = Song::from_path("/path/to/song2")?;
 //!
 //!     println!("Distance between song1 and song2 is {}", song1.distance(&song2));
 //!     Ok(())
@@ -44,7 +44,7 @@
 //!     let paths = vec!["/path/to/song1", "/path/to/song2", "/path/to/song3"];
 //!     let mut songs: Vec<Song> = paths
 //!         .iter()
-//!         .map(|path| Song::new(path))
+//!         .map(|path| Song::from_path(path))
 //!         .collect::<BlissResult<Vec<Song>>>()?;
 //!
 //!     // Assuming there is a first song
@@ -128,7 +128,7 @@ pub fn bulk_analyze(paths: Vec<String>) -> Vec<BlissResult<Song>> {
             handles.push(s.spawn(move |_| {
                 let mut result = Vec::with_capacity(chunk.len());
                 for path in chunk {
-                    let song = Song::new(&path);
+                    let song = Song::from_path(&path);
                     result.push(song);
                 }
                 result

src/library.rs

@@ -221,8 +221,8 @@ pub trait Library {
     /// * `distance` - a user-supplied valid distance metric, either taken
     ///    from the [distance](distance) module, or made from scratch.
     /// * `sort` - a user-supplied sorting function that uses the `distance`
-    ///    metric, either taken from the [distance](module), or made from
-    ///    scratch.
+    ///    metric, either taken from the [distance module](distance), or made
+    ///    from scratch.
     ///
     /// # Returns
     ///
@@ -276,7 +276,7 @@ pub trait Library {
             let child = thread::spawn(move || {
                 for path in owned_chunk {
                     info!("Analyzing file '{}'", path);
-                    let song = Song::new(&path);
+                    let song = Song::from_path(&path);
                     tx_thread.send((path.to_string(), song)).unwrap();
                 }
                 drop(tx_thread);
@@ -395,7 +395,7 @@ pub fn analyze_paths_streaming(
         let child = thread::spawn(move || {
             for path in owned_chunk {
                 info!("Analyzing file '{}'", path);
-                let song = Song::new(&path);
+                let song = Song::from_path(&path);
                 tx_thread.send((path.to_string(), song)).unwrap();
             }
         });

src/song.rs

@@ -75,7 +75,7 @@ pub struct Song {
 /// use bliss_audio::{AnalysisIndex, BlissResult, Song};
 ///
 /// fn main() -> BlissResult<()> {
-///     let song = Song::new("path/to/song")?;
+///     let song = Song::from_path("path/to/song")?;
 ///     println!("{}", song.analysis[AnalysisIndex::Tempo]);
 ///     Ok(())
 /// }
@@ -228,12 +228,12 @@ impl Song {
         self.analysis.custom_distance(&other.analysis, distance)
     }
 
-    /// Returns a decoded Song given a file path, or an error if the song
+    /// Returns a decoded [Song] given a file path, or an error if the song
     /// could not be analyzed for some reason.
     ///
     /// # Arguments
     ///
-    /// * `path` - A string holding a valid file path to a valid audio file.
+    /// * `path` - A [Path] holding a valid file path to a valid audio file.
     ///
     /// # Errors
     ///
@@ -244,7 +244,7 @@ impl Song {
     /// The error type returned should give a hint as to whether it was a
     /// decoding ([DecodingError](BlissError::DecodingError)) or an analysis
     /// ([AnalysisError](BlissError::AnalysisError)) error.
-    pub fn new<P: AsRef<Path>>(path: P) -> BlissResult<Self> {
+    pub fn from_path<P: AsRef<Path>>(path: P) -> BlissResult<Self> {
         let raw_song = Song::decode(path.as_ref())?;
 
         Ok(Song {
@@ -640,7 +640,7 @@ mod tests {
 
     #[test]
     fn test_analyze() {
-        let song = Song::new(Path::new("data/s16_mono_22_5kHz.flac")).unwrap();
+        let song = Song::from_path(Path::new("data/s16_mono_22_5kHz.flac")).unwrap();
         let expected_analysis = vec![
             0.3846389,
             -0.849141,
@@ -820,14 +820,14 @@ mod tests {
 
     #[test]
     fn test_index_analysis() {
-        let song = Song::new("data/s16_mono_22_5kHz.flac").unwrap();
+        let song = Song::from_path("data/s16_mono_22_5kHz.flac").unwrap();
         assert_eq!(song.analysis[AnalysisIndex::Tempo], 0.3846389);
         assert_eq!(song.analysis[AnalysisIndex::Chroma10], -0.95968974);
     }
 
     #[test]
     fn test_debug_analysis() {
-        let song = Song::new("data/s16_mono_22_5kHz.flac").unwrap();
+        let song = Song::from_path("data/s16_mono_22_5kHz.flac").unwrap();
         assert_eq!(
             "Analysis { Tempo: 0.3846389, Zcr: -0.849141, MeanSpectralCentroid: \
             -0.75481045, StdDeviationSpectralCentroid: -0.8790748, MeanSpectralR\