Tracking issue for RFC 3892: Complex numbers (`complex_numbers`)

This is a tracking issue for RFC 3892: Complex numbers.

The feature gate for the issue is #![feature(complex_numbers)].

About tracking issues

Tracking issues are used to record the overall progress of implementation. They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions. A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature. Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Library API

// in core::num

pub struct Complex<T> {
    pub re: T,
    pub im: T,
}

impl<T> Complex<T> {
    pub fn new(re: T, im: T);
    pub fn conjugate(self) -> Self;
}

impl<T: Default> Default for Complex<T> { /* ... */ }

impl<T: Neg> Neg for Complex<T> {
    type Output = Complex<T::Output>;
    // ...
}

impl<T: Add> Add<Self> for Complex<T> {
    type Output = Complex<T::Output>;
    // ...
}

impl<T: Add<Output = T>> Add<T> for Complex<T> {
    type Output = Complex<T::Output>;
    // ...
}

impl<T: Sub> Sub<Self> for Complex<T> {
    type Output = Complex<T::Output>;
    // ...
}

impl<T: Sub<Output = T>> Sub<T> for Complex<T> {
    type Output = Complex<T::Output>;
    // ...
}

impl Mul for Complex<{float}> {
    type Output = Self;
    // ...
}

impl Div for Complex<{float}> {
    type Output = Self;
    // ...
}

Steps

• Accept an RFC.
  • https://github.com/rust-lang/rfcs/pull/3892
• Implement in nightly.
  • https://github.com/rust-lang/rust/pull/158885
• Add documentation to the reference.
  • See the instructions.
• Stabilize.
  • See the instructions.

Unresolved Questions

ABI compatibility

On some targets, Clang and GCC deviate on the ABI they use.

For Complex<{ float }>:

• https://github.com/llvm/llvm-project/pull/212119 (fixed in LLVM 24)
• https://github.com/llvm/llvm-project/pull/208917

For Complex<{ integer }>:

• https://github.com/llvm/llvm-project/pull/212340 (fixed in LLVM 24)
• https://github.com/llvm/llvm-project/issues/214810

Note that Complex<{ integer }> is a GNU extension, and we don't currently intend to guarantee ABI compatibility for the complex integers a part of the initial stabilization. The compatibility issues are tracked here for completeness.

Clang also outright rejects the type in some cases where it has no defined "C" ABI. If neither GCC nor clang accept the equivalent code (e.g. because SSE is missing), we should at least consider just refusing to compile the program.

Precision of Mul

See https://github.com/rust-lang/rust/issues/154023#issuecomment-4273964728.

Related

TODO.

Implementation history

TODO.

cc @scimind2460

Start with the complex_numbers feature gate, the linked implementation pull request, and the proposed core::num::Complex API. Review the reference documentation instructions and stabilization guide; the tracking issue is complete when nightly implementation, reference documentation, and stabilization work are all resolved.