Skip to content

Commit 6166929

Browse files
borsbors
committed
Auto merge of rust-lang#85703 - clarfonthey:unchecked_shift, r=scottmcm
Add inherent unchecked_shl, unchecked_shr to integers Tracking issue: rust-lang#85122. Adding more of these methods, since these are missing.
2 parents 4664725 + 2a40f24 commit 6166929

File tree

2 files changed

+154
-12
lines changed

2 files changed

+154
-12
lines changed

‎library/core/src/num/int_macros.rs

+77-6
Original file line numberDiff line numberDiff line change
@@ -407,8 +407,15 @@ macro_rules! int_impl {
407407
}
408408

409409
/// Unchecked integer addition. Computes `self + rhs`, assuming overflow
410-
/// cannot occur. This results in undefined behavior when
411-
#[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`.")]
410+
/// cannot occur.
411+
///
412+
/// # Safety
413+
///
414+
/// This results in undefined behavior when
415+
#[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")]
416+
/// i.e. when [`checked_add`] would return `None`.
417+
///
418+
#[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")]
412419
#[unstable(
413420
feature = "unchecked_math",
414421
reason = "niche optimization path",
@@ -446,8 +453,15 @@ macro_rules! int_impl {
446453
}
447454

448455
/// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
449-
/// cannot occur. This results in undefined behavior when
450-
#[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`.")]
456+
/// cannot occur.
457+
///
458+
/// # Safety
459+
///
460+
/// This results in undefined behavior when
461+
#[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")]
462+
/// i.e. when [`checked_sub`] would return `None`.
463+
///
464+
#[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")]
451465
#[unstable(
452466
feature = "unchecked_math",
453467
reason = "niche optimization path",
@@ -485,8 +499,15 @@ macro_rules! int_impl {
485499
}
486500

487501
/// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow
488-
/// cannot occur. This results in undefined behavior when
489-
#[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`.")]
502+
/// cannot occur.
503+
///
504+
/// # Safety
505+
///
506+
/// This results in undefined behavior when
507+
#[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")]
508+
/// i.e. when [`checked_mul`] would return `None`.
509+
///
510+
#[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")]
490511
#[unstable(
491512
feature = "unchecked_math",
492513
reason = "niche optimization path",
@@ -645,6 +666,31 @@ macro_rules! int_impl {
645666
if unlikely!(b) {None} else {Some(a)}
646667
}
647668

669+
/// Unchecked shift left. Computes `self << rhs`, assuming that
670+
/// `rhs` is less than the number of bits in `self`.
671+
///
672+
/// # Safety
673+
///
674+
/// This results in undefined behavior if `rhs` is larger than
675+
/// or equal to the number of bits in `self`,
676+
/// i.e. when [`checked_shl`] would return `None`.
677+
///
678+
#[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
679+
#[unstable(
680+
feature = "unchecked_math",
681+
reason = "niche optimization path",
682+
issue = "85122",
683+
)]
684+
#[must_use = "this returns the result of the operation, \
685+
without modifying the original"]
686+
#[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
687+
#[inline(always)]
688+
pub const unsafe fn unchecked_shl(self, rhs: Self) -> Self {
689+
// SAFETY: the caller must uphold the safety contract for
690+
// `unchecked_shl`.
691+
unsafe { intrinsics::unchecked_shl(self, rhs) }
692+
}
693+
648694
/// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is
649695
/// larger than or equal to the number of bits in `self`.
650696
///
@@ -666,6 +712,31 @@ macro_rules! int_impl {
666712
if unlikely!(b) {None} else {Some(a)}
667713
}
668714

715+
/// Unchecked shift right. Computes `self >> rhs`, assuming that
716+
/// `rhs` is less than the number of bits in `self`.
717+
///
718+
/// # Safety
719+
///
720+
/// This results in undefined behavior if `rhs` is larger than
721+
/// or equal to the number of bits in `self`,
722+
/// i.e. when [`checked_shr`] would return `None`.
723+
///
724+
#[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
725+
#[unstable(
726+
feature = "unchecked_math",
727+
reason = "niche optimization path",
728+
issue = "85122",
729+
)]
730+
#[must_use = "this returns the result of the operation, \
731+
without modifying the original"]
732+
#[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
733+
#[inline(always)]
734+
pub const unsafe fn unchecked_shr(self, rhs: Self) -> Self {
735+
// SAFETY: the caller must uphold the safety contract for
736+
// `unchecked_shr`.
737+
unsafe { intrinsics::unchecked_shr(self, rhs) }
738+
}
739+
669740
/// Checked absolute value. Computes `self.abs()`, returning `None` if
670741
/// `self == MIN`.
671742
///

