Add primitive numeric traits

[CAD97]

• Draft implementation accompanying ACP: primitive numeric traits libs-team#371

[rustbot]

r? @workingjubilee

rustbot has assigned @workingjubilee.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[CAD97]

If this is to actually land, I'll probably want to take a stab at refactoring the primitive impl macros to reduce duplication of the docs, e.g. something like

macro_rules! int_methods {
    (
        type Self = $SelfT:ty;
        // …

        $callback:path!($);
    ) => {
        $callback!(
            #[doc(concat!(…))]
            fn count_ones;
        );
        // …
    };
}

trait Integer {
    int_methods!(
        type Self = Self;
        int_decl!($);
    );
}

impl i32 {
    int_methods!(
        type Self = i32;
        int_impl!($);
    );
}

I'm not 100% confident this'd be an overall improvement, but centralizing the docs so they can't diverge at least sounds good on paper. (Such could land separately.)

[rust-log-analyzer]

The job mingw-check failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

   Compiling compiler_builtins v0.1.109
error: unresolved link to `ilog2`
   --> library/core/src/primitive/int_macros.rs:21:15
    |
21  |         /// [`ilog2`] function which returns a consistent number, even if the type widens.
    |               ^^^^^ no item named `ilog2` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
---

error: unresolved link to `checked_add`
   --> library/core/src/primitive/int_macros.rs:86:19
    |
86  |         /// `x.`[`checked_add`]`(y).`[`unwrap_unchecked`]`()`.
    |                   ^^^^^^^^^^^ no item named `checked_add` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `unwrap_unchecked`
   --> library/core/src/primitive/int_macros.rs:86:40
    |
86  |         /// `x.`[`checked_add`]`(y).`[`unwrap_unchecked`]`()`.
    |
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
---

error: unresolved link to `wrapping_add`
   --> library/core/src/primitive/int_macros.rs:89:54
    |
89  |         /// use this.  Instead, you're looking for [`wrapping_add`].
    |                                                      ^^^^^^^^^^^^ no item named `wrapping_add` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_add`
   --> library/core/src/primitive/int_macros.rs:94:51
    |
94  |         /// `self + rhs < Self::MIN`, i.e. when [`checked_add`] would return `None`.
    |                                                   ^^^^^^^^^^^ no item named `checked_add` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_sub`
   --> library/core/src/primitive/int_macros.rs:110:19
    |
110 |         /// `x.`[`checked_sub`]`(y).`[`unwrap_unchecked`]`()`.
    |                   ^^^^^^^^^^^ no item named `checked_sub` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `unwrap_unchecked`
   --> library/core/src/primitive/int_macros.rs:110:40
    |
110 |         /// `x.`[`checked_sub`]`(y).`[`unwrap_unchecked`]`()`.
    |
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
---

error: unresolved link to `wrapping_sub`
   --> library/core/src/primitive/int_macros.rs:113:54
    |
113 |         /// use this.  Instead, you're looking for [`wrapping_sub`].
    |                                                      ^^^^^^^^^^^^ no item named `wrapping_sub` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_sub`
   --> library/core/src/primitive/int_macros.rs:118:51
    |
118 |         /// `self - rhs < Self::MIN`, i.e. when [`checked_sub`] would return `None`.
    |                                                   ^^^^^^^^^^^ no item named `checked_sub` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_mul`
   --> library/core/src/primitive/int_macros.rs:134:19
    |
134 |         /// `x.`[`checked_mul`]`(y).`[`unwrap_unchecked`]`()`.
    |                   ^^^^^^^^^^^ no item named `checked_mul` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `unwrap_unchecked`
   --> library/core/src/primitive/int_macros.rs:134:40
    |
134 |         /// `x.`[`checked_mul`]`(y).`[`unwrap_unchecked`]`()`.
    |
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
---

error: unresolved link to `wrapping_mul`
   --> library/core/src/primitive/int_macros.rs:137:54
    |
137 |         /// use this.  Instead, you're looking for [`wrapping_mul`].
    |                                                      ^^^^^^^^^^^^ no item named `wrapping_mul` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_mul`
   --> library/core/src/primitive/int_macros.rs:142:51
    |
142 |         /// `self * rhs < Self::MIN`, i.e. when [`checked_mul`] would return `None`.
    |                                                   ^^^^^^^^^^^ no item named `checked_mul` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_shl`
   --> library/core/src/primitive/int_macros.rs:200:25
    |
200 |         /// i.e. when [`checked_shl`] would return `None`.
    |                         ^^^^^^^^^^^ no item named `checked_shl` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation
    |     ----------- in this macro invocation
    |
    = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
    = note: this error originates in the macro `int_decl` (in Nightly builds, run with -Z macro-backtrace for more info)

error: unresolved link to `checked_shr`
   --> library/core/src/primitive/int_macros.rs:218:25
    |
218 |         /// i.e. when [`checked_shr`] would return `None`.
    |                         ^^^^^^^^^^^ no item named `checked_shr` in scope
   ::: library/core/src/primitive/mod.rs:200:5
    |
200 |     int_decl!();
    |     ----------- in this macro invocation

[CAD97]

Closing this as the ACP seems unlikely to be accepted.