Merge pull request #2 from Yoshanuikabundi/open-ergonomics

Improved ergonomics for opening files

README.md

@@ -11,11 +11,9 @@ files with a safe api.
 ### Basic usage
 ```rust
 use xdrfile::*;
-use std::path::Path; 
 
-let mut path = Path::new("tests/1l2y.xtc");
 // get a handle to the file
-let mut trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
+let mut trj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
 
 // find number of atoms in the file
 let num_atoms = trj.get_num_atoms().unwrap();
@@ -48,11 +46,9 @@ Rc is required)
 
 ```rust
 use xdrfile::*;
-use std::path::Path; 
 
-let mut path = Path::new("tests/1l2y.xtc");
 // get a handle to the file
-let trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
+let trj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
 
 // iterate over all frames
 for (idx, frame) in trj.into_iter().filter_map(Result::ok).enumerate() {

src/iterator.rs

@@ -122,7 +122,7 @@ mod tests {
 
     #[test]
     pub fn test_xtc_trajectory_iterator() {
-        let traj = XTCTrajectory::open(Path::new("tests/1l2y.xtc"), FileMode::Read).unwrap();
+        let traj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
         let frames: Vec<Rc<Frame>> = traj.into_iter().filter_map(Result::ok).collect();
         assert!(frames.len() == 38);
         assert!(frames[0].step == 1, frames[0].step);
@@ -131,7 +131,7 @@ mod tests {
 
     #[test]
     pub fn test_trr_trajectory_iterator() {
-        let traj = TRRTrajectory::open(Path::new("tests/1l2y.trr"), FileMode::Read).unwrap();
+        let traj = TRRTrajectory::open_read("tests/1l2y.trr").unwrap();
         let frames: Vec<Rc<Frame>> = traj.into_iter().filter_map(Result::ok).collect();
         assert!(frames.len() == 38);
         assert!(frames[0].step == 1, frames[0].step);

src/lib.rs

@@ -8,11 +8,9 @@
 //! # Basic usage example
 //! ```rust
 //! use xdrfile::*;
-//! use std::path::Path;
 //!
-//! let mut path = Path::new("tests/1l2y.xtc");
 //! // get a handle to the file
-//! let mut trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
+//! let mut trj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
 //!
 //! // find number of atoms in the file
 //! let num_atoms = trj.get_num_atoms().unwrap();
@@ -45,11 +43,9 @@
 //!
 //! ```rust
 //! use xdrfile::*;
-//! use std::path::Path;
 //!
-//! let mut path = Path::new("tests/1l2y.xtc");
 //! // get a handle to the file
-//! let trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
+//! let trj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
 //!
 //! // iterate over all frames
 //! for (idx, frame) in trj.into_iter().filter_map(Result::ok).enumerate() {
@@ -157,7 +153,8 @@ struct XDRFile {
 }
 
 impl XDRFile {
-    pub fn open(path: &Path, filemode: FileMode) -> Result<XDRFile> {
+    pub fn open(path: impl AsRef<Path>, filemode: FileMode) -> Result<XDRFile> {
+        let path = path.as_ref();
         let path_p = path_to_cstring(path).into_raw();
         let mode_p = CString::new(filemode.value()).unwrap().into_raw();
 
@@ -211,7 +208,7 @@ pub struct XTCTrajectory {
 }
 
 impl XTCTrajectory {
-    pub fn open(path: &Path, filemode: FileMode) -> Result<XTCTrajectory> {
+    pub fn open(path: impl AsRef<Path>, filemode: FileMode) -> Result<XTCTrajectory> {
         let xdr = XDRFile::open(path, filemode)?;
         Ok(XTCTrajectory {
             handle: xdr,
@@ -219,6 +216,21 @@ impl XTCTrajectory {
             num_atoms: Lazy::new(),
         })
     }
+
+    /// Open a file in read mode
+    pub fn open_read(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open(path, FileMode::Read)
+    }
+
+    /// Open a file in append mode
+    pub fn open_append(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open(path, FileMode::Append)
+    }
+
+    /// Open a file in write mode
+    pub fn open_write(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open(path, FileMode::Write)
+    }
 }
 
 impl Trajectory for XTCTrajectory {
@@ -299,13 +311,28 @@ pub struct TRRTrajectory {
 }
 
 impl TRRTrajectory {
-    pub fn open(path: &Path, filemode: FileMode) -> Result<TRRTrajectory> {
+    pub fn open(path: impl AsRef<Path>, filemode: FileMode) -> Result<TRRTrajectory> {
         let xdr = XDRFile::open(path, filemode)?;
         Ok(TRRTrajectory {
             handle: xdr,
             num_atoms: Lazy::new(),
         })
     }
+
+    /// Open a file in read mode
+    pub fn open_read(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open(path, FileMode::Read)
+    }
+
+    /// Open a file in append mode
+    pub fn open_append(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open(path, FileMode::Append)
+    }
+
+    /// Open a file in write mode
+    pub fn open_write(path: impl AsRef<Path>) -> Result<Self> {
+        Self::open(path, FileMode::Write)
+    }
 }
 
 impl Trajectory for TRRTrajectory {
@@ -404,7 +431,7 @@ mod tests {
             box_vector: [[1.0, 2.0, 3.0], [2.0, 1.0, 3.0], [3.0, 2.0, 1.0]],
             coords: vec![[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
         };
-        let mut f = XTCTrajectory::open(tmp_path, FileMode::Write).unwrap();
+        let mut f = XTCTrajectory::open_write(&tmp_path).unwrap();
         let write_status = f.write(&frame);
         match write_status {
             Err(_) => panic!("Failed"),
@@ -413,7 +440,7 @@ mod tests {
         f.flush().unwrap();
 
         let mut new_frame = Frame::with_capacity(natoms);
-        let mut f = XTCTrajectory::open(tmp_path, FileMode::Read).unwrap();
+        let mut f = XTCTrajectory::open_read(tmp_path).unwrap();
         let num_atoms = f.get_num_atoms().unwrap();
         assert_eq!(num_atoms, natoms);
 
@@ -443,7 +470,7 @@ mod tests {
             box_vector: [[1.0, 2.0, 3.0], [2.0, 1.0, 3.0], [3.0, 2.0, 1.0]],
             coords: vec![[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
         };
-        let mut f = TRRTrajectory::open(tmp_path, FileMode::Write).unwrap();
+        let mut f = TRRTrajectory::open_write(tmp_path).unwrap();
         let write_status = f.write(&frame);
         match write_status {
             Err(_) => panic!("Failed"),
@@ -452,7 +479,7 @@ mod tests {
         f.flush().unwrap();
 
         let mut new_frame = Frame::with_capacity(natoms);
-        let mut f = TRRTrajectory::open(tmp_path, FileMode::Read).unwrap();
+        let mut f = TRRTrajectory::open_read(tmp_path).unwrap();
         // let num_atoms = f.get_num_atoms().unwrap();
         // assert_eq!(num_atoms, natoms);
 
@@ -472,11 +499,11 @@ mod tests {
     #[test]
     fn test_err_could_not_open() {
         let file_name = "non-existent.xtc";
-        let path = Path::new(&file_name);
+        let expexted_path = Path::new(&file_name);
-        if let Err(e) = XDRFile::open(path, FileMode::Read) {
+        if let Err(e) = XDRFile::open(file_name, FileMode::Read) {
             match e {
                 Error::CouldNotOpenFile(err_path, err_mode) => {
-                    assert_eq!(path, err_path);
+                    assert_eq!(expexted_path, err_path);
                     assert!(FileMode::Read == err_mode)
                 }
                 _ => panic!("Wrong Error type"),
@@ -487,8 +514,7 @@ mod tests {
     #[test]
     fn test_err_could_not_read_atom_nr() {
         let file_name = "README.md"; // not a trajectory
-        let path = Path::new(&file_name);
+        let mut trr = TRRTrajectory::open_read(file_name).unwrap();
-        let mut trr = TRRTrajectory::open(path, FileMode::Read).unwrap();
         if let Err(e) = trr.get_num_atoms() {
             match e {
                 Error::CouldNotReadAtomNumber(code) => {
@@ -502,9 +528,8 @@ mod tests {
     #[test]
     fn test_err_could_not_read() {
         let file_name = "README.md"; // not a trajectory
-        let path = Path::new(&file_name);
         let mut frame = Frame::with_capacity(1);
-        let mut trr = TRRTrajectory::open(path, FileMode::Read).unwrap();
+        let mut trr = TRRTrajectory::open_read(file_name).unwrap();
         if let Err(e) = trr.read(&mut frame) {
             match e {
                 Error::CouldNotRead(code) => {

tests/integration.rs

@@ -1,15 +1,13 @@
 #[cfg(test)]
 mod integration {
 
-    use std::path::Path;
+    
     use std::rc::Rc;
     use xdrfile::*;
 
     #[test]
     fn test_use_library() {
-        let path = Path::new("tests/1l2y.xtc");
+        let mut trj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
-
-        let mut trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
         let num_atoms = trj.get_num_atoms().unwrap();
         let mut frame = Frame::with_capacity(num_atoms);
 
@@ -20,9 +18,7 @@ mod integration {
 
     #[test]
     fn test_use_library_iterator() {
-        let path = Path::new("tests/1l2y.xtc");
+        let trj = XTCTrajectory::open_read("tests/1l2y.xtc").unwrap();
-
-        let trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
         let frames: Vec<Rc<Frame>> = trj.into_iter().filter_map(Result::ok).collect();
         for (idx, frame) in frames.iter().enumerate() {
             assert_eq!(frame.step as usize, idx + 1);