diff --git a/complex/src/lib.rs b/complex/src/lib.rs index 1ef6e03..c73cb42 100644 --- a/complex/src/lib.rs +++ b/complex/src/lib.rs @@ -33,8 +33,33 @@ use traits::{Zero, One, Num, Float}; // probably doesn't map to C's _Complex correctly. /// A complex number in Cartesian form. +/// +/// ## Representation and Foreign Function Interface Compatibility +/// +/// `Complex` is memory layout compatible with an array `[T; 2]`. +/// +/// Note that `Complex` where F is a floating point type is **only** memory +/// layout compatible with C's complex types, **not** necessarily calling +/// convention compatible. This means that for FFI you can only pass +/// `Complex` behind a pointer, not as a value. +/// +/// ## Examples +/// +/// Example of extern function declaration. +/// +/// ``` +/// use num_complex::Complex; +/// use std::os::raw::c_int; +/// +/// extern "C" { +/// fn zaxpy_(n: *const c_int, alpha: *const Complex, +/// x: *const Complex, incx: *const c_int, +/// y: *mut Complex, incy: *const c_int); +/// } +/// ``` #[derive(PartialEq, Eq, Copy, Clone, Hash, Debug, Default)] #[cfg_attr(feature = "rustc-serialize", derive(RustcEncodable, RustcDecodable))] +#[repr(C)] pub struct Complex { /// Real portion of the complex number pub re: T,