C interop: `Complex<T>`

[nxsaken]

Metadata
Point of contact	@folkertdev
Team(s)	compiler, lang, libs-api
Goal document	2026/interop-complex

Summary

Rust should be able to define an ABI-compatible counterpart to every signature that C can define. This is important for C interop and translation of code from C to rust, using manual FFI, and tooling like c-bindgen and c2rust. This goal closes a long-standing gap in rust's ability to match C.

Tasks and status

[nxsaken]

This issue is intended for status updates only.

For general questions or comments, please contact the owner(s) directly.

[folkertdev]

An initial update

tracking issue: rust-lang/rust#154023
accepted rfc: rust-lang/rfcs#3892

This project goal adds core::num::Complex, a complex number type that is ABI-compatible with the C _Complex type (at least when the element type is a C float type).

/// A complex number.
#[derive(Clone, Copy, Debug, PartialEq)]
#[unstable(feature = "complex_numbers", issue = "154023")]
#[repr(C)]
#[lang = "complex"]
pub struct Complex<T> {
    /// The real component.
    pub re: T,
    /// The imaginary component.
    pub im: T,
}

We've started work on the type itself:

• Add core::num::Complex rust#158885
• add Complex<T> layout tests for straightforward targets rust#161187

These PRs implement the type and start the work on making it ABI-compatible with C _Complex across targets. With the second PR we've tackled the easy cases, leaving PowerPC, MIPS and Sparc. Those require more work.

One foundational piece is this PR that gives us more flexibility in specifying padding.

• make pad_i32 of PassMode::cast an integer rust#160132

Once that is merged I'll continue to cherry-pick changes off of this WIP branch where I've got all targets I can get my hands on working:

• Complex layout phase 2 rust#159981

We've also started work on the API and libcalls:

• implement Add and Sub for Complex rust#161227
• implement Complex mul and div libcalls compiler-builtins#1288

---

When first looking into this, it was clear that matching C _Complex on all targets was going to be immensely tedious. The RFC only expressed the requirement that we'd match the C type, without much research into what that would entail. It turns out that many ABIs have custom behavior for _Complex that deviates from just a struct with two fields.

I made a fork (that I do hope to upstream) of abi-cafe that can cross-compile, and added support for complex numbers (my fork). In combination with a number of (custom) GCC builds and qemu, my abi-cafe can effectively fuzz the ABI of _Complex across targets, finding differences between the WIP Rust implementation, Clang and GCC. I've since added support for some other (unstable) features like packed structs, c-variadic functions and f16b.

This tool has been extremely helpful in finding and testing fixes for various rustc bugs:

• on X86 SysV the ABI of an empty struct is different from Clang and GCC rust#161117
• sparc: make ABI consistent with clang rust#160401
• fix arm homogeneous aggregate ABI rust#161070
• fix is_homogeneous_aggregate: use unit size, not total size  rust#161394

... and a much larger number of Clang bugs, here are the ones most relevant to Complex:

• [MIPS][clang] make _Complex ABI match GCC llvm/llvm-project#212119
• [Sparc][clang] make _Complex ABI GCC-compatible llvm/llvm-project#212340
• [PowerPC] make _Complex ABI GCC-compatible llvm/llvm-project#208917
• [RISCV] make _Complex {integer} consistent with GCC llvm/llvm-project#216404
• [clang][LoongArch] Match GCC ABI handling of integer complex types llvm/llvm-project#215222

Blockers

Review capacity has been a real issue here. ABIs are hard, and changes to them are time-consuming to review.

Help wanted

On the libs side of things, it's unclear what other APIs we want on Complex. The RFC does not specify anything further, so extensions need to go throug ACP.

The num_complex crate has various functions (conversion from polar coordinates, sqrt, sin, etc.). However these implementations are generally not equivalent to the libc functions when dealing with floating point edge cases, particularly NaN.

There is more low-hanging fruit too in terms of trait implementations. Maybe the type should be Hash, or impl<T: Default> Default for Complex<T>, etc. I'd be happy for someone else to tackle this.