diff --git a/CHANGELOG.md b/CHANGELOG.md index 7319589f..e244516e 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/fitsio/examples/full_example.rs b/fitsio/examples/full_example.rs index 866c7375..8f968ff1 100644 --- a/fitsio/examples/full_example.rs +++ b/fitsio/examples/full_example.rs @@ -49,8 +49,8 @@ fn run() -> Result<(), Box> { /* 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)?; diff --git a/fitsio/src/hdu.rs b/fitsio/src/hdu.rs index 5c6b1e62..f40f29c3 100644 --- a/fitsio/src/hdu.rs +++ b/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> { + # 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::(&mut fptr, "foo")?, 1i64); + # Ok(()) + # } + # } + ``` + */ + pub fn write_key_cmt( + &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 diff --git a/fitsio/src/headers.rs b/fitsio/src/headers.rs index 513be1a2..c400ac1e 100644 --- a/fitsio/src/headers.rs +++ b/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)]