Repository navigation
Tracking Issue for integer extension and truncation methods #154330
Description
Feature gate: #![feature(integer_extend_truncate)]
This is a tracking issue for integer extension and truncation methods.
Public API
impl iX {
// `Target` is a signed integer with size >= Self
fn widen<Target>(self) -> Target
where Self: WidenTarget<Target>;
// `Target` is a signed integer with size <= Self
fn truncate<Target>(self) -> Target
where Self: TruncateTarget<Target>;
fn saturating_truncate<Target>(self) -> Target
where Self: TruncateTarget<Target>;
fn checked_truncate<Target>(self) -> Option<Target>
where Self: TruncateTarget<Target>;
}
impl uX {
// `Target` is an unsigned integer with size >= Self
fn widen<Target>(self) -> Target
where Self: WidenTarget<Target>;
// `Target` is an unsigned integer with size <= Self
fn truncate<Target>(self) -> Target
where Self: TruncateTarget<Target>;
fn saturating_truncate<Target>(self) -> Target
where Self: TruncateTarget<Target>;
fn checked_truncate<Target>(self) -> Option<Target>
where Self: TruncateTarget<Target>;
}Steps / History
(Remember to update the S-tracking-* label when checking boxes.)
- ACP: Integer Manipulation API libs-team#204
- Implementation: Add integer truncation and extension methods #154356
- Final comment period (FCP)1
- Stabilization PR
Unresolved Questions
- None yet.
Activity
jhpratt commentedon Mar 24, 2026
Amanieu commentedon Mar 24, 2026
jhpratt commentedon Mar 24, 2026
tgross35 commentedon Mar 24, 2026
Is there any reason not to include widening unsigned->signed conversions as part of
ExtendTarget? E.g.u8toi16is lossless.joshtriplett commentedon Mar 24, 2026
We discussed this in the @rust-lang/libs-api meeting, and felt that either code should write these as separate conversions (e.g.
.extend().cast_signed()) or use.into()which already provides "conversion via multiple operations at once".jhpratt commentedon Mar 24, 2026
Not doing so ensures the methods serve exactly one purpose. It's trivial to chain that and
.cast_signed()(already stable) in that situation. Imo it's more explicit about what is happening.Last I checked,
timeis the only code base usingnum-conv, so check that out if you want to see real world code. Otherwise it's just examples, realistically.joshtriplett commentedon Mar 24, 2026
jhpratt commentedon Mar 24, 2026
joshtriplett commentedon Mar 24, 2026
jhpratt commentedon Mar 24, 2026
joshtriplett commentedon Mar 24, 2026
jhpratt commentedon Mar 24, 2026
13 remaining items
joshtriplett commentedon May 4, 2026
@Qelxiros That would be nice, with clippy's usual mechanism for only issuing such lints if your MSRV allows it.
bjoernager commentedon May 4, 2026
Has the name
widenbeen discussed instead ofextend? Keeping in mindwidening_mulhaving similar functionality (now that it's to return a wider integer.)joshtriplett commentedon May 7, 2026
@bjoernager That's a really good thought.
widenwould be more consistent, and would avoid conflicts with the meaning ofextendin collections. Big 👍 to changing that. Nominating to discuss.joshtriplett commentedon May 8, 2026
#156298
Amanieu commentedon May 12, 2026
If we adopt
widenthen for symmetry we should also rename the truncating operations to narrow. Proposed names:truncating_narrowsaturating_narrowchecked_narrowAnd possibly even an
unchecked_narrowwhich is UB if the original value doesn't fit in the narrowed type.SimonSapin commentedon May 12, 2026
is there any architecture with instructions for
unchecked_narrowwith some advantage overtruncating_narrow?Qelxiros commentedon May 12, 2026
I'd guess that
truncating_narrowis a bitmask of some sort, while the caller ofunchecked_narrowmust guarantee that value already fits in the smaller size, so it can be a no-op (assuming the value lives in a register at that program point). I'm not 100% sure though.programmerjake commentedon May 12, 2026
unchecked_narrowimproves optimizations since it tells LLVM the input is in range so if LLVM needs to widen the values to fit in registers it needs no explicit conversion and probably other optimizations too.jhpratt commentedon May 18, 2026
Updated
num-convwithwiden. I'm also now subscribed to this issue since apparently I wasn't before.asquared31415 commentedon May 26, 2026
"truncate" and "extend" are well known terms that have been used for decades to describe this specific operation, is there a reason that the libs team prefers the new names?
joshtriplett commentedon Jul 28, 2026
@asquared31415 One reason is that we already have
extendmethods in the standard library that means something else (adding items to a collection).