Tracking issue for RFC 3892: Complex numbers.

[traviscross]

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);
}

impl<T: Add<Output = T>> 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<Output = T>> 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>;
    // ...
}

Steps

• Accept an RFC.
  • Complex numbers rfcs#3892
• Implement in nightly.
  • Add Complex type and repr(complex) #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 }>:

• [MIPS][clang] make _Complex ABI match GCC llvm/llvm-project#212119 (fixed in LLVM 24)
• [PowerPC] make _Complex ABI GCC-compatible llvm/llvm-project#208917

For Complex<{ integer }>:

• [Sparc][clang] make _Complex ABI GCC-compatible llvm/llvm-project#212340 (fixed in LLVM 24)
• [Loongarch] ABI of _Complex of small integers is different from GCC llvm/llvm-project#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.

Precision of Mul

See #154023 (comment).

Related

TODO.

Implementation history

TODO.

cc @scimind2460

[MusicalNinjaDad]

I just saw the discussion on internals and would be keen to pick up the implementation of this if you are open to support @traviscross / @scimind2460

[scimind2460]

@musicalninja Thank you very much! I greatly appreciate it. One part where I can suggest the implementation can be taken over is the ABI repr to be changed exactly to C’s complex type after an initial PR lands.

…

On Thu, 2 Apr 2026 at 7:19 PM, MusicalNinjaDad ***@***.***> wrote: *MusicalNinjaDad* left a comment (rust-lang/rust#154023) <#154023 (comment)> I just saw the discussion on internals and would be keen to pick up the implementation of this if you are open to support @traviscross <https://github.com/traviscross> / @scimind2460 <https://github.com/scimind2460> — Reply to this email directly, view it on GitHub <#154023?email_source=notifications&email_token=BLL7PYH25D5D4AKFLW237GD4TZVVHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJXG42TKNBRGA42M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4177554109>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BLL7PYBXZHUWISTKTPDXDUD4TZVVHAVCNFSM6AAAAACWVVDHTWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCNZXGU2TIMJQHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[tgross35]

@scimind2460 do you plan to reopen a PR with the initial changes?

If you're running into issues with git, open a PR anyway and just describe what's going on. We can help you fix it, some of us are reasonably good at git things :).

[MusicalNinjaDad]

@scimind2460 - I can also offer to handle the rebase, or walk you through it, for the PR.

If you are able to reopen #154040 and I can support with the exact git commands to use, that's probably best. Then you keep all the review comments alive.
If you can't reopen then we can find another way too.

[CodesInChaos]

num-complex makes use of num-traits to implement many of its functions. An std:num::Complex which doesn't build on similar traits will be less flexible (only work for a few underlying types) or powerful (only support few operations) than num_complex. I'd expect such an inferior std implementation to splinter the ecosystem instead of unifying it.

Is it planned to add something similar to num_traits to std?

[scimind2460]

Thanks for the offer, @tgross35 and @MusicalNinjaDad! The problem is with certain submodules keeping on breaking. It also seems that my local copy has broken after me trying to horrendously fix a merge commit.

[scimind2460]

num-complex makes use of num-traits to implement many of its functions. An std:num::Complex which doesn't build on similar traits will be less flexible (only work for a few underlying types) or powerful (only support few operations) than num_complex. I'd expect such an inferior std implementation to splinter the ecosystem instead of unifying it.

Is it planned to add something similar to num_traits to std?

I don't think so. The libs-team folks didn't exactly like the idea. They thought it would bloat the MVP. But I think that if a different idea was proposed to move num_traits into std, it might have some support.

[CodesInChaos]

It doesn't matter until it gets stabilized, but I think a std::num::Complex without num-traits would be a mistake. It forces consumers to choose between the flexible but external num-complex crate, and the built-in but limited std::num::Complex, fracturing the ecosystem. Which is the exact opposite of "provide a unified API" goal stated in the RFC.

If no num-traits will be added (that's a pretty big change after all), then std should limit itself to a simple std::ffi::complex type, with the expectation that num-complex will wrap it (to solve the FFI issues), and consumers will continue to use num-complex.