fitsio_sys/
lib.rs

1//! This package was automatically generated with [`rust-bindgen`][1] and as such was not
2//! user-generated.
3//!
4//! The functions contained are expected to be used with [`fitsio`][2], a high level API wrapper
5//! around the low level direct C-bindings, though the bindings are complete enough to be usable.
6//!
7//! This code will not be directly documented, and so users should refer to the [`fitsio` C
8//! documentation][3] for usage.
9//!
10//! ## Note about function names
11//!
12//! Unfortunately we must use fits short names throughout. The C-api exposes long names for
13//! functions which are more descriptive, for example `fits_open_file` instead of `ffopen`, but the
14//! symbols available in the library have only short names, and the long names are merely
15//! preprocessor definitions.
16//!
17//! ## Examples
18//!
19//! ```rust
20//! use std::ptr;
21//! use std::ffi;
22//! # use fitsio_sys::{ffinit, ffphps, ffclos};
23//!
24//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! let filename = ffi::CString::new("!/tmp/test.fits").unwrap();
26//! let mut fptr = ptr::null_mut();
27//! let mut status = 0;
28//!
29//! unsafe {
30//!     // Create a new file, clobbering any pre-existing file
31//!     ffinit(&mut fptr as *mut *mut _,
32//!         filename.as_ptr(),
33//!         &mut status);
34//!
35//!     // Add an empty primary HDU
36//!     ffphps(fptr, 8, 0, ptr::null_mut(), &mut status);
37//!
38//!     // Finally close the file
39//!     ffclos(fptr, &mut status);
40//! }
41//!
42//! assert_eq!(status, 0);
43//! # Ok(())
44//! # }
45//! ```
46//!
47//! [1]: https://github.com/crabtw/rust-bindgen
48//! [2]: https://crates.io/crates/fitsio
49//! [3]: http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/cfitsio.html
50
51#![allow(improper_ctypes)]
52
53mod aliases;
54pub use aliases::*;
55
56#[cfg(not(feature = "bindgen"))]
57#[allow(non_camel_case_types, non_upper_case_globals, non_snake_case)]
58#[allow(
59    clippy::unreadable_literal,
60    clippy::transmute_ptr_to_ptr,
61    clippy::redundant_static_lifetimes,
62    clippy::missing_safety_doc,
63    clippy::should_implement_trait,
64    clippy::upper_case_acronyms
65)]
66mod sys {
67
68    // automatically generated by rust-bindgen
69    // Prevent clippy from throwing errors in generated code
70
71    #[cfg(target_pointer_width = "64")]
72    include!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/bindings_64.rs"));
73    #[cfg(target_pointer_width = "32")]
74    include!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/bindings_32.rs"));
75}
76
77#[cfg(feature = "bindgen")]
78#[allow(
79    non_upper_case_globals,
80    non_camel_case_types,
81    non_snake_case,
82    improper_ctypes
83)]
84// Prevent clippy from throwing errors in generated code
85#[allow(
86    clippy::unreadable_literal,
87    clippy::transmute_ptr_to_ptr,
88    clippy::redundant_static_lifetimes,
89    clippy::missing_safety_doc,
90    clippy::useless_transmute,
91    clippy::trivially_copy_pass_by_ref,
92    clippy::too_many_arguments,
93    clippy::should_implement_trait,
94    clippy::upper_case_acronyms
95)]
96mod sys {
97    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
98}
99
100pub use sys::*;
101
102// global functions
103
104/// Representation of the version of cfitsio used within bindings
105pub struct CfitsioVersion {
106    /// Minor version
107    pub minor: u32,
108    /// Major version
109    pub major: u32,
110}
111
112impl std::fmt::Display for CfitsioVersion {
113    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
114        write!(f, "{}.{}", self.major, self.minor)
115    }
116}
117
118pub fn cfitsio_version() -> CfitsioVersion {
119    CfitsioVersion {
120        // TODO: we need to detect the version of cfitsio we are binding to. Version >=4 supports
121        // this field, but earlier versions don't.
122        // patch: CFITSIO_MICRO,
123        minor: CFITSIO_MINOR,
124        major: CFITSIO_MAJOR,
125    }
126}
127
128#[cfg(test)]
129mod tests {
130    use std::{ffi::CString, ptr};
131
132    use crate::{
133        aliases::{fits_get_num_rows, fits_movabs_hdu, fits_open_file},
134        ffgnrw, ffmahd, ffopen,
135    };
136
137    #[test]
138    fn fitsio_sys_works() {
139        let mut fptr = ptr::null_mut();
140        let filename = CString::new("../testdata/full_example.fits").expect("valid C string");
141        let iomode = 0; // read only
142        let mut num_table_rows = 0;
143        let mut status = 0;
144
145        unsafe {
146            ffopen(&mut fptr, filename.as_ptr(), iomode, &mut status);
147            assert_eq!(status, 0);
148
149            ffmahd(fptr, 2, &mut 0, &mut status);
150            assert_eq!(status, 0);
151
152            ffgnrw(fptr, &mut num_table_rows, &mut status);
153            assert_eq!(status, 0);
154            assert_eq!(num_table_rows, 50);
155        }
156    }
157
158    #[test]
159    fn fitsio_sys_aliases_work() {
160        let mut fptr = ptr::null_mut();
161        let filename = CString::new("../testdata/full_example.fits").expect("valid C string");
162        let iomode = 0; // read only
163        let mut num_table_rows = 0;
164        let mut status = 0;
165
166        unsafe {
167            fits_open_file(&mut fptr, filename.as_ptr(), iomode, &mut status);
168            assert_eq!(status, 0);
169
170            fits_movabs_hdu(fptr, 2, &mut 0, &mut status);
171            assert_eq!(status, 0);
172
173            fits_get_num_rows(fptr, &mut num_table_rows, &mut status);
174            assert_eq!(status, 0);
175            assert_eq!(num_table_rows, 50);
176        }
177    }
178}
fitsio_sys/lib.rs

fitsio_sys/
lib.rs