‎library/core/src/num/uint_macros.rs

+77-6
Original file line numberDiff line numberDiff line change
@@ -417,8 +417,15 @@ macro_rules! uint_impl {
417417
}
418418

419419
/// Unchecked integer addition. Computes `self + rhs`, assuming overflow
420-
/// cannot occur. This results in undefined behavior when
421-
#[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`.")]
420+
/// cannot occur.
421+
///
422+
/// # Safety
423+
///
424+
/// This results in undefined behavior when
425+
#[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")]
426+
/// i.e. when [`checked_add`] would return `None`.
427+
///
428+
#[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")]
422429
#[unstable(
423430
feature = "unchecked_math",
424431
reason = "niche optimization path",
@@ -456,8 +463,15 @@ macro_rules! uint_impl {
456463
}
457464

458465
/// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
459-
/// cannot occur. This results in undefined behavior when
460-
#[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`.")]
466+
/// cannot occur.
467+
///
468+
/// # Safety
469+
///
470+
/// This results in undefined behavior when
471+
#[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")]
472+
/// i.e. when [`checked_sub`] would return `None`.
473+
///
474+
#[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")]
461475
#[unstable(
462476
feature = "unchecked_math",
463477
reason = "niche optimization path",
@@ -495,8 +509,15 @@ macro_rules! uint_impl {
495509
}
496510

497511
/// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow
498-
/// cannot occur. This results in undefined behavior when
499-
#[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`.")]
512+
/// cannot occur.
513+
///
514+
/// # Safety
515+
///
516+
/// This results in undefined behavior when
517+
#[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")]
518+
/// i.e. when [`checked_mul`] would return `None`.
519+
///
520+
#[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")]
500521
#[unstable(
501522
feature = "unchecked_math",
502523
reason = "niche optimization path",
@@ -655,6 +676,31 @@ macro_rules! uint_impl {
655676
if unlikely!(b) {None} else {Some(a)}
656677
}
657678

679+
/// Unchecked shift left. Computes `self << rhs`, assuming that
680+
/// `rhs` is less than the number of bits in `self`.
681+
///
682+
/// # Safety
683+
///
684+
/// This results in undefined behavior if `rhs` is larger than
685+
/// or equal to the number of bits in `self`,
686+
/// i.e. when [`checked_shl`] would return `None`.
687+
///
688+
#[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
689+
#[unstable(
690+
feature = "unchecked_math",
691+
reason = "niche optimization path",
692+
issue = "85122",
693+
)]
694+
#[must_use = "this returns the result of the operation, \
695+
without modifying the original"]
696+
#[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
697+
#[inline(always)]
698+
pub const unsafe fn unchecked_shl(self, rhs: Self) -> Self {
699+
// SAFETY: the caller must uphold the safety contract for
700+
// `unchecked_shl`.
701+
unsafe { intrinsics::unchecked_shl(self, rhs) }
702+
}
703+
658704
/// Checked shift right. Computes `self >> rhs`, returning `None`
659705
/// if `rhs` is larger than or equal to the number of bits in `self`.
660706
///
@@ -676,6 +722,31 @@ macro_rules! uint_impl {
676722
if unlikely!(b) {None} else {Some(a)}
677723
}
678724

725+
/// Unchecked shift right. Computes `self >> rhs`, assuming that
726+
/// `rhs` is less than the number of bits in `self`.
727+
///
728+
/// # Safety
729+
///
730+
/// This results in undefined behavior if `rhs` is larger than
731+
/// or equal to the number of bits in `self`,
732+
/// i.e. when [`checked_shr`] would return `None`.
733+
///
734+
#[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
735+
#[unstable(
736+
feature = "unchecked_math",
737+
reason = "niche optimization path",
738+
issue = "85122",
739+
)]
740+
#[must_use = "this returns the result of the operation, \
741+
without modifying the original"]
742+
#[rustc_const_unstable(feature = "const_inherent_unchecked_arith", issue = "85122")]
743+
#[inline(always)]
744+
pub const unsafe fn unchecked_shr(self, rhs: Self) -> Self {
745+
// SAFETY: the caller must uphold the safety contract for
746+
// `unchecked_shr`.
747+
unsafe { intrinsics::unchecked_shr(self, rhs) }
748+
}
749+
679750
/// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
680751
/// overflow occurred.
681752
///

0 commit comments

Comments
 (0)