Skip to content

Tracking issue for RFC 3892: Complex numbers (complex_numbers) #154023

Open
Open
Tracking issue for RFC 3892: Complex numbers (complex_numbers)#154023
Labels
C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCF-complex_numbers`#![feature(complex_numbers)]`T-langRelevant to the language teamT-libsRelevant to the library team, which will review and decide on the PR/issue.

Description

@traviscross
traviscross
opened on Mar 17, 2026

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

Unresolved Questions

ABI compatibility

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

For Complex<{ float }>:

For Complex<{ integer }>:

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 #154023 (comment).

Related

TODO.

Implementation history

TODO.

cc @scimind2460

Activity

  1. traviscross
    added
    C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFC
    T-langRelevant to the language team
    T-libs-api[DEPRECATED; DO NOT USE]
    F-complex_numbers`#![feature(complex_numbers)]`
    on Mar 17, 2026

  2. MusicalNinjaDad commented on Apr 2, 2026

    @MusicalNinjaDad
    MusicalNinjaDad
    on Apr 2, 2026
    Contributor

    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

  3. scimind2460 commented on Apr 3, 2026

    @scimind2460
    scimind2460
    on Apr 3, 2026 via email
    Contributor

  4. tgross35 commented on Apr 3, 2026

    @tgross35
    tgross35
    on Apr 3, 2026
    Member

    @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 :).

  5. MusicalNinjaDad commented on Apr 3, 2026

    @MusicalNinjaDad
    MusicalNinjaDad
    on Apr 3, 2026
    Contributor

    @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.

  6. CodesInChaos commented on Apr 8, 2026

    @CodesInChaos
    CodesInChaos
    on Apr 8, 2026

    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?

  7. scimind2460 commented on Apr 18, 2026

    @scimind2460
    scimind2460
    on Apr 18, 2026
    Contributor

    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.

  8. scimind2460 commented on Apr 18, 2026

    @scimind2460
    scimind2460
    on Apr 18, 2026
    Contributor

    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.

  9. CodesInChaos commented on Apr 18, 2026

    @CodesInChaos
    CodesInChaos
    on Apr 18, 2026

    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.

  10. tgross35 commented on Apr 18, 2026

    @tgross35
    tgross35
    on Apr 18, 2026
    Member

    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.

    To get your repo back to a clean state you can try something like this:

    # Set up the upstream (not needed if you already have this)
git remote add upstream git@github.com:rust-lang/rust.git
git fetch upstream

# Deinit submodules
git submodule deinit --all --force

# Check out your local `main` then make it identical to the upstream. Warning!! If you
# have unpushed changes on your local `main`, this will wipe them.
git switch main
git reset --hard upstream/main

    Then just reapply a known good patch. Looking at #154040 it seems like fa06e21 might be a good candidate.

    # New working branch
git switch -c complex-numbers2

# Use the github URL for the raw email-style patch, which `git am`
# knows how to apply.
curl -L https://github.com/rust-lang/rust/commit/fa06e21ab9ace9454ee66e87df9e59b4606daae5.patch |
    git am -3

  11. tgross35 commented on Apr 18, 2026

    @tgross35
    tgross35
    on Apr 18, 2026
    Member

    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.

    Note that num-complex will be able to switch to reexporting the std type once available, and will likely want to do so given the ABI issues it resolves.

  12. Apersoma commented on Apr 18, 2026

    @Apersoma
    Apersoma
    on Apr 18, 2026
    Contributor

    will there be any precision guarantees for multiplication? maybe even division, probably not though.
    also what are all the git issues that all the prs seem to be having?

  13. 41 remaining items

  14. JonathanBrouwer
    added a commit that references this issue on Sep 29, 2026

    Rollup merge of rust-lang#162832 - folkertdev:complex-mul-div, r=tgro…

    f656696
  15. rust-bors
    added a commit that references this issue on Sep 29, 2026

    Unrolled build for #162832 in rollup 163472

    63b34fe
  16. pull
    added a commit that references this issue on Sep 30, 2026

    Rollup merge of #162832 - folkertdev:complex-mul-div, r=tgross35

    ec422e6
  17. bjorn3
    added a commit that references this issue on Sep 30, 2026

    Rollup merge of #162832 - folkertdev:complex-mul-div, r=tgross35

    f62e2cf
  18. JonathanBrouwer
    added a commit that references this issue on Sep 30, 2026

    Rollup merge of rust-lang#162921 - folkertdev:complex-mips64, r=beetrees

    e035dd9
  19. jhpratt
    added a commit that references this issue on Oct 1, 2026

    Rollup merge of rust-lang#162921 - folkertdev:complex-mips64, r=beetrees

    973d397
  20. rust-bors
    added a commit that references this issue on Oct 1, 2026

    Unrolled build for #162921 in rollup 163583

    1727065
  21. RalfJung
    added a commit that references this issue on Oct 1, 2026

    Rollup merge of #162921 - folkertdev:complex-mips64, r=beetrees

    c501a7f
  22. github-actions
    added a commit that references this issue on Oct 5, 2026

    Rollup merge of #162921 - folkertdev:complex-mips64, r=beetrees

    a4ddb3b
  23. JonathanBrouwer
    added 4 commits that reference this issue on Oct 8, 2026

    Rollup merge of rust-lang#163617 - folkertdev:complex-mips, r=beetrees

    1f3a582

    Rollup merge of rust-lang#163617 - folkertdev:complex-mips, r=beetrees

    a92dffc

    Rollup merge of rust-lang#163617 - folkertdev:complex-mips, r=beetrees

    c963d95

    Rollup merge of rust-lang#163617 - folkertdev:complex-mips, r=beetrees

    30a1a4a
  24. rust-bors
    added a commit that references this issue on Oct 8, 2026

    Unrolled build for #163617 in rollup 164005

    8f0a5fc
  25. programskillforverification
    added a commit that references this issue on Oct 9, 2026

    Rollup merge of #163617 - folkertdev:complex-mips, r=beetrees

    6a20493
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCF-complex_numbers`#![feature(complex_numbers)]`T-langRelevant to the language teamT-libsRelevant to the library team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions