Added write_key_cmt method to include comments with keys

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 ### Added
+* `fitsio`: A `write_key_cmt` method to complement the `write_key` method, to add optional comments to the FITS HDU keys.
 ### Changed
 ### Removed
 

fitsio/examples/full_example.rs

@@ -49,8 +49,8 @@ fn run() -> Result<(), Box<dyn Error>> {
         /* Now we add the header keys */
         hdu.write_key(&mut fitsfile, "PROJECT", "My First Astronomy Project")?;
 
-        /* Now the exposure time */
-        hdu.write_key(&mut fitsfile, "EXPTIME", 15.2f32)?;
+        /* Now the exposure time, with a comment */
+        hdu.write_key_cmt(&mut fitsfile, "EXPTIME", 15.2f32, "Exposure time [s]")?;
 
         /* And finally the image id */
         hdu.write_key(&mut fitsfile, "IMAGE_ID", 20180101010005i64)?;

fitsio/src/hdu.rs

@@ -96,6 +96,37 @@ impl FitsHdu {
         T::write_key(fits_file, name, value)
     }
 
+    /**
+    Write a fits key to the current header with a comment
+
+    # Example
+
+    ```rust
+    # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    # let tdir = tempfile::Builder::new().prefix("fitsio-").tempdir().unwrap();
+    # let tdir_path = tdir.path();
+    # let filename = tdir_path.join("test.fits");
+    # {
+    # let mut fptr = fitsio::FitsFile::create(filename).open()?;
+    fptr.primary_hdu()?.write_key_cmt(&mut fptr, "foo", 1i64, "FOO key")?;
+    assert_eq!(fptr.hdu(0)?.read_key::<i64>(&mut fptr, "foo")?, 1i64);
+    # Ok(())
+    # }
+    # }
+    ```
+    */
+    pub fn write_key_cmt<T: WritesKey>(
+        &self,
+        fits_file: &mut FitsFile,
+        name: &str,
+        value: T,
+        comment: &str,
+    ) -> Result<()> {
+        fits_file.make_current(self)?;
+        fits_check_readwrite!(fits_file);
+        T::write_key_cmt(fits_file, name, value, comment)
+    }
+
     /**
     Read pixels from an image between a start index and end index
 

fitsio/src/headers.rs

@@ -95,6 +95,8 @@ impl ReadsKey for String {
 pub trait WritesKey {
     #[doc(hidden)]
     fn write_key(f: &mut FitsFile, name: &str, value: Self) -> Result<()>;
+    #[doc(hidden)]
+    fn write_key_cmt(f: &mut FitsFile, name: &str, value: Self, comment: &str) -> Result<()>;
 }
 
 macro_rules! writes_key_impl_int {
@@ -118,6 +120,31 @@ macro_rules! writes_key_impl_int {
                 }
                 check_status(status)
             }
+
+            fn write_key_cmt(
+                f: &mut FitsFile,
+                name: &str,
+                value: Self,
+                comment: &str,
+            ) -> Result<()> {
+                let c_name = ffi::CString::new(name)?;
+                let c_cmt = ffi::CString::new(comment)?;
+                let mut status = 0;
+
+                let datatype = u8::from($datatype);
+
+                unsafe {
+                    fits_write_key(
+                        f.fptr.as_mut() as *mut _,
+                        datatype as _,
+                        c_name.as_ptr(),
+                        &value as *const $t as *mut c_void,
+                        c_cmt.as_ptr(),
+                        &mut status,
+                    );
+                }
+                check_status(status)
+            }
         }
     };
 }
@@ -150,6 +177,29 @@ macro_rules! writes_key_impl_flt {
                 }
                 check_status(status)
             }
+
+            fn write_key_cmt(
+                f: &mut FitsFile,
+                name: &str,
+                value: Self,
+                comment: &str,
+            ) -> Result<()> {
+                let c_name = ffi::CString::new(name)?;
+                let c_cmt = ffi::CString::new(comment)?;
+                let mut status = 0;
+
+                unsafe {
+                    $func(
+                        f.fptr.as_mut() as *mut _,
+                        c_name.as_ptr(),
+                        value,
+                        9,
+                        c_cmt.as_ptr(),
+                        &mut status,
+                    );
+                }
+                check_status(status)
+            }
         }
     };
 }
@@ -161,6 +211,9 @@ impl WritesKey for String {
     fn write_key(f: &mut FitsFile, name: &str, value: Self) -> Result<()> {
         WritesKey::write_key(f, name, value.as_str())
     }
+    fn write_key_cmt(f: &mut FitsFile, name: &str, value: Self, comment: &str) -> Result<()> {
+        WritesKey::write_key_cmt(f, name, value.as_str(), comment)
+    }
 }
 
 impl<'a> WritesKey for &'a str {
@@ -181,6 +234,25 @@ impl<'a> WritesKey for &'a str {
 
         check_status(status)
     }
+
+    fn write_key_cmt(f: &mut FitsFile, name: &str, value: Self, comment: &str) -> Result<()> {
+        let c_name = ffi::CString::new(name)?;
+        let c_value = ffi::CString::new(value)?;
+        let c_cmt = ffi::CString::new(comment)?;
+        let mut status = 0;
+
+        unsafe {
+            fits_write_key_str(
+                f.fptr.as_mut() as *mut _,
+                c_name.as_ptr(),
+                c_value.as_ptr(),
+                c_cmt.as_ptr(),
+                &mut status,
+            );
+        }
+
+        check_status(status)
+    }
 }
 
 #[cfg(test)]