Trait ComplexElement

Source

pub unsafe trait ComplexElement {
    type Component;
}

Expand description

A type the bulk complex-array helpers may read as raw bytes: two contiguous Self::Component scalars, real part first.

Implementing this is how a foreign complex type — num_complex::Complex<T>, or your own #[repr(C)] pair — reaches crate::complex’s serialize_with helpers and crate::complex_array’s serde(with) modules. Complex implements it for every scalar BEVE encodes, and the num-complex feature adds num_complex::Complex<T>.

Component is an associated type so the helpers can name it in their bounds: complex::f32_array requires Component = f32, so a same-width class cannot cross.

§Safety

Self must have the layout #[repr(C)] struct { re: Component, im: Component }: two Component values, real first, no padding, every byte initialized. The helpers read size_of_val(slice) bytes out of a &[Self], so padding leaks uninitialized memory into the output and a pointer field writes its address.

Self must also share Component’s alignment. A plain #[repr(C)] pair does; #[repr(packed)] satisfies everything above but drops to align 1, and the helpers build a &[Complex<Component>] over your slice.

Size and alignment are checked at run time. Padding and field order cannot be checked and are the implementor’s promise.

§A padded type needs no impl, and gets none

#[repr(C)] struct { re: i16, tag: u8 } is size 4, align 2 — identical to Complex<i16> — so no run-time check can reject it. Absent an unsafe impl it does not compile:

#[derive(Clone, Copy)]
#[repr(C)]
struct Padded {
    re: i16,
    tag: u8,
}

fn encode<S: serde::Serializer>(data: &[Padded], s: S) {
    let _ = beve::complex::i16_array(data, s);
}

§A same-width class is refused

Pairs of i32 cannot reach the f32 helper, which would otherwise emit the payload unchanged under an f32 class tag:

#[derive(Clone, Copy)]
#[repr(C)]
struct IntPair {
    re: i32,
    im: i32,
}

// SAFETY: `#[repr(C)]` over two `i32`, real first.
unsafe impl beve::ComplexElement for IntPair {
    type Component = i32;
}

fn encode<S: serde::Serializer>(data: &[IntPair], s: S) {
    let _ = beve::complex::f32_array(data, s);
}

The same type reaches its own class’s helper:

#[derive(Clone, Copy)]
#[repr(C)]
struct IntPair {
    re: i32,
    im: i32,
}

// SAFETY: `#[repr(C)]` over two `i32`, real first.
unsafe impl beve::ComplexElement for IntPair {
    type Component = i32;
}

fn encode<S: serde::Serializer>(data: &[IntPair], s: S) {
    let _ = beve::complex::i32_array(data, s);
}

Required Associated Types§

Source

type Component

The scalar type of the real and imaginary parts.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Trait ComplexElement Copy item path

§Safety

§A padded type needs no impl, and gets none

§A same-width class is refused

Required Associated Types§

type Component

Dyn Compatibility§

Implementations on Foreign Types§

impl ComplexElement for Complex<f32>

type Component = f32

impl ComplexElement for Complex<f64>

type Component = f64

impl ComplexElement for Complex<i8>

type Component = i8

impl ComplexElement for Complex<i16>

type Component = i16

impl ComplexElement for Complex<i32>

type Component = i32

impl ComplexElement for Complex<i64>

type Component = i64

impl ComplexElement for Complex<i128>

type Component = i128

impl ComplexElement for Complex<u8>

type Component = u8

impl ComplexElement for Complex<u16>

type Component = u16

impl ComplexElement for Complex<u32>

type Component = u32

impl ComplexElement for Complex<u64>

type Component = u64

impl ComplexElement for Complex<u128>

type Component = u128

Implementors§

impl ComplexElement for beve::Complex<f32>

type Component = f32

impl ComplexElement for beve::Complex<f64>

type Component = f64

impl ComplexElement for beve::Complex<i8>

type Component = i8

impl ComplexElement for beve::Complex<i16>

type Component = i16

impl ComplexElement for beve::Complex<i32>

type Component = i32

impl ComplexElement for beve::Complex<i64>

type Component = i64

impl ComplexElement for beve::Complex<i128>

type Component = i128

impl ComplexElement for beve::Complex<u8>

type Component = u8

impl ComplexElement for beve::Complex<u16>

type Component = u16

impl ComplexElement for beve::Complex<u32>

type Component = u32

impl ComplexElement for beve::Complex<u64>

type Component = u64

impl ComplexElement for beve::Complex<u128>

type Component = u128

Trait ComplexElement