uint_macros.rs source code [crates/core/src/num/uint_macros.rs]

1	macro_rules! uint_impl {
2	(
3	Self = $SelfT:ty,
4	ActualT = $ActualT:ident,
5	SignedT = $SignedT:ident,
6	NonZeroT = $NonZeroT:ty,
7
8	// There are all for use only* in doc comments.*
9	// As such, they're all passed as literals -- passing them as a string
10	// literal is fine if they need to be multiple code tokens.
11	// In non-comments, use the associated constants rather than these.
12	BITS = $BITS:literal,
13	MAX = $MaxV:literal,
14	rot = $rot:literal,
15	rot_op = $rot_op:literal,
16	rot_result = $rot_result:literal,
17	swap_op = $swap_op:literal,
18	swapped = $swapped:literal,
19	reversed = $reversed:literal,
20	le_bytes = $le_bytes:literal,
21	be_bytes = $be_bytes:literal,
22	to_xe_bytes_doc = $to_xe_bytes_doc:expr,
23	from_xe_bytes_doc = $from_xe_bytes_doc:expr,
24	bound_condition = $bound_condition:literal,
25	) => {
26	/// The smallest value that can be represented by this integer type.
27	///
28	/// # Examples
29	///
30	/// Basic usage:
31	///
32	/// ```
33	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, 0);")]
34	/// ```
35	#[stable(feature = "assoc_int_consts", since = "1.43.0")]
36	pub const MIN: Self = `0`;
37
38	/// The largest value that can be represented by this integer type
39	#[doc = concat!("(2<sup>", $BITS, "</sup> − 1", $bound_condition, ").")]
40	///
41	/// # Examples
42	///
43	/// Basic usage:
44	///
45	/// ```
46	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($MaxV), ");")]
47	/// ```
48	#[stable(feature = "assoc_int_consts", since = "1.43.0")]
49	pub const MAX: Self = !`0`;
50
51	/// The size of this integer type in bits.
52	///
53	/// # Examples
54	///
55	/// ```
56	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")]
57	/// ```
58	#[stable(feature = "int_bits_const", since = "1.53.0")]
59	pub const BITS: u32 = Self::MAX.count_ones();
60
61	/// Converts a string slice in a given base to an integer.
62	///
63	/// The string is expected to be an optional `+` sign
64	/// followed by digits.
65	/// Leading and trailing whitespace represent an error.
66	/// Digits are a subset of these characters, depending on `radix`:
67	///
68	/// `0-9`*
69	/// `a-z`*
70	/// `A-Z`*
71	///
72	/// # Panics
73	///
74	/// This function panics if `radix` is not in the range from 2 to 36.
75	///
76	/// # Examples
77	///
78	/// Basic usage:
79	///
80	/// ```
81	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::from_str_radix(`\"`A`\"`, 16), Ok(10));")]
82	/// ```
83	#[stable(feature = "rust1", since = "1.0.0")]
84	pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> {
85	from_str_radix(src, radix)
86	}
87
88	/// Returns the number of ones in the binary representation of `self`.
89	///
90	/// # Examples
91	///
92	/// Basic usage:
93	///
94	/// ```
95	#[doc = concat!("let n = 0b01001100", stringify!($SelfT), ";")]
96	///
97	/// assert_eq!(n.count_ones(), 3);
98	/// ```
99	#[stable(feature = "rust1", since = "1.0.0")]
100	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
101	#[doc(alias = "popcount")]
102	#[doc(alias = "popcnt")]
103	#[must_use = "this returns the result of the operation, \
104	without modifying the original"]
105	#[inline(always)]
106	pub const fn count_ones(self) -> u32 {
107	intrinsics::ctpop(self as $ActualT) as u32
108	}
109
110	/// Returns the number of zeros in the binary representation of `self`.
111	///
112	/// # Examples
113	///
114	/// Basic usage:
115	///
116	/// ```
117	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 0);")]
118	/// ```
119	#[stable(feature = "rust1", since = "1.0.0")]
120	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
121	#[must_use = "this returns the result of the operation, \
122	without modifying the original"]
123	#[inline(always)]
124	pub const fn count_zeros(self) -> u32 {
125	(!self).count_ones()
126	}
127
128	/// Returns the number of leading zeros in the binary representation of `self`.
129	///
130	/// Depending on what you're doing with the value, you might also be interested in the
131	/// [`ilog2`] function which returns a consistent number, even if the type widens.
132	///
133	/// # Examples
134	///
135	/// Basic usage:
136	///
137	/// ```
138	#[doc = concat!("let n = ", stringify!($SelfT), "::MAX >> 2;")]
139	///
140	/// assert_eq!(n.leading_zeros(), 2);
141	/// ```
142	#[doc = concat!("[`ilog2`]: ", stringify!($SelfT), "::ilog2")]
143	#[stable(feature = "rust1", since = "1.0.0")]
144	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
145	#[must_use = "this returns the result of the operation, \
146	without modifying the original"]
147	#[inline(always)]
148	pub const fn leading_zeros(self) -> u32 {
149	intrinsics::ctlz(self as $ActualT) as u32
150	}
151
152	/// Returns the number of trailing zeros in the binary representation
153	/// of `self`.
154	///
155	/// # Examples
156	///
157	/// Basic usage:
158	///
159	/// ```
160	#[doc = concat!("let n = 0b0101000", stringify!($SelfT), ";")]
161	///
162	/// assert_eq!(n.trailing_zeros(), 3);
163	/// ```
164	#[stable(feature = "rust1", since = "1.0.0")]
165	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
166	#[must_use = "this returns the result of the operation, \
167	without modifying the original"]
168	#[inline(always)]
169	pub const fn trailing_zeros(self) -> u32 {
170	intrinsics::cttz(self) as u32
171	}
172
173	/// Returns the number of leading ones in the binary representation of `self`.
174	///
175	/// # Examples
176	///
177	/// Basic usage:
178	///
179	/// ```
180	#[doc = concat!("let n = !(", stringify!($SelfT), "::MAX >> 2);")]
181	///
182	/// assert_eq!(n.leading_ones(), 2);
183	/// ```
184	#[stable(feature = "leading_trailing_ones", since = "1.46.0")]
185	#[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
186	#[must_use = "this returns the result of the operation, \
187	without modifying the original"]
188	#[inline(always)]
189	pub const fn leading_ones(self) -> u32 {
190	(!self).leading_zeros()
191	}
192
193	/// Returns the number of trailing ones in the binary representation
194	/// of `self`.
195	///
196	/// # Examples
197	///
198	/// Basic usage:
199	///
200	/// ```
201	#[doc = concat!("let n = 0b1010111", stringify!($SelfT), ";")]
202	///
203	/// assert_eq!(n.trailing_ones(), 3);
204	/// ```
205	#[stable(feature = "leading_trailing_ones", since = "1.46.0")]
206	#[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")]
207	#[must_use = "this returns the result of the operation, \
208	without modifying the original"]
209	#[inline(always)]
210	pub const fn trailing_ones(self) -> u32 {
211	(!self).trailing_zeros()
212	}
213
214	/// Shifts the bits to the left by a specified amount, `n`,
215	/// wrapping the truncated bits to the end of the resulting integer.
216	///
217	/// Please note this isn't the same operation as the `<<` shifting operator!
218	///
219	/// # Examples
220	///
221	/// Basic usage:
222	///
223	/// ```
224	#[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")]
225	#[doc = concat!("let m = ", $rot_result, ";")]
226	///
227	#[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")]
228	/// ```
229	#[stable(feature = "rust1", since = "1.0.0")]
230	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
231	#[must_use = "this returns the result of the operation, \
232	without modifying the original"]
233	#[inline(always)]
234	pub const fn rotate_left(self, n: u32) -> Self {
235	intrinsics::rotate_left(self, n as $SelfT)
236	}
237
238	/// Shifts the bits to the right by a specified amount, `n`,
239	/// wrapping the truncated bits to the beginning of the resulting
240	/// integer.
241	///
242	/// Please note this isn't the same operation as the `>>` shifting operator!
243	///
244	/// # Examples
245	///
246	/// Basic usage:
247	///
248	/// ```
249	#[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")]
250	#[doc = concat!("let m = ", $rot_op, ";")]
251	///
252	#[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")]
253	/// ```
254	#[stable(feature = "rust1", since = "1.0.0")]
255	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
256	#[must_use = "this returns the result of the operation, \
257	without modifying the original"]
258	#[inline(always)]
259	pub const fn rotate_right(self, n: u32) -> Self {
260	intrinsics::rotate_right(self, n as $SelfT)
261	}
262
263	/// Reverses the byte order of the integer.
264	///
265	/// # Examples
266	///
267	/// Basic usage:
268	///
269	/// ```
270	#[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
271	/// let m = n.swap_bytes();
272	///
273	#[doc = concat!("assert_eq!(m, ", $swapped, ");")]
274	/// ```
275	#[stable(feature = "rust1", since = "1.0.0")]
276	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
277	#[must_use = "this returns the result of the operation, \
278	without modifying the original"]
279	#[inline(always)]
280	pub const fn swap_bytes(self) -> Self {
281	intrinsics::bswap(self as $ActualT) as Self
282	}
283
284	/// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit,
285	/// second least-significant bit becomes second most-significant bit, etc.
286	///
287	/// # Examples
288	///
289	/// Basic usage:
290	///
291	/// ```
292	#[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")]
293	/// let m = n.reverse_bits();
294	///
295	#[doc = concat!("assert_eq!(m, ", $reversed, ");")]
296	#[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")]
297	/// ```
298	#[stable(feature = "reverse_bits", since = "1.37.0")]
299	#[rustc_const_stable(feature = "reverse_bits", since = "1.37.0")]
300	#[must_use = "this returns the result of the operation, \
301	without modifying the original"]
302	#[inline(always)]
303	pub const fn reverse_bits(self) -> Self {
304	intrinsics::bitreverse(self as $ActualT) as Self
305	}
306
307	/// Converts an integer from big endian to the target's endianness.
308	///
309	/// On big endian this is a no-op. On little endian the bytes are
310	/// swapped.
311	///
312	/// # Examples
313	///
314	/// Basic usage:
315	///
316	/// ```
317	#[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
318	///
319	/// if cfg!(target_endian = "big") {
320	#[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n)")]
321	/// } else {
322	#[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")]
323	/// }
324	/// ```
325	#[stable(feature = "rust1", since = "1.0.0")]
326	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
327	#[must_use]
328	#[inline(always)]
329	pub const fn from_be(x: Self) -> Self {
330	#[cfg(target_endian = "big")]
331	{
332	x
333	}
334	#[cfg(not(target_endian = "big"))]
335	{
336	x.swap_bytes()
337	}
338	}
339
340	/// Converts an integer from little endian to the target's endianness.
341	///
342	/// On little endian this is a no-op. On big endian the bytes are
343	/// swapped.
344	///
345	/// # Examples
346	///
347	/// Basic usage:
348	///
349	/// ```
350	#[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
351	///
352	/// if cfg!(target_endian = "little") {
353	#[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n)")]
354	/// } else {
355	#[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")]
356	/// }
357	/// ```
358	#[stable(feature = "rust1", since = "1.0.0")]
359	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
360	#[must_use]
361	#[inline(always)]
362	pub const fn from_le(x: Self) -> Self {
363	#[cfg(target_endian = "little")]
364	{
365	x
366	}
367	#[cfg(not(target_endian = "little"))]
368	{
369	x.swap_bytes()
370	}
371	}
372
373	/// Converts `self` to big endian from the target's endianness.
374	///
375	/// On big endian this is a no-op. On little endian the bytes are
376	/// swapped.
377	///
378	/// # Examples
379	///
380	/// Basic usage:
381	///
382	/// ```
383	#[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
384	///
385	/// if cfg!(target_endian = "big") {
386	/// assert_eq!(n.to_be(), n)
387	/// } else {
388	/// assert_eq!(n.to_be(), n.swap_bytes())
389	/// }
390	/// ```
391	#[stable(feature = "rust1", since = "1.0.0")]
392	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
393	#[must_use = "this returns the result of the operation, \
394	without modifying the original"]
395	#[inline(always)]
396	pub const fn to_be(self) -> Self { // or not to be?
397	#[cfg(target_endian = "big")]
398	{
399	self
400	}
401	#[cfg(not(target_endian = "big"))]
402	{
403	self.swap_bytes()
404	}
405	}
406
407	/// Converts `self` to little endian from the target's endianness.
408	///
409	/// On little endian this is a no-op. On big endian the bytes are
410	/// swapped.
411	///
412	/// # Examples
413	///
414	/// Basic usage:
415	///
416	/// ```
417	#[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")]
418	///
419	/// if cfg!(target_endian = "little") {
420	/// assert_eq!(n.to_le(), n)
421	/// } else {
422	/// assert_eq!(n.to_le(), n.swap_bytes())
423	/// }
424	/// ```
425	#[stable(feature = "rust1", since = "1.0.0")]
426	#[rustc_const_stable(feature = "const_math", since = "1.32.0")]
427	#[must_use = "this returns the result of the operation, \
428	without modifying the original"]
429	#[inline(always)]
430	pub const fn to_le(self) -> Self {
431	#[cfg(target_endian = "little")]
432	{
433	self
434	}
435	#[cfg(not(target_endian = "little"))]
436	{
437	self.swap_bytes()
438	}
439	}
440
441	/// Checked integer addition. Computes `self + rhs`, returning `None`
442	/// if overflow occurred.
443	///
444	/// # Examples
445	///
446	/// Basic usage:
447	///
448	/// ```
449	#[doc = concat!(
450	"assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), ",
451	"Some(", stringify!($SelfT), "::MAX - 1));"
452	)]
453	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")]
454	/// ```
455	#[stable(feature = "rust1", since = "1.0.0")]
456	#[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
457	#[must_use = "this returns the result of the operation, \
458	without modifying the original"]
459	#[inline]
460	pub const fn checked_add(self, rhs: Self) -> Option<Self> {
461	let (a, b) = self.overflowing_add(rhs);
462	if unlikely!(b) { None } else { Some(a) }
463	}
464
465	/// Strict integer addition. Computes `self + rhs`, panicking
466	/// if overflow occurred.
467	///
468	/// # Panics
469	///
470	/// ## Overflow behavior
471	///
472	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
473	///
474	/// # Examples
475	///
476	/// Basic usage:
477	///
478	/// ```
479	/// #![feature(strict_overflow_ops)]
480	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")]
481	/// ```
482	///
483	/// ```should_panic
484	/// #![feature(strict_overflow_ops)]
485	#[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")]
486	/// ```
487	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
488	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
489	#[must_use = "this returns the result of the operation, \
490	without modifying the original"]
491	#[inline]
492	#[track_caller]
493	pub const fn strict_add(self, rhs: Self) -> Self {
494	let (a, b) = self.overflowing_add(rhs);
495	if unlikely!(b) { overflow_panic ::add()} else {a}
496	}
497
498	/// Unchecked integer addition. Computes `self + rhs`, assuming overflow
499	/// cannot occur.
500	///
501	/// # Safety
502	///
503	/// This results in undefined behavior when
504	#[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")]
505	/// i.e. when [`checked_add`] would return `None`.
506	///
507	#[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")]
508	#[unstable(
509	feature = "unchecked_math",
510	reason = "niche optimization path",
511	issue = "85122",
512	)]
513	#[must_use = "this returns the result of the operation, \
514	without modifying the original"]
515	#[rustc_const_unstable(feature = "unchecked_math", issue = "85122")]
516	#[inline(always)]
517	#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
518	pub const unsafe fn unchecked_add(self, rhs: Self) -> Self {
519	// SAFETY: the caller must uphold the safety contract for
520	// `unchecked_add`.
521	unsafe { intrinsics::unchecked_add(self, rhs) }
522	}
523
524	/// Checked addition with a signed integer. Computes `self + rhs`,
525	/// returning `None` if overflow occurred.
526	///
527	/// # Examples
528	///
529	/// Basic usage:
530	///
531	/// ```
532	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_signed(2), Some(3));")]
533	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_signed(-2), None);")]
534	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add_signed(3), None);")]
535	/// ```
536	#[stable(feature = "mixed_integer_ops", since = "1.66.0")]
537	#[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
538	#[must_use = "this returns the result of the operation, \
539	without modifying the original"]
540	#[inline]
541	pub const fn checked_add_signed(self, rhs: $SignedT) -> Option<Self> {
542	let (a, b) = self.overflowing_add_signed(rhs);
543	if unlikely!(b) { None } else { Some(a) }
544	}
545
546	/// Strict addition with a signed integer. Computes `self + rhs`,
547	/// panicking if overflow occurred.
548	///
549	/// # Panics
550	///
551	/// ## Overflow behavior
552	///
553	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
554	///
555	/// # Examples
556	///
557	/// Basic usage:
558	///
559	/// ```
560	/// #![feature(strict_overflow_ops)]
561	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_signed(2), 3);")]
562	/// ```
563	///
564	/// ```should_panic
565	/// #![feature(strict_overflow_ops)]
566	#[doc = concat!("let _ = 1", stringify!($SelfT), ".strict_add_signed(-2);")]
567	/// ```
568	///
569	/// ```should_panic
570	/// #![feature(strict_overflow_ops)]
571	#[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add_signed(3);")]
572	/// ```
573	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
574	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
575	#[must_use = "this returns the result of the operation, \
576	without modifying the original"]
577	#[inline]
578	#[track_caller]
579	pub const fn strict_add_signed(self, rhs: $SignedT) -> Self {
580	let (a, b) = self.overflowing_add_signed(rhs);
581	if unlikely!(b) { overflow_panic ::add()} else {a}
582	}
583
584	/// Checked integer subtraction. Computes `self - rhs`, returning
585	/// `None` if overflow occurred.
586	///
587	/// # Examples
588	///
589	/// Basic usage:
590	///
591	/// ```
592	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_sub(1), Some(0));")]
593	#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".checked_sub(1), None);")]
594	/// ```
595	#[stable(feature = "rust1", since = "1.0.0")]
596	#[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
597	#[must_use = "this returns the result of the operation, \
598	without modifying the original"]
599	#[inline]
600	pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
601	let (a, b) = self.overflowing_sub(rhs);
602	if unlikely!(b) { None } else { Some(a) }
603	}
604
605	/// Strict integer subtraction. Computes `self - rhs`, panicking if
606	/// overflow occurred.
607	///
608	/// # Panics
609	///
610	/// ## Overflow behavior
611	///
612	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
613	///
614	/// # Examples
615	///
616	/// Basic usage:
617	///
618	/// ```
619	/// #![feature(strict_overflow_ops)]
620	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub(1), 0);")]
621	/// ```
622	///
623	/// ```should_panic
624	/// #![feature(strict_overflow_ops)]
625	#[doc = concat!("let _ = 0", stringify!($SelfT), ".strict_sub(1);")]
626	/// ```
627	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
628	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
629	#[must_use = "this returns the result of the operation, \
630	without modifying the original"]
631	#[inline]
632	#[track_caller]
633	pub const fn strict_sub(self, rhs: Self) -> Self {
634	let (a, b) = self.overflowing_sub(rhs);
635	if unlikely!(b) { overflow_panic ::sub()} else {a}
636	}
637
638	/// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow
639	/// cannot occur.
640	///
641	/// # Safety
642	///
643	/// This results in undefined behavior when
644	#[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")]
645	/// i.e. when [`checked_sub`] would return `None`.
646	///
647	#[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")]
648	#[unstable(
649	feature = "unchecked_math",
650	reason = "niche optimization path",
651	issue = "85122",
652	)]
653	#[must_use = "this returns the result of the operation, \
654	without modifying the original"]
655	#[rustc_const_unstable(feature = "unchecked_math", issue = "85122")]
656	#[inline(always)]
657	#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
658	pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self {
659	// SAFETY: the caller must uphold the safety contract for
660	// `unchecked_sub`.
661	unsafe { intrinsics::unchecked_sub(self, rhs) }
662	}
663
664	/// Checked integer multiplication. Computes `self rhs`, returning*
665	/// `None` if overflow occurred.
666	///
667	/// # Examples
668	///
669	/// Basic usage:
670	///
671	/// ```
672	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_mul(1), Some(5));")]
673	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")]
674	/// ```
675	#[stable(feature = "rust1", since = "1.0.0")]
676	#[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
677	#[must_use = "this returns the result of the operation, \
678	without modifying the original"]
679	#[inline]
680	pub const fn checked_mul(self, rhs: Self) -> Option<Self> {
681	let (a, b) = self.overflowing_mul(rhs);
682	if unlikely!(b) { None } else { Some(a) }
683	}
684
685	/// Strict integer multiplication. Computes `self rhs`, panicking if*
686	/// overflow occurred.
687	///
688	/// # Panics
689	///
690	/// ## Overflow behavior
691	///
692	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
693	///
694	/// # Examples
695	///
696	/// Basic usage:
697	///
698	/// ```
699	/// #![feature(strict_overflow_ops)]
700	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_mul(1), 5);")]
701	/// ```
702	///
703	/// ``` should_panic
704	/// #![feature(strict_overflow_ops)]
705	#[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")]
706	/// ```
707	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
708	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
709	#[must_use = "this returns the result of the operation, \
710	without modifying the original"]
711	#[inline]
712	#[track_caller]
713	pub const fn strict_mul(self, rhs: Self) -> Self {
714	let (a, b) = self.overflowing_mul(rhs);
715	if unlikely!(b) { overflow_panic ::mul()} else {a}
716	}
717
718	/// Unchecked integer multiplication. Computes `self rhs`, assuming overflow*
719	/// cannot occur.
720	///
721	/// # Safety
722	///
723	/// This results in undefined behavior when
724	#[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")]
725	/// i.e. when [`checked_mul`] would return `None`.
726	///
727	#[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")]
728	#[unstable(
729	feature = "unchecked_math",
730	reason = "niche optimization path",
731	issue = "85122",
732	)]
733	#[must_use = "this returns the result of the operation, \
734	without modifying the original"]
735	#[rustc_const_unstable(feature = "unchecked_math", issue = "85122")]
736	#[inline(always)]
737	#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
738	pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self {
739	// SAFETY: the caller must uphold the safety contract for
740	// `unchecked_mul`.
741	unsafe { intrinsics::unchecked_mul(self, rhs) }
742	}
743
744	/// Checked integer division. Computes `self / rhs`, returning `None`
745	/// if `rhs == 0`.
746	///
747	/// # Examples
748	///
749	/// Basic usage:
750	///
751	/// ```
752	#[doc = concat!("assert_eq!(128", stringify!($SelfT), ".checked_div(2), Some(64));")]
753	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_div(0), None);")]
754	/// ```
755	#[stable(feature = "rust1", since = "1.0.0")]
756	#[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
757	#[must_use = "this returns the result of the operation, \
758	without modifying the original"]
759	#[inline]
760	pub const fn checked_div(self, rhs: Self) -> Option<Self> {
761	if unlikely!(rhs == `0`) {
762	None
763	} else {
764	// SAFETY: div by zero has been checked above and unsigned types have no other
765	// failure modes for division
766	Some(unsafe { intrinsics::unchecked_div(self, rhs) })
767	}
768	}
769
770	/// Strict integer division. Computes `self / rhs`.
771	/// Strict division on unsigned types is just normal division.
772	/// There's no way overflow could ever happen.
773	/// This function exists, so that all operations
774	/// are accounted for in the strict operations.
775	///
776	/// # Panics
777	///
778	/// This function will panic if `rhs` is zero.
779	///
780	/// # Examples
781	///
782	/// Basic usage:
783	///
784	/// ```
785	/// #![feature(strict_overflow_ops)]
786	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_div(10), 10);")]
787	/// ```
788	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
789	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
790	#[must_use = "this returns the result of the operation, \
791	without modifying the original"]
792	#[inline(always)]
793	#[track_caller]
794	pub const fn strict_div(self, rhs: Self) -> Self {
795	self / rhs
796	}
797
798	/// Checked Euclidean division. Computes `self.div_euclid(rhs)`, returning `None`
799	/// if `rhs == 0`.
800	///
801	/// # Examples
802	///
803	/// Basic usage:
804	///
805	/// ```
806	#[doc = concat!("assert_eq!(128", stringify!($SelfT), ".checked_div_euclid(2), Some(64));")]
807	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_div_euclid(0), None);")]
808	/// ```
809	#[stable(feature = "euclidean_division", since = "1.38.0")]
810	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
811	#[must_use = "this returns the result of the operation, \
812	without modifying the original"]
813	#[inline]
814	pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> {
815	if unlikely!(rhs == `0`) {
816	None
817	} else {
818	Some(self.div_euclid(rhs))
819	}
820	}
821
822	/// Strict Euclidean division. Computes `self.div_euclid(rhs)`.
823	/// Strict division on unsigned types is just normal division.
824	/// There's no way overflow could ever happen.
825	/// This function exists, so that all operations
826	/// are accounted for in the strict operations.
827	/// Since, for the positive integers, all common
828	/// definitions of division are equal, this
829	/// is exactly equal to `self.strict_div(rhs)`.
830	///
831	/// # Panics
832	///
833	/// This function will panic if `rhs` is zero.
834	///
835	/// # Examples
836	///
837	/// Basic usage:
838	///
839	/// ```
840	/// #![feature(strict_overflow_ops)]
841	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_div_euclid(10), 10);")]
842	/// ```
843	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
844	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
845	#[must_use = "this returns the result of the operation, \
846	without modifying the original"]
847	#[inline(always)]
848	#[track_caller]
849	pub const fn strict_div_euclid(self, rhs: Self) -> Self {
850	self / rhs
851	}
852
853	/// Checked integer remainder. Computes `self % rhs`, returning `None`
854	/// if `rhs == 0`.
855	///
856	/// # Examples
857	///
858	/// Basic usage:
859	///
860	/// ```
861	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")]
862	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")]
863	/// ```
864	#[stable(feature = "wrapping", since = "1.7.0")]
865	#[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")]
866	#[must_use = "this returns the result of the operation, \
867	without modifying the original"]
868	#[inline]
869	pub const fn checked_rem(self, rhs: Self) -> Option<Self> {
870	if unlikely!(rhs == `0`) {
871	None
872	} else {
873	// SAFETY: div by zero has been checked above and unsigned types have no other
874	// failure modes for division
875	Some(unsafe { intrinsics::unchecked_rem(self, rhs) })
876	}
877	}
878
879	/// Strict integer remainder. Computes `self % rhs`.
880	/// Strict remainder calculation on unsigned types is
881	/// just the regular remainder calculation.
882	/// There's no way overflow could ever happen.
883	/// This function exists, so that all operations
884	/// are accounted for in the strict operations.
885	///
886	/// # Panics
887	///
888	/// This function will panic if `rhs` is zero.
889	///
890	/// # Examples
891	///
892	/// Basic usage:
893	///
894	/// ```
895	/// #![feature(strict_overflow_ops)]
896	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_rem(10), 0);")]
897	/// ```
898	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
899	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
900	#[must_use = "this returns the result of the operation, \
901	without modifying the original"]
902	#[inline(always)]
903	#[track_caller]
904	pub const fn strict_rem(self, rhs: Self) -> Self {
905	self % rhs
906	}
907
908	/// Checked Euclidean modulo. Computes `self.rem_euclid(rhs)`, returning `None`
909	/// if `rhs == 0`.
910	///
911	/// # Examples
912	///
913	/// Basic usage:
914	///
915	/// ```
916	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")]
917	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")]
918	/// ```
919	#[stable(feature = "euclidean_division", since = "1.38.0")]
920	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
921	#[must_use = "this returns the result of the operation, \
922	without modifying the original"]
923	#[inline]
924	pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> {
925	if unlikely!(rhs == `0`) {
926	None
927	} else {
928	Some(self.rem_euclid(rhs))
929	}
930	}
931
932	/// Strict Euclidean modulo. Computes `self.rem_euclid(rhs)`.
933	/// Strict modulo calculation on unsigned types is
934	/// just the regular remainder calculation.
935	/// There's no way overflow could ever happen.
936	/// This function exists, so that all operations
937	/// are accounted for in the strict operations.
938	/// Since, for the positive integers, all common
939	/// definitions of division are equal, this
940	/// is exactly equal to `self.strict_rem(rhs)`.
941	///
942	/// # Panics
943	///
944	/// This function will panic if `rhs` is zero.
945	///
946	/// # Examples
947	///
948	/// Basic usage:
949	///
950	/// ```
951	/// #![feature(strict_overflow_ops)]
952	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_rem_euclid(10), 0);")]
953	/// ```
954	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
955	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
956	#[must_use = "this returns the result of the operation, \
957	without modifying the original"]
958	#[inline(always)]
959	#[track_caller]
960	pub const fn strict_rem_euclid(self, rhs: Self) -> Self {
961	self % rhs
962	}
963
964	/// Returns the logarithm of the number with respect to an arbitrary base,
965	/// rounded down.
966	///
967	/// This method might not be optimized owing to implementation details;
968	/// `ilog2` can produce results more efficiently for base 2, and `ilog10`
969	/// can produce results more efficiently for base 10.
970	///
971	/// # Panics
972	///
973	/// This function will panic if `self` is zero, or if `base` is less than 2.
974	///
975	/// # Examples
976	///
977	/// ```
978	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")]
979	/// ```
980	#[stable(feature = "int_log", since = "1.67.0")]
981	#[rustc_const_stable(feature = "int_log", since = "1.67.0")]
982	#[must_use = "this returns the result of the operation, \
983	without modifying the original"]
984	#[inline]
985	#[track_caller]
986	pub const fn ilog(self, base: Self) -> u32 {
987	assert!(base >= `2`, "base of integer logarithm must be at least 2");
988	if let Some(log) = self.checked_ilog(base) {
989	log
990	} else {
991	int_log10::panic_for_nonpositive_argument()
992	}
993	}
994
995	/// Returns the base 2 logarithm of the number, rounded down.
996	///
997	/// # Panics
998	///
999	/// This function will panic if `self` is zero.
1000	///
1001	/// # Examples
1002	///
1003	/// ```
1004	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")]
1005	/// ```
1006	#[stable(feature = "int_log", since = "1.67.0")]
1007	#[rustc_const_stable(feature = "int_log", since = "1.67.0")]
1008	#[must_use = "this returns the result of the operation, \
1009	without modifying the original"]
1010	#[inline]
1011	#[track_caller]
1012	pub const fn ilog2(self) -> u32 {
1013	if let Some(log) = self.checked_ilog2() {
1014	log
1015	} else {
1016	int_log10::panic_for_nonpositive_argument()
1017	}
1018	}
1019
1020	/// Returns the base 10 logarithm of the number, rounded down.
1021	///
1022	/// # Panics
1023	///
1024	/// This function will panic if `self` is zero.
1025	///
1026	/// # Example
1027	///
1028	/// ```
1029	#[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")]
1030	/// ```
1031	#[stable(feature = "int_log", since = "1.67.0")]
1032	#[rustc_const_stable(feature = "int_log", since = "1.67.0")]
1033	#[must_use = "this returns the result of the operation, \
1034	without modifying the original"]
1035	#[inline]
1036	#[track_caller]
1037	pub const fn ilog10(self) -> u32 {
1038	if let Some(log) = self.checked_ilog10() {
1039	log
1040	} else {
1041	int_log10::panic_for_nonpositive_argument()
1042	}
1043	}
1044
1045	/// Returns the logarithm of the number with respect to an arbitrary base,
1046	/// rounded down.
1047	///
1048	/// Returns `None` if the number is zero, or if the base is not at least 2.
1049	///
1050	/// This method might not be optimized owing to implementation details;
1051	/// `checked_ilog2` can produce results more efficiently for base 2, and
1052	/// `checked_ilog10` can produce results more efficiently for base 10.
1053	///
1054	/// # Examples
1055	///
1056	/// ```
1057	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")]
1058	/// ```
1059	#[stable(feature = "int_log", since = "1.67.0")]
1060	#[rustc_const_stable(feature = "int_log", since = "1.67.0")]
1061	#[must_use = "this returns the result of the operation, \
1062	without modifying the original"]
1063	#[inline]
1064	pub const fn checked_ilog(self, base: Self) -> Option<u32> {
1065	if self <= `0` \|\| base <= `1` {
1066	None
1067	} else {
1068	let mut n = `0`;
1069	let mut r = self;
1070
1071	// Optimization for 128 bit wide integers.
1072	if Self::BITS == `128` {
1073	let b = Self::ilog2(self) / (Self::ilog2(base) + `1`);
1074	n += b;
1075	r /= base.pow(b as u32);
1076	}
1077
1078	while r >= base {
1079	r /= base;
1080	n += `1`;
1081	}
1082	Some(n)
1083	}
1084	}
1085
1086	/// Returns the base 2 logarithm of the number, rounded down.
1087	///
1088	/// Returns `None` if the number is zero.
1089	///
1090	/// # Examples
1091	///
1092	/// ```
1093	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")]
1094	/// ```
1095	#[stable(feature = "int_log", since = "1.67.0")]
1096	#[rustc_const_stable(feature = "int_log", since = "1.67.0")]
1097	#[must_use = "this returns the result of the operation, \
1098	without modifying the original"]
1099	#[inline]
1100	pub const fn checked_ilog2(self) -> Option<u32> {
1101	// FIXME: Simply use `NonZero::new` once it is actually generic.
1102	if let Some(x) = <$NonZeroT>::new(self) {
1103	Some(x.ilog2())
1104	} else {
1105	None
1106	}
1107	}
1108
1109	/// Returns the base 10 logarithm of the number, rounded down.
1110	///
1111	/// Returns `None` if the number is zero.
1112	///
1113	/// # Examples
1114	///
1115	/// ```
1116	#[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")]
1117	/// ```
1118	#[stable(feature = "int_log", since = "1.67.0")]
1119	#[rustc_const_stable(feature = "int_log", since = "1.67.0")]
1120	#[must_use = "this returns the result of the operation, \
1121	without modifying the original"]
1122	#[inline]
1123	pub const fn checked_ilog10(self) -> Option<u32> {
1124	// FIXME: Simply use `NonZero::new` once it is actually generic.
1125	if let Some(x) = <$NonZeroT>::new(self) {
1126	Some(x.ilog10())
1127	} else {
1128	None
1129	}
1130	}
1131
1132	/// Checked negation. Computes `-self`, returning `None` unless `self ==
1133	/// 0`.
1134	///
1135	/// Note that negating any positive integer will overflow.
1136	///
1137	/// # Examples
1138	///
1139	/// Basic usage:
1140	///
1141	/// ```
1142	#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".checked_neg(), Some(0));")]
1143	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_neg(), None);")]
1144	/// ```
1145	#[stable(feature = "wrapping", since = "1.7.0")]
1146	#[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1147	#[must_use = "this returns the result of the operation, \
1148	without modifying the original"]
1149	#[inline]
1150	pub const fn checked_neg(self) -> Option<Self> {
1151	let (a, b) = self.overflowing_neg();
1152	if unlikely!(b) { None } else { Some(a) }
1153	}
1154
1155	/// Strict negation. Computes `-self`, panicking unless `self ==
1156	/// 0`.
1157	///
1158	/// Note that negating any positive integer will overflow.
1159	///
1160	/// # Panics
1161	///
1162	/// ## Overflow behavior
1163	///
1164	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1165	///
1166	/// # Examples
1167	///
1168	/// Basic usage:
1169	///
1170	/// ```
1171	/// #![feature(strict_overflow_ops)]
1172	#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".strict_neg(), 0);")]
1173	/// ```
1174	///
1175	/// ```should_panic
1176	/// #![feature(strict_overflow_ops)]
1177	#[doc = concat!("let _ = 1", stringify!($SelfT), ".strict_neg();")]
1178	///
1179	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
1180	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
1181	#[must_use = "this returns the result of the operation, \
1182	without modifying the original"]
1183	#[inline]
1184	#[track_caller]
1185	pub const fn strict_neg(self) -> Self {
1186	let (a, b) = self.overflowing_neg();
1187	if unlikely!(b) { overflow_panic::neg() } else { a }
1188	}
1189
1190	/// Checked shift left. Computes `self << rhs`, returning `None`
1191	/// if `rhs` is larger than or equal to the number of bits in `self`.
1192	///
1193	/// # Examples
1194	///
1195	/// Basic usage:
1196	///
1197	/// ```
1198	#[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")]
1199	#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);")]
1200	/// ```
1201	#[stable(feature = "wrapping", since = "1.7.0")]
1202	#[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1203	#[must_use = "this returns the result of the operation, \
1204	without modifying the original"]
1205	#[inline]
1206	pub const fn checked_shl(self, rhs: u32) -> Option<Self> {
1207	let (a, b) = self.overflowing_shl(rhs);
1208	if unlikely!(b) { None } else { Some(a) }
1209	}
1210
1211	/// Strict shift left. Computes `self << rhs`, panicking if `rhs` is larger
1212	/// than or equal to the number of bits in `self`.
1213	///
1214	/// # Panics
1215	///
1216	/// ## Overflow behavior
1217	///
1218	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1219	///
1220	/// # Examples
1221	///
1222	/// Basic usage:
1223	///
1224	/// ```
1225	/// #![feature(strict_overflow_ops)]
1226	#[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")]
1227	/// ```
1228	///
1229	/// ```should_panic
1230	/// #![feature(strict_overflow_ops)]
1231	#[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shl(129);")]
1232	/// ```
1233	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
1234	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
1235	#[must_use = "this returns the result of the operation, \
1236	without modifying the original"]
1237	#[inline]
1238	#[track_caller]
1239	pub const fn strict_shl(self, rhs: u32) -> Self {
1240	let (a, b) = self.overflowing_shl(rhs);
1241	if unlikely!(b) { overflow_panic::shl() } else { a }
1242	}
1243
1244	/// Unchecked shift left. Computes `self << rhs`, assuming that
1245	/// `rhs` is less than the number of bits in `self`.
1246	///
1247	/// # Safety
1248	///
1249	/// This results in undefined behavior if `rhs` is larger than
1250	/// or equal to the number of bits in `self`,
1251	/// i.e. when [`checked_shl`] would return `None`.
1252	///
1253	#[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")]
1254	#[unstable(
1255	feature = "unchecked_shifts",
1256	reason = "niche optimization path",
1257	issue = "85122",
1258	)]
1259	#[must_use = "this returns the result of the operation, \
1260	without modifying the original"]
1261	#[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")]
1262	#[inline(always)]
1263	#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1264	pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self {
1265	// SAFETY: the caller must uphold the safety contract for
1266	// `unchecked_shl`.
1267	// Any legal shift amount is losslessly representable in the self type.
1268	unsafe { intrinsics::unchecked_shl(self, conv_rhs_for_unchecked_shift!($SelfT, rhs)) }
1269	}
1270
1271	/// Checked shift right. Computes `self >> rhs`, returning `None`
1272	/// if `rhs` is larger than or equal to the number of bits in `self`.
1273	///
1274	/// # Examples
1275	///
1276	/// Basic usage:
1277	///
1278	/// ```
1279	#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")]
1280	#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(129), None);")]
1281	/// ```
1282	#[stable(feature = "wrapping", since = "1.7.0")]
1283	#[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")]
1284	#[must_use = "this returns the result of the operation, \
1285	without modifying the original"]
1286	#[inline]
1287	pub const fn checked_shr(self, rhs: u32) -> Option<Self> {
1288	let (a, b) = self.overflowing_shr(rhs);
1289	if unlikely!(b) { None } else { Some(a) }
1290	}
1291
1292	/// Strict shift right. Computes `self >> rhs`, panicking `rhs` is
1293	/// larger than or equal to the number of bits in `self`.
1294	///
1295	/// # Panics
1296	///
1297	/// ## Overflow behavior
1298	///
1299	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1300	///
1301	/// # Examples
1302	///
1303	/// Basic usage:
1304	///
1305	/// ```
1306	/// #![feature(strict_overflow_ops)]
1307	#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")]
1308	/// ```
1309	///
1310	/// ```should_panic
1311	/// #![feature(strict_overflow_ops)]
1312	#[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(129);")]
1313	/// ```
1314	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
1315	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
1316	#[must_use = "this returns the result of the operation, \
1317	without modifying the original"]
1318	#[inline]
1319	#[track_caller]
1320	pub const fn strict_shr(self, rhs: u32) -> Self {
1321	let (a, b) = self.overflowing_shr(rhs);
1322	if unlikely!(b) { overflow_panic::shr() } else { a }
1323	}
1324
1325	/// Unchecked shift right. Computes `self >> rhs`, assuming that
1326	/// `rhs` is less than the number of bits in `self`.
1327	///
1328	/// # Safety
1329	///
1330	/// This results in undefined behavior if `rhs` is larger than
1331	/// or equal to the number of bits in `self`,
1332	/// i.e. when [`checked_shr`] would return `None`.
1333	///
1334	#[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")]
1335	#[unstable(
1336	feature = "unchecked_shifts",
1337	reason = "niche optimization path",
1338	issue = "85122",
1339	)]
1340	#[must_use = "this returns the result of the operation, \
1341	without modifying the original"]
1342	#[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")]
1343	#[inline(always)]
1344	#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1345	pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self {
1346	// SAFETY: the caller must uphold the safety contract for
1347	// `unchecked_shr`.
1348	// Any legal shift amount is losslessly representable in the self type.
1349	unsafe { intrinsics::unchecked_shr(self, conv_rhs_for_unchecked_shift!($SelfT, rhs)) }
1350	}
1351
1352	/// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if
1353	/// overflow occurred.
1354	///
1355	/// # Examples
1356	///
1357	/// Basic usage:
1358	///
1359	/// ```
1360	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));")]
1361	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")]
1362	/// ```
1363	#[stable(feature = "no_panic_pow", since = "1.34.0")]
1364	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1365	#[must_use = "this returns the result of the operation, \
1366	without modifying the original"]
1367	#[inline]
1368	pub const fn checked_pow(self, mut exp: u32) -> Option<Self> {
1369	if exp == `0` {
1370	return Some(`1`);
1371	}
1372	let mut base = self;
1373	let mut acc: Self = `1`;
1374
1375	while exp > `1` {
1376	if (exp & `1`) == `1` {
1377	acc = try_opt!(acc.checked_mul(base));
1378	}
1379	exp /= `2`;
1380	base = try_opt!(base.checked_mul(base));
1381	}
1382
1383	// since exp!=0, finally the exp must be 1.
1384	// Deal with the final bit of the exponent separately, since
1385	// squaring the base afterwards is not necessary and may cause a
1386	// needless overflow.
1387
1388	acc.checked_mul(base)
1389	}
1390
1391	/// Strict exponentiation. Computes `self.pow(exp)`, panicking if
1392	/// overflow occurred.
1393	///
1394	/// # Panics
1395	///
1396	/// ## Overflow behavior
1397	///
1398	/// This function will always panic on overflow, regardless of whether overflow checks are enabled.
1399	///
1400	/// # Examples
1401	///
1402	/// Basic usage:
1403	///
1404	/// ```
1405	/// #![feature(strict_overflow_ops)]
1406	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".strict_pow(5), 32);")]
1407	/// ```
1408	///
1409	/// ```should_panic
1410	/// #![feature(strict_overflow_ops)]
1411	#[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")]
1412	/// ```
1413	#[unstable(feature = "strict_overflow_ops", issue = "118260")]
1414	#[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")]
1415	#[must_use = "this returns the result of the operation, \
1416	without modifying the original"]
1417	#[inline]
1418	#[track_caller]
1419	pub const fn strict_pow(self, mut exp: u32) -> Self {
1420	if exp == `0` {
1421	return `1`;
1422	}
1423	let mut base = self;
1424	let mut acc: Self = `1`;
1425
1426	while exp > `1` {
1427	if (exp & `1`) == `1` {
1428	acc = acc.strict_mul(base);
1429	}
1430	exp /= `2`;
1431	base = base.strict_mul(base);
1432	}
1433	// since exp!=0, finally the exp must be 1.
1434	// Deal with the final bit of the exponent separately, since
1435	// squaring the base afterwards is not necessary and may cause a
1436	// needless overflow.
1437	acc.strict_mul(base)
1438	}
1439
1440	/// Saturating integer addition. Computes `self + rhs`, saturating at
1441	/// the numeric bounds instead of overflowing.
1442	///
1443	/// # Examples
1444	///
1445	/// Basic usage:
1446	///
1447	/// ```
1448	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")]
1449	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(127), ", stringify!($SelfT), "::MAX);")]
1450	/// ```
1451	#[stable(feature = "rust1", since = "1.0.0")]
1452	#[must_use = "this returns the result of the operation, \
1453	without modifying the original"]
1454	#[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1455	#[inline(always)]
1456	pub const fn saturating_add(self, rhs: Self) -> Self {
1457	intrinsics::saturating_add(self, rhs)
1458	}
1459
1460	/// Saturating addition with a signed integer. Computes `self + rhs`,
1461	/// saturating at the numeric bounds instead of overflowing.
1462	///
1463	/// # Examples
1464	///
1465	/// Basic usage:
1466	///
1467	/// ```
1468	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_signed(2), 3);")]
1469	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_signed(-2), 0);")]
1470	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).saturating_add_signed(4), ", stringify!($SelfT), "::MAX);")]
1471	/// ```
1472	#[stable(feature = "mixed_integer_ops", since = "1.66.0")]
1473	#[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
1474	#[must_use = "this returns the result of the operation, \
1475	without modifying the original"]
1476	#[inline]
1477	pub const fn saturating_add_signed(self, rhs: $SignedT) -> Self {
1478	let (res, overflow) = self.overflowing_add(rhs as Self);
1479	if overflow == (rhs < `0`) {
1480	res
1481	} else if overflow {
1482	Self::MAX
1483	} else {
1484	`0`
1485	}
1486	}
1487
1488	/// Saturating integer subtraction. Computes `self - rhs`, saturating
1489	/// at the numeric bounds instead of overflowing.
1490	///
1491	/// # Examples
1492	///
1493	/// Basic usage:
1494	///
1495	/// ```
1496	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(27), 73);")]
1497	#[doc = concat!("assert_eq!(13", stringify!($SelfT), ".saturating_sub(127), 0);")]
1498	/// ```
1499	#[stable(feature = "rust1", since = "1.0.0")]
1500	#[must_use = "this returns the result of the operation, \
1501	without modifying the original"]
1502	#[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1503	#[inline(always)]
1504	pub const fn saturating_sub(self, rhs: Self) -> Self {
1505	intrinsics::saturating_sub(self, rhs)
1506	}
1507
1508	/// Saturating integer multiplication. Computes `self rhs`,*
1509	/// saturating at the numeric bounds instead of overflowing.
1510	///
1511	/// # Examples
1512	///
1513	/// Basic usage:
1514	///
1515	/// ```
1516	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".saturating_mul(10), 20);")]
1517	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).saturating_mul(10), ", stringify!($SelfT),"::MAX);")]
1518	/// ```
1519	#[stable(feature = "wrapping", since = "1.7.0")]
1520	#[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")]
1521	#[must_use = "this returns the result of the operation, \
1522	without modifying the original"]
1523	#[inline]
1524	pub const fn saturating_mul(self, rhs: Self) -> Self {
1525	match self.checked_mul(rhs) {
1526	Some(x) => x,
1527	None => Self::MAX,
1528	}
1529	}
1530
1531	/// Saturating integer division. Computes `self / rhs`, saturating at the
1532	/// numeric bounds instead of overflowing.
1533	///
1534	/// # Panics
1535	///
1536	/// This function will panic if `rhs` is 0.
1537	///
1538	/// # Examples
1539	///
1540	/// Basic usage:
1541	///
1542	/// ```
1543	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")]
1544	///
1545	/// ```
1546	#[stable(feature = "saturating_div", since = "1.58.0")]
1547	#[rustc_const_stable(feature = "saturating_div", since = "1.58.0")]
1548	#[must_use = "this returns the result of the operation, \
1549	without modifying the original"]
1550	#[inline]
1551	#[track_caller]
1552	pub const fn saturating_div(self, rhs: Self) -> Self {
1553	// on unsigned types, there is no overflow in integer division
1554	self.wrapping_div(rhs)
1555	}
1556
1557	/// Saturating integer exponentiation. Computes `self.pow(exp)`,
1558	/// saturating at the numeric bounds instead of overflowing.
1559	///
1560	/// # Examples
1561	///
1562	/// Basic usage:
1563	///
1564	/// ```
1565	#[doc = concat!("assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);")]
1566	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);")]
1567	/// ```
1568	#[stable(feature = "no_panic_pow", since = "1.34.0")]
1569	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1570	#[must_use = "this returns the result of the operation, \
1571	without modifying the original"]
1572	#[inline]
1573	pub const fn saturating_pow(self, exp: u32) -> Self {
1574	match self.checked_pow(exp) {
1575	Some(x) => x,
1576	None => Self::MAX,
1577	}
1578	}
1579
1580	/// Wrapping (modular) addition. Computes `self + rhs`,
1581	/// wrapping around at the boundary of the type.
1582	///
1583	/// # Examples
1584	///
1585	/// Basic usage:
1586	///
1587	/// ```
1588	#[doc = concat!("assert_eq!(200", stringify!($SelfT), ".wrapping_add(55), 255);")]
1589	#[doc = concat!("assert_eq!(200", stringify!($SelfT), ".wrapping_add(", stringify!($SelfT), "::MAX), 199);")]
1590	/// ```
1591	#[stable(feature = "rust1", since = "1.0.0")]
1592	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1593	#[must_use = "this returns the result of the operation, \
1594	without modifying the original"]
1595	#[inline(always)]
1596	pub const fn wrapping_add(self, rhs: Self) -> Self {
1597	intrinsics::wrapping_add(self, rhs)
1598	}
1599
1600	/// Wrapping (modular) addition with a signed integer. Computes
1601	/// `self + rhs`, wrapping around at the boundary of the type.
1602	///
1603	/// # Examples
1604	///
1605	/// Basic usage:
1606	///
1607	/// ```
1608	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_add_signed(2), 3);")]
1609	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_add_signed(-2), ", stringify!($SelfT), "::MAX);")]
1610	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).wrapping_add_signed(4), 1);")]
1611	/// ```
1612	#[stable(feature = "mixed_integer_ops", since = "1.66.0")]
1613	#[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
1614	#[must_use = "this returns the result of the operation, \
1615	without modifying the original"]
1616	#[inline]
1617	pub const fn wrapping_add_signed(self, rhs: $SignedT) -> Self {
1618	self.wrapping_add(rhs as Self)
1619	}
1620
1621	/// Wrapping (modular) subtraction. Computes `self - rhs`,
1622	/// wrapping around at the boundary of the type.
1623	///
1624	/// # Examples
1625	///
1626	/// Basic usage:
1627	///
1628	/// ```
1629	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_sub(100), 0);")]
1630	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_sub(", stringify!($SelfT), "::MAX), 101);")]
1631	/// ```
1632	#[stable(feature = "rust1", since = "1.0.0")]
1633	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1634	#[must_use = "this returns the result of the operation, \
1635	without modifying the original"]
1636	#[inline(always)]
1637	pub const fn wrapping_sub(self, rhs: Self) -> Self {
1638	intrinsics::wrapping_sub(self, rhs)
1639	}
1640
1641	/// Wrapping (modular) multiplication. Computes `self *
1642	/// rhs`, wrapping around at the boundary of the type.
1643	///
1644	/// # Examples
1645	///
1646	/// Basic usage:
1647	///
1648	/// Please note that this example is shared between integer types.
1649	/// Which explains why `u8` is used here.
1650	///
1651	/// ```
1652	/// assert_eq!(10u8.wrapping_mul(12), 120);
1653	/// assert_eq!(25u8.wrapping_mul(12), 44);
1654	/// ```
1655	#[stable(feature = "rust1", since = "1.0.0")]
1656	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1657	#[must_use = "this returns the result of the operation, \
1658	without modifying the original"]
1659	#[inline(always)]
1660	pub const fn wrapping_mul(self, rhs: Self) -> Self {
1661	intrinsics::wrapping_mul(self, rhs)
1662	}
1663
1664	/// Wrapping (modular) division. Computes `self / rhs`.
1665	/// Wrapped division on unsigned types is just normal division.
1666	/// There's no way wrapping could ever happen.
1667	/// This function exists, so that all operations
1668	/// are accounted for in the wrapping operations.
1669	///
1670	/// # Panics
1671	///
1672	/// This function will panic if `rhs` is 0.
1673	///
1674	/// # Examples
1675	///
1676	/// Basic usage:
1677	///
1678	/// ```
1679	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")]
1680	/// ```
1681	#[stable(feature = "num_wrapping", since = "1.2.0")]
1682	#[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1683	#[must_use = "this returns the result of the operation, \
1684	without modifying the original"]
1685	#[inline(always)]
1686	#[track_caller]
1687	pub const fn wrapping_div(self, rhs: Self) -> Self {
1688	self / rhs
1689	}
1690
1691	/// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`.
1692	/// Wrapped division on unsigned types is just normal division.
1693	/// There's no way wrapping could ever happen.
1694	/// This function exists, so that all operations
1695	/// are accounted for in the wrapping operations.
1696	/// Since, for the positive integers, all common
1697	/// definitions of division are equal, this
1698	/// is exactly equal to `self.wrapping_div(rhs)`.
1699	///
1700	/// # Panics
1701	///
1702	/// This function will panic if `rhs` is 0.
1703	///
1704	/// # Examples
1705	///
1706	/// Basic usage:
1707	///
1708	/// ```
1709	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")]
1710	/// ```
1711	#[stable(feature = "euclidean_division", since = "1.38.0")]
1712	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1713	#[must_use = "this returns the result of the operation, \
1714	without modifying the original"]
1715	#[inline(always)]
1716	#[track_caller]
1717	pub const fn wrapping_div_euclid(self, rhs: Self) -> Self {
1718	self / rhs
1719	}
1720
1721	/// Wrapping (modular) remainder. Computes `self % rhs`.
1722	/// Wrapped remainder calculation on unsigned types is
1723	/// just the regular remainder calculation.
1724	/// There's no way wrapping could ever happen.
1725	/// This function exists, so that all operations
1726	/// are accounted for in the wrapping operations.
1727	///
1728	/// # Panics
1729	///
1730	/// This function will panic if `rhs` is 0.
1731	///
1732	/// # Examples
1733	///
1734	/// Basic usage:
1735	///
1736	/// ```
1737	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")]
1738	/// ```
1739	#[stable(feature = "num_wrapping", since = "1.2.0")]
1740	#[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")]
1741	#[must_use = "this returns the result of the operation, \
1742	without modifying the original"]
1743	#[inline(always)]
1744	#[track_caller]
1745	pub const fn wrapping_rem(self, rhs: Self) -> Self {
1746	self % rhs
1747	}
1748
1749	/// Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`.
1750	/// Wrapped modulo calculation on unsigned types is
1751	/// just the regular remainder calculation.
1752	/// There's no way wrapping could ever happen.
1753	/// This function exists, so that all operations
1754	/// are accounted for in the wrapping operations.
1755	/// Since, for the positive integers, all common
1756	/// definitions of division are equal, this
1757	/// is exactly equal to `self.wrapping_rem(rhs)`.
1758	///
1759	/// # Panics
1760	///
1761	/// This function will panic if `rhs` is 0.
1762	///
1763	/// # Examples
1764	///
1765	/// Basic usage:
1766	///
1767	/// ```
1768	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")]
1769	/// ```
1770	#[stable(feature = "euclidean_division", since = "1.38.0")]
1771	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
1772	#[must_use = "this returns the result of the operation, \
1773	without modifying the original"]
1774	#[inline(always)]
1775	#[track_caller]
1776	pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self {
1777	self % rhs
1778	}
1779
1780	/// Wrapping (modular) negation. Computes `-self`,
1781	/// wrapping around at the boundary of the type.
1782	///
1783	/// Since unsigned types do not have negative equivalents
1784	/// all applications of this function will wrap (except for `-0`).
1785	/// For values smaller than the corresponding signed type's maximum
1786	/// the result is the same as casting the corresponding signed value.
1787	/// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where
1788	/// `MAX` is the corresponding signed type's maximum.
1789	///
1790	/// # Examples
1791	///
1792	/// Basic usage:
1793	///
1794	/// ```
1795	#[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".wrapping_neg(), 0);")]
1796	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_neg(), 1);")]
1797	#[doc = concat!("assert_eq!(13_", stringify!($SelfT), ".wrapping_neg(), (!13) + 1);")]
1798	#[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_neg(), !(42 - 1));")]
1799	/// ```
1800	#[stable(feature = "num_wrapping", since = "1.2.0")]
1801	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1802	#[must_use = "this returns the result of the operation, \
1803	without modifying the original"]
1804	#[inline(always)]
1805	pub const fn wrapping_neg(self) -> Self {
1806	(`0` as $SelfT).wrapping_sub(self)
1807	}
1808
1809	/// Panic-free bitwise shift-left; yields `self << mask(rhs)`,
1810	/// where `mask` removes any high-order bits of `rhs` that
1811	/// would cause the shift to exceed the bitwidth of the type.
1812	///
1813	/// Note that this is not* the same as a rotate-left; the*
1814	/// RHS of a wrapping shift-left is restricted to the range
1815	/// of the type, rather than the bits shifted out of the LHS
1816	/// being returned to the other end. The primitive integer
1817	/// types all implement a [`rotate_left`](Self::rotate_left) function,
1818	/// which may be what you want instead.
1819	///
1820	/// # Examples
1821	///
1822	/// Basic usage:
1823	///
1824	/// ```
1825	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_shl(7), 128);")]
1826	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_shl(128), 1);")]
1827	/// ```
1828	#[stable(feature = "num_wrapping", since = "1.2.0")]
1829	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1830	#[must_use = "this returns the result of the operation, \
1831	without modifying the original"]
1832	#[inline(always)]
1833	#[rustc_allow_const_fn_unstable(unchecked_shifts)]
1834	pub const fn wrapping_shl(self, rhs: u32) -> Self {
1835	// SAFETY: the masking by the bitsize of the type ensures that we do not shift
1836	// out of bounds
1837	unsafe {
1838	self.unchecked_shl(rhs & (Self::BITS - `1`))
1839	}
1840	}
1841
1842	/// Panic-free bitwise shift-right; yields `self >> mask(rhs)`,
1843	/// where `mask` removes any high-order bits of `rhs` that
1844	/// would cause the shift to exceed the bitwidth of the type.
1845	///
1846	/// Note that this is not* the same as a rotate-right; the*
1847	/// RHS of a wrapping shift-right is restricted to the range
1848	/// of the type, rather than the bits shifted out of the LHS
1849	/// being returned to the other end. The primitive integer
1850	/// types all implement a [`rotate_right`](Self::rotate_right) function,
1851	/// which may be what you want instead.
1852	///
1853	/// # Examples
1854	///
1855	/// Basic usage:
1856	///
1857	/// ```
1858	#[doc = concat!("assert_eq!(128", stringify!($SelfT), ".wrapping_shr(7), 1);")]
1859	#[doc = concat!("assert_eq!(128", stringify!($SelfT), ".wrapping_shr(128), 128);")]
1860	/// ```
1861	#[stable(feature = "num_wrapping", since = "1.2.0")]
1862	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1863	#[must_use = "this returns the result of the operation, \
1864	without modifying the original"]
1865	#[inline(always)]
1866	#[rustc_allow_const_fn_unstable(unchecked_shifts)]
1867	pub const fn wrapping_shr(self, rhs: u32) -> Self {
1868	// SAFETY: the masking by the bitsize of the type ensures that we do not shift
1869	// out of bounds
1870	unsafe {
1871	self.unchecked_shr(rhs & (Self::BITS - `1`))
1872	}
1873	}
1874
1875	/// Wrapping (modular) exponentiation. Computes `self.pow(exp)`,
1876	/// wrapping around at the boundary of the type.
1877	///
1878	/// # Examples
1879	///
1880	/// Basic usage:
1881	///
1882	/// ```
1883	#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);")]
1884	/// assert_eq!(3u8.wrapping_pow(6), 217);
1885	/// ```
1886	#[stable(feature = "no_panic_pow", since = "1.34.0")]
1887	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
1888	#[must_use = "this returns the result of the operation, \
1889	without modifying the original"]
1890	#[inline]
1891	pub const fn wrapping_pow(self, mut exp: u32) -> Self {
1892	if exp == `0` {
1893	return `1`;
1894	}
1895	let mut base = self;
1896	let mut acc: Self = `1`;
1897
1898	while exp > `1` {
1899	if (exp & `1`) == `1` {
1900	acc = acc.wrapping_mul(base);
1901	}
1902	exp /= `2`;
1903	base = base.wrapping_mul(base);
1904	}
1905
1906	// since exp!=0, finally the exp must be 1.
1907	// Deal with the final bit of the exponent separately, since
1908	// squaring the base afterwards is not necessary and may cause a
1909	// needless overflow.
1910	acc.wrapping_mul(base)
1911	}
1912
1913	/// Calculates `self` + `rhs`
1914	///
1915	/// Returns a tuple of the addition along with a boolean indicating
1916	/// whether an arithmetic overflow would occur. If an overflow would
1917	/// have occurred then the wrapped value is returned.
1918	///
1919	/// # Examples
1920	///
1921	/// Basic usage
1922	///
1923	/// ```
1924	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")]
1925	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (0, true));")]
1926	/// ```
1927	#[stable(feature = "wrapping", since = "1.7.0")]
1928	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
1929	#[must_use = "this returns the result of the operation, \
1930	without modifying the original"]
1931	#[inline(always)]
1932	pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) {
1933	let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT);
1934	(a as Self, b)
1935	}
1936
1937	/// Calculates `self` + `rhs` + `carry` and returns a tuple containing
1938	/// the sum and the output carry.
1939	///
1940	/// Performs "ternary addition" of two integer operands and a carry-in
1941	/// bit, and returns an output integer and a carry-out bit. This allows
1942	/// chaining together multiple additions to create a wider addition, and
1943	/// can be useful for bignum addition.
1944	///
1945	#[doc = concat!("This can be thought of as a ", stringify!($BITS), "-bit `\"`full adder`\"`, in the electronics sense.")]
1946	///
1947	/// If the input carry is false, this method is equivalent to
1948	/// [`overflowing_add`](Self::overflowing_add), and the output carry is
1949	/// equal to the overflow flag. Note that although carry and overflow
1950	/// flags are similar for unsigned integers, they are different for
1951	/// signed integers.
1952	///
1953	/// # Examples
1954	///
1955	/// ```
1956	/// #![feature(bigint_helper_methods)]
1957	///
1958	#[doc = concat!("// 3 MAX (a = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
1959	#[doc = concat!("// + 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")]
1960	/// // ---------
1961	#[doc = concat!("// 9 6 (sum = 9 × 2^", stringify!($BITS), " + 6)")]
1962	///
1963	#[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (3, ", stringify!($SelfT), "::MAX);")]
1964	#[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (5, 7);")]
1965	/// let carry0 = false;
1966	///
1967	/// let (sum0, carry1) = a0.carrying_add(b0, carry0);
1968	/// assert_eq!(carry1, true);
1969	/// let (sum1, carry2) = a1.carrying_add(b1, carry1);
1970	/// assert_eq!(carry2, false);
1971	///
1972	/// assert_eq!((sum1, sum0), (9, 6));
1973	/// ```
1974	#[unstable(feature = "bigint_helper_methods", issue = "85532")]
1975	#[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
1976	#[must_use = "this returns the result of the operation, \
1977	without modifying the original"]
1978	#[inline]
1979	pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) {
1980	// note: longer-term this should be done via an intrinsic, but this has been shown
1981	// to generate optimal code for now, and LLVM doesn't have an equivalent intrinsic
1982	let (a, b) = self.overflowing_add(rhs);
1983	let (c, d) = a.overflowing_add(carry as $SelfT);
1984	(c, b \|\| d)
1985	}
1986
1987	/// Calculates `self` + `rhs` with a signed `rhs`
1988	///
1989	/// Returns a tuple of the addition along with a boolean indicating
1990	/// whether an arithmetic overflow would occur. If an overflow would
1991	/// have occurred then the wrapped value is returned.
1992	///
1993	/// # Examples
1994	///
1995	/// Basic usage:
1996	///
1997	/// ```
1998	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_signed(2), (3, false));")]
1999	#[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_signed(-2), (", stringify!($SelfT), "::MAX, true));")]
2000	#[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_signed(4), (1, true));")]
2001	/// ```
2002	#[stable(feature = "mixed_integer_ops", since = "1.66.0")]
2003	#[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")]
2004	#[must_use = "this returns the result of the operation, \
2005	without modifying the original"]
2006	#[inline]
2007	pub const fn overflowing_add_signed(self, rhs: $SignedT) -> (Self, bool) {
2008	let (res, overflowed) = self.overflowing_add(rhs as Self);
2009	(res, overflowed ^ (rhs < `0`))
2010	}
2011
2012	/// Calculates `self` - `rhs`
2013	///
2014	/// Returns a tuple of the subtraction along with a boolean indicating
2015	/// whether an arithmetic overflow would occur. If an overflow would
2016	/// have occurred then the wrapped value is returned.
2017	///
2018	/// # Examples
2019	///
2020	/// Basic usage
2021	///
2022	/// ```
2023	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")]
2024	#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")]
2025	/// ```
2026	#[stable(feature = "wrapping", since = "1.7.0")]
2027	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
2028	#[must_use = "this returns the result of the operation, \
2029	without modifying the original"]
2030	#[inline(always)]
2031	pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) {
2032	let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT);
2033	(a as Self, b)
2034	}
2035
2036	/// Calculates `self` − `rhs` − `borrow` and returns a tuple
2037	/// containing the difference and the output borrow.
2038	///
2039	/// Performs "ternary subtraction" by subtracting both an integer
2040	/// operand and a borrow-in bit from `self`, and returns an output
2041	/// integer and a borrow-out bit. This allows chaining together multiple
2042	/// subtractions to create a wider subtraction, and can be useful for
2043	/// bignum subtraction.
2044	///
2045	/// # Examples
2046	///
2047	/// ```
2048	/// #![feature(bigint_helper_methods)]
2049	///
2050	#[doc = concat!("// 9 6 (a = 9 × 2^", stringify!($BITS), " + 6)")]
2051	#[doc = concat!("// - 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")]
2052	/// // ---------
2053	#[doc = concat!("// 3 MAX (diff = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
2054	///
2055	#[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (9, 6);")]
2056	#[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (5, 7);")]
2057	/// let borrow0 = false;
2058	///
2059	/// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0);
2060	/// assert_eq!(borrow1, true);
2061	/// let (diff1, borrow2) = a1.borrowing_sub(b1, borrow1);
2062	/// assert_eq!(borrow2, false);
2063	///
2064	#[doc = concat!("assert_eq!((diff1, diff0), (3, ", stringify!($SelfT), "::MAX));")]
2065	/// ```
2066	#[unstable(feature = "bigint_helper_methods", issue = "85532")]
2067	#[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
2068	#[must_use = "this returns the result of the operation, \
2069	without modifying the original"]
2070	#[inline]
2071	pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) {
2072	// note: longer-term this should be done via an intrinsic, but this has been shown
2073	// to generate optimal code for now, and LLVM doesn't have an equivalent intrinsic
2074	let (a, b) = self.overflowing_sub(rhs);
2075	let (c, d) = a.overflowing_sub(borrow as $SelfT);
2076	(c, b \|\| d)
2077	}
2078
2079	/// Computes the absolute difference between `self` and `other`.
2080	///
2081	/// # Examples
2082	///
2083	/// Basic usage:
2084	///
2085	/// ```
2086	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($SelfT), ");")]
2087	#[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($SelfT), ");")]
2088	/// ```
2089	#[stable(feature = "int_abs_diff", since = "1.60.0")]
2090	#[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")]
2091	#[must_use = "this returns the result of the operation, \
2092	without modifying the original"]
2093	#[inline]
2094	pub const fn abs_diff(self, other: Self) -> Self {
2095	if mem::size_of::<Self>() == `1` {
2096	// Trick LLVM into generating the psadbw instruction when SSE2
2097	// is available and this function is autovectorized for u8's.
2098	(self as i32).wrapping_sub(other as i32).abs() as Self
2099	} else {
2100	if self < other {
2101	other - self
2102	} else {
2103	self - other
2104	}
2105	}
2106	}
2107
2108	/// Calculates the multiplication of `self` and `rhs`.
2109	///
2110	/// Returns a tuple of the multiplication along with a boolean
2111	/// indicating whether an arithmetic overflow would occur. If an
2112	/// overflow would have occurred then the wrapped value is returned.
2113	///
2114	/// # Examples
2115	///
2116	/// Basic usage:
2117	///
2118	/// Please note that this example is shared between integer types.
2119	/// Which explains why `u32` is used here.
2120	///
2121	/// ```
2122	/// assert_eq!(5u32.overflowing_mul(2), (10, false));
2123	/// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));
2124	/// ```
2125	#[stable(feature = "wrapping", since = "1.7.0")]
2126	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
2127	#[must_use = "this returns the result of the operation, \
2128	without modifying the original"]
2129	#[inline(always)]
2130	pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) {
2131	let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT);
2132	(a as Self, b)
2133	}
2134
2135	/// Calculates the divisor when `self` is divided by `rhs`.
2136	///
2137	/// Returns a tuple of the divisor along with a boolean indicating
2138	/// whether an arithmetic overflow would occur. Note that for unsigned
2139	/// integers overflow never occurs, so the second value is always
2140	/// `false`.
2141	///
2142	/// # Panics
2143	///
2144	/// This function will panic if `rhs` is 0.
2145	///
2146	/// # Examples
2147	///
2148	/// Basic usage
2149	///
2150	/// ```
2151	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")]
2152	/// ```
2153	#[inline(always)]
2154	#[stable(feature = "wrapping", since = "1.7.0")]
2155	#[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
2156	#[must_use = "this returns the result of the operation, \
2157	without modifying the original"]
2158	#[track_caller]
2159	pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) {
2160	(self / rhs, `false`)
2161	}
2162
2163	/// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`.
2164	///
2165	/// Returns a tuple of the divisor along with a boolean indicating
2166	/// whether an arithmetic overflow would occur. Note that for unsigned
2167	/// integers overflow never occurs, so the second value is always
2168	/// `false`.
2169	/// Since, for the positive integers, all common
2170	/// definitions of division are equal, this
2171	/// is exactly equal to `self.overflowing_div(rhs)`.
2172	///
2173	/// # Panics
2174	///
2175	/// This function will panic if `rhs` is 0.
2176	///
2177	/// # Examples
2178	///
2179	/// Basic usage
2180	///
2181	/// ```
2182	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")]
2183	/// ```
2184	#[inline(always)]
2185	#[stable(feature = "euclidean_division", since = "1.38.0")]
2186	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2187	#[must_use = "this returns the result of the operation, \
2188	without modifying the original"]
2189	#[track_caller]
2190	pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) {
2191	(self / rhs, `false`)
2192	}
2193
2194	/// Calculates the remainder when `self` is divided by `rhs`.
2195	///
2196	/// Returns a tuple of the remainder after dividing along with a boolean
2197	/// indicating whether an arithmetic overflow would occur. Note that for
2198	/// unsigned integers overflow never occurs, so the second value is
2199	/// always `false`.
2200	///
2201	/// # Panics
2202	///
2203	/// This function will panic if `rhs` is 0.
2204	///
2205	/// # Examples
2206	///
2207	/// Basic usage
2208	///
2209	/// ```
2210	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")]
2211	/// ```
2212	#[inline(always)]
2213	#[stable(feature = "wrapping", since = "1.7.0")]
2214	#[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")]
2215	#[must_use = "this returns the result of the operation, \
2216	without modifying the original"]
2217	#[track_caller]
2218	pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) {
2219	(self % rhs, `false`)
2220	}
2221
2222	/// Calculates the remainder `self.rem_euclid(rhs)` as if by Euclidean division.
2223	///
2224	/// Returns a tuple of the modulo after dividing along with a boolean
2225	/// indicating whether an arithmetic overflow would occur. Note that for
2226	/// unsigned integers overflow never occurs, so the second value is
2227	/// always `false`.
2228	/// Since, for the positive integers, all common
2229	/// definitions of division are equal, this operation
2230	/// is exactly equal to `self.overflowing_rem(rhs)`.
2231	///
2232	/// # Panics
2233	///
2234	/// This function will panic if `rhs` is 0.
2235	///
2236	/// # Examples
2237	///
2238	/// Basic usage
2239	///
2240	/// ```
2241	#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")]
2242	/// ```
2243	#[inline(always)]
2244	#[stable(feature = "euclidean_division", since = "1.38.0")]
2245	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2246	#[must_use = "this returns the result of the operation, \
2247	without modifying the original"]
2248	#[track_caller]
2249	pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) {
2250	(self % rhs, `false`)
2251	}
2252
2253	/// Negates self in an overflowing fashion.
2254	///
2255	/// Returns `!self + 1` using wrapping operations to return the value
2256	/// that represents the negation of this unsigned value. Note that for
2257	/// positive unsigned values overflow always occurs, but negating 0 does
2258	/// not overflow.
2259	///
2260	/// # Examples
2261	///
2262	/// Basic usage
2263	///
2264	/// ```
2265	#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".overflowing_neg(), (0, false));")]
2266	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2i32 as ", stringify!($SelfT), ", true));")]
2267	/// ```
2268	#[inline(always)]
2269	#[stable(feature = "wrapping", since = "1.7.0")]
2270	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
2271	#[must_use = "this returns the result of the operation, \
2272	without modifying the original"]
2273	pub const fn overflowing_neg(self) -> (Self, bool) {
2274	((!self).wrapping_add(`1`), self != `0`)
2275	}
2276
2277	/// Shifts self left by `rhs` bits.
2278	///
2279	/// Returns a tuple of the shifted version of self along with a boolean
2280	/// indicating whether the shift value was larger than or equal to the
2281	/// number of bits. If the shift value is too large, then value is
2282	/// masked (N-1) where N is the number of bits, and this value is then
2283	/// used to perform the shift.
2284	///
2285	/// # Examples
2286	///
2287	/// Basic usage
2288	///
2289	/// ```
2290	#[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));")]
2291	#[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));")]
2292	/// ```
2293	#[stable(feature = "wrapping", since = "1.7.0")]
2294	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
2295	#[must_use = "this returns the result of the operation, \
2296	without modifying the original"]
2297	#[inline(always)]
2298	pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) {
2299	(self.wrapping_shl(rhs), rhs >= Self::BITS)
2300	}
2301
2302	/// Shifts self right by `rhs` bits.
2303	///
2304	/// Returns a tuple of the shifted version of self along with a boolean
2305	/// indicating whether the shift value was larger than or equal to the
2306	/// number of bits. If the shift value is too large, then value is
2307	/// masked (N-1) where N is the number of bits, and this value is then
2308	/// used to perform the shift.
2309	///
2310	/// # Examples
2311	///
2312	/// Basic usage
2313	///
2314	/// ```
2315	#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")]
2316	#[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(132), (0x1, true));")]
2317	/// ```
2318	#[stable(feature = "wrapping", since = "1.7.0")]
2319	#[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")]
2320	#[must_use = "this returns the result of the operation, \
2321	without modifying the original"]
2322	#[inline(always)]
2323	pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) {
2324	(self.wrapping_shr(rhs), rhs >= Self::BITS)
2325	}
2326
2327	/// Raises self to the power of `exp`, using exponentiation by squaring.
2328	///
2329	/// Returns a tuple of the exponentiation along with a bool indicating
2330	/// whether an overflow happened.
2331	///
2332	/// # Examples
2333	///
2334	/// Basic usage:
2335	///
2336	/// ```
2337	#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));")]
2338	/// assert_eq!(3u8.overflowing_pow(6), (217, true));
2339	/// ```
2340	#[stable(feature = "no_panic_pow", since = "1.34.0")]
2341	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2342	#[must_use = "this returns the result of the operation, \
2343	without modifying the original"]
2344	#[inline]
2345	pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) {
2346	if exp == `0`{
2347	return (`1`,`false`);
2348	}
2349	let mut base = self;
2350	let mut acc: Self = `1`;
2351	let mut overflown = `false`;
2352	// Scratch space for storing results of overflowing_mul.
2353	let mut r;
2354
2355	while exp > `1` {
2356	if (exp & `1`) == `1` {
2357	r = acc.overflowing_mul(base);
2358	acc = r.`0`;
2359	overflown \|= r.`1`;
2360	}
2361	exp /= `2`;
2362	r = base.overflowing_mul(base);
2363	base = r.`0`;
2364	overflown \|= r.`1`;
2365	}
2366
2367	// since exp!=0, finally the exp must be 1.
2368	// Deal with the final bit of the exponent separately, since
2369	// squaring the base afterwards is not necessary and may cause a
2370	// needless overflow.
2371	r = acc.overflowing_mul(base);
2372	r.`1` \|= overflown;
2373
2374	r
2375	}
2376
2377	/// Raises self to the power of `exp`, using exponentiation by squaring.
2378	///
2379	/// # Examples
2380	///
2381	/// Basic usage:
2382	///
2383	/// ```
2384	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".pow(5), 32);")]
2385	/// ```
2386	#[stable(feature = "rust1", since = "1.0.0")]
2387	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2388	#[must_use = "this returns the result of the operation, \
2389	without modifying the original"]
2390	#[inline]
2391	#[rustc_inherit_overflow_checks]
2392	pub const fn pow(self, mut exp: u32) -> Self {
2393	if exp == `0` {
2394	return `1`;
2395	}
2396	let mut base = self;
2397	let mut acc = `1`;
2398
2399	while exp > `1` {
2400	if (exp & `1`) == `1` {
2401	acc = acc * base;
2402	}
2403	exp /= `2`;
2404	base = base * base;
2405	}
2406
2407	// since exp!=0, finally the exp must be 1.
2408	// Deal with the final bit of the exponent separately, since
2409	// squaring the base afterwards is not necessary and may cause a
2410	// needless overflow.
2411	acc * base
2412	}
2413
2414	/// Returns the square root of the number, rounded down.
2415	///
2416	/// # Examples
2417	///
2418	/// Basic usage:
2419	/// ```
2420	/// #![feature(isqrt)]
2421	#[doc = concat!("assert_eq!(10", stringify!($SelfT), ".isqrt(), 3);")]
2422	/// ```
2423	#[unstable(feature = "isqrt", issue = "116226")]
2424	#[rustc_const_unstable(feature = "isqrt", issue = "116226")]
2425	#[must_use = "this returns the result of the operation, \
2426	without modifying the original"]
2427	#[inline]
2428	pub const fn isqrt(self) -> Self {
2429	if self < `2` {
2430	return self;
2431	}
2432
2433	// The algorithm is based on the one presented in
2434	// <https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Binary_numeral_system_(base_2)>
2435	// which cites as source the following C code:
2436	// <https://web.archive.org/web/20120306040058/http://medialab.freaknet.org/martin/src/sqrt/sqrt.c>.
2437
2438	let mut op = self;
2439	let mut res = `0`;
2440	let mut one = `1` << (self.ilog2() & !`1`);
2441
2442	while one != `0` {
2443	if op >= res + one {
2444	op -= res + one;
2445	res = (res >> `1`) + one;
2446	} else {
2447	res >>= `1`;
2448	}
2449	one >>= `2`;
2450	}
2451
2452	// SAFETY: the result is positive and fits in an integer with half as many bits.
2453	// Inform the optimizer about it.
2454	unsafe {
2455	hint::assert_unchecked(`0` < res);
2456	hint::assert_unchecked(res < `1` << (Self::BITS / `2`));
2457	}
2458
2459	res
2460	}
2461
2462	/// Performs Euclidean division.
2463	///
2464	/// Since, for the positive integers, all common
2465	/// definitions of division are equal, this
2466	/// is exactly equal to `self / rhs`.
2467	///
2468	/// # Panics
2469	///
2470	/// This function will panic if `rhs` is 0.
2471	///
2472	/// # Examples
2473	///
2474	/// Basic usage:
2475	///
2476	/// ```
2477	#[doc = concat!("assert_eq!(7", stringify!($SelfT), ".div_euclid(4), 1); // or any other integer type")]
2478	/// ```
2479	#[stable(feature = "euclidean_division", since = "1.38.0")]
2480	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2481	#[must_use = "this returns the result of the operation, \
2482	without modifying the original"]
2483	#[inline(always)]
2484	#[track_caller]
2485	pub const fn div_euclid(self, rhs: Self) -> Self {
2486	self / rhs
2487	}
2488
2489
2490	/// Calculates the least remainder of `self (mod rhs)`.
2491	///
2492	/// Since, for the positive integers, all common
2493	/// definitions of division are equal, this
2494	/// is exactly equal to `self % rhs`.
2495	///
2496	/// # Panics
2497	///
2498	/// This function will panic if `rhs` is 0.
2499	///
2500	/// # Examples
2501	///
2502	/// Basic usage:
2503	///
2504	/// ```
2505	#[doc = concat!("assert_eq!(7", stringify!($SelfT), ".rem_euclid(4), 3); // or any other integer type")]
2506	/// ```
2507	#[doc(alias = "modulo", alias = "mod")]
2508	#[stable(feature = "euclidean_division", since = "1.38.0")]
2509	#[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")]
2510	#[must_use = "this returns the result of the operation, \
2511	without modifying the original"]
2512	#[inline(always)]
2513	#[track_caller]
2514	pub const fn rem_euclid(self, rhs: Self) -> Self {
2515	self % rhs
2516	}
2517
2518	/// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity.
2519	///
2520	/// This is the same as performing `self / rhs` for all unsigned integers.
2521	///
2522	/// # Panics
2523	///
2524	/// This function will panic if `rhs` is zero.
2525	///
2526	/// # Examples
2527	///
2528	/// Basic usage:
2529	///
2530	/// ```
2531	/// #![feature(int_roundings)]
2532	#[doc = concat!("assert_eq!(7_", stringify!($SelfT), ".div_floor(4), 1);")]
2533	/// ```
2534	#[unstable(feature = "int_roundings", issue = "88581")]
2535	#[must_use = "this returns the result of the operation, \
2536	without modifying the original"]
2537	#[inline(always)]
2538	#[track_caller]
2539	pub const fn div_floor(self, rhs: Self) -> Self {
2540	self / rhs
2541	}
2542
2543	/// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity.
2544	///
2545	/// # Panics
2546	///
2547	/// This function will panic if `rhs` is zero.
2548	///
2549	/// # Examples
2550	///
2551	/// Basic usage:
2552	///
2553	/// ```
2554	#[doc = concat!("assert_eq!(7_", stringify!($SelfT), ".div_ceil(4), 2);")]
2555	/// ```
2556	#[stable(feature = "int_roundings1", since = "1.73.0")]
2557	#[rustc_const_stable(feature = "int_roundings1", since = "1.73.0")]
2558	#[must_use = "this returns the result of the operation, \
2559	without modifying the original"]
2560	#[inline]
2561	#[track_caller]
2562	pub const fn div_ceil(self, rhs: Self) -> Self {
2563	let d = self / rhs;
2564	let r = self % rhs;
2565	if r > `0` && rhs > `0` {
2566	d + `1`
2567	} else {
2568	d
2569	}
2570	}
2571
2572	/// Calculates the smallest value greater than or equal to `self` that
2573	/// is a multiple of `rhs`.
2574	///
2575	/// # Panics
2576	///
2577	/// This function will panic if `rhs` is zero.
2578	///
2579	/// ## Overflow behavior
2580	///
2581	/// On overflow, this function will panic if overflow checks are enabled (default in debug
2582	/// mode) and wrap if overflow checks are disabled (default in release mode).
2583	///
2584	/// # Examples
2585	///
2586	/// Basic usage:
2587	///
2588	/// ```
2589	#[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")]
2590	#[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")]
2591	/// ```
2592	#[stable(feature = "int_roundings1", since = "1.73.0")]
2593	#[rustc_const_stable(feature = "int_roundings1", since = "1.73.0")]
2594	#[must_use = "this returns the result of the operation, \
2595	without modifying the original"]
2596	#[inline]
2597	#[rustc_inherit_overflow_checks]
2598	pub const fn next_multiple_of(self, rhs: Self) -> Self {
2599	match self % rhs {
2600	`0` => self,
2601	r => self + (rhs - r)
2602	}
2603	}
2604
2605	/// Calculates the smallest value greater than or equal to `self` that
2606	/// is a multiple of `rhs`. Returns `None` if `rhs` is zero or the
2607	/// operation would result in overflow.
2608	///
2609	/// # Examples
2610	///
2611	/// Basic usage:
2612	///
2613	/// ```
2614	#[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")]
2615	#[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")]
2616	#[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")]
2617	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")]
2618	/// ```
2619	#[stable(feature = "int_roundings1", since = "1.73.0")]
2620	#[rustc_const_stable(feature = "int_roundings1", since = "1.73.0")]
2621	#[must_use = "this returns the result of the operation, \
2622	without modifying the original"]
2623	#[inline]
2624	pub const fn checked_next_multiple_of(self, rhs: Self) -> Option<Self> {
2625	match try_opt!(self.checked_rem(rhs)) {
2626	`0` => Some(self),
2627	// rhs - r cannot overflow because r is smaller than rhs
2628	r => self.checked_add(rhs - r)
2629	}
2630	}
2631
2632	/// Returns `true` if and only if `self == 2^k` for some `k`.
2633	///
2634	/// # Examples
2635	///
2636	/// Basic usage:
2637	///
2638	/// ```
2639	#[doc = concat!("assert!(16", stringify!($SelfT), ".is_power_of_two());")]
2640	#[doc = concat!("assert!(!10", stringify!($SelfT), ".is_power_of_two());")]
2641	/// ```
2642	#[must_use]
2643	#[stable(feature = "rust1", since = "1.0.0")]
2644	#[rustc_const_stable(feature = "const_is_power_of_two", since = "1.32.0")]
2645	#[inline(always)]
2646	pub const fn is_power_of_two(self) -> bool {
2647	self.count_ones() == `1`
2648	}
2649
2650	// Returns one less than next power of two.
2651	// (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8)
2652	//
2653	// 8u8.one_less_than_next_power_of_two() == 7
2654	// 6u8.one_less_than_next_power_of_two() == 7
2655	//
2656	// This method cannot overflow, as in the `next_power_of_two`
2657	// overflow cases it instead ends up returning the maximum value
2658	// of the type, and can return 0 for 0.
2659	#[inline]
2660	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2661	const fn one_less_than_next_power_of_two(self) -> Self {
2662	if self <= `1` { return `0`; }
2663
2664	let p = self - `1`;
2665	// SAFETY: Because `p > 0`, it cannot consist entirely of leading zeros.
2666	// That means the shift is always in-bounds, and some processors
2667	// (such as intel pre-haswell) have more efficient ctlz
2668	// intrinsics when the argument is non-zero.
2669	let z = unsafe { intrinsics::ctlz_nonzero(p) };
2670	<$SelfT>::MAX >> z
2671	}
2672
2673	/// Returns the smallest power of two greater than or equal to `self`.
2674	///
2675	/// When return value overflows (i.e., `self > (1 << (N-1))` for type
2676	/// `uN`), it panics in debug mode and the return value is wrapped to 0 in
2677	/// release mode (the only situation in which method can return 0).
2678	///
2679	/// # Examples
2680	///
2681	/// Basic usage:
2682	///
2683	/// ```
2684	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".next_power_of_two(), 2);")]
2685	#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".next_power_of_two(), 4);")]
2686	/// ```
2687	#[stable(feature = "rust1", since = "1.0.0")]
2688	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2689	#[must_use = "this returns the result of the operation, \
2690	without modifying the original"]
2691	#[inline]
2692	#[rustc_inherit_overflow_checks]
2693	pub const fn next_power_of_two(self) -> Self {
2694	self.one_less_than_next_power_of_two() + `1`
2695	}
2696
2697	/// Returns the smallest power of two greater than or equal to `n`. If
2698	/// the next power of two is greater than the type's maximum value,
2699	/// `None` is returned, otherwise the power of two is wrapped in `Some`.
2700	///
2701	/// # Examples
2702	///
2703	/// Basic usage:
2704	///
2705	/// ```
2706	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_next_power_of_two(), Some(2));")]
2707	#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".checked_next_power_of_two(), Some(4));")]
2708	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_power_of_two(), None);")]
2709	/// ```
2710	#[inline]
2711	#[stable(feature = "rust1", since = "1.0.0")]
2712	#[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")]
2713	#[must_use = "this returns the result of the operation, \
2714	without modifying the original"]
2715	pub const fn checked_next_power_of_two(self) -> Option<Self> {
2716	self.one_less_than_next_power_of_two().checked_add(`1`)
2717	}
2718
2719	/// Returns the smallest power of two greater than or equal to `n`. If
2720	/// the next power of two is greater than the type's maximum value,
2721	/// the return value is wrapped to `0`.
2722	///
2723	/// # Examples
2724	///
2725	/// Basic usage:
2726	///
2727	/// ```
2728	/// #![feature(wrapping_next_power_of_two)]
2729	///
2730	#[doc = concat!("assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);")]
2731	#[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);")]
2732	#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_next_power_of_two(), 0);")]
2733	/// ```
2734	#[inline]
2735	#[unstable(feature = "wrapping_next_power_of_two", issue = "32463",
2736	reason = "needs decision on wrapping behaviour")]
2737	#[rustc_const_unstable(feature = "wrapping_next_power_of_two", issue = "32463")]
2738	#[must_use = "this returns the result of the operation, \
2739	without modifying the original"]
2740	pub const fn wrapping_next_power_of_two(self) -> Self {
2741	self.one_less_than_next_power_of_two().wrapping_add(`1`)
2742	}
2743
2744	/// Return the memory representation of this integer as a byte array in
2745	/// big-endian (network) byte order.
2746	///
2747	#[doc = $to_xe_bytes_doc]
2748	///
2749	/// # Examples
2750	///
2751	/// ```
2752	#[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")]
2753	#[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")]
2754	/// ```
2755	#[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2756	#[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2757	#[must_use = "this returns the result of the operation, \
2758	without modifying the original"]
2759	#[inline]
2760	pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] {
2761	self.to_be().to_ne_bytes()
2762	}
2763
2764	/// Return the memory representation of this integer as a byte array in
2765	/// little-endian byte order.
2766	///
2767	#[doc = $to_xe_bytes_doc]
2768	///
2769	/// # Examples
2770	///
2771	/// ```
2772	#[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")]
2773	#[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")]
2774	/// ```
2775	#[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2776	#[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2777	#[must_use = "this returns the result of the operation, \
2778	without modifying the original"]
2779	#[inline]
2780	pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] {
2781	self.to_le().to_ne_bytes()
2782	}
2783
2784	/// Return the memory representation of this integer as a byte array in
2785	/// native byte order.
2786	///
2787	/// As the target platform's native endianness is used, portable code
2788	/// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
2789	/// instead.
2790	///
2791	#[doc = $to_xe_bytes_doc]
2792	///
2793	/// [`to_be_bytes`]: Self::to_be_bytes
2794	/// [`to_le_bytes`]: Self::to_le_bytes
2795	///
2796	/// # Examples
2797	///
2798	/// ```
2799	#[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")]
2800	/// assert_eq!(
2801	/// bytes,
2802	/// if cfg!(target_endian = "big") {
2803	#[doc = concat!(" ", $be_bytes)]
2804	/// } else {
2805	#[doc = concat!(" ", $le_bytes)]
2806	/// }
2807	/// );
2808	/// ```
2809	#[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2810	#[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2811	#[must_use = "this returns the result of the operation, \
2812	without modifying the original"]
2813	// SAFETY: const sound because integers are plain old datatypes so we can always
2814	// transmute them to arrays of bytes
2815	#[inline]
2816	pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] {
2817	// SAFETY: integers are plain old datatypes so we can always transmute them to
2818	// arrays of bytes
2819	unsafe { mem::transmute(self) }
2820	}
2821
2822	/// Create a native endian integer value from its representation
2823	/// as a byte array in big endian.
2824	///
2825	#[doc = $from_xe_bytes_doc]
2826	///
2827	/// # Examples
2828	///
2829	/// ```
2830	#[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")]
2831	#[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2832	/// ```
2833	///
2834	/// When starting from a slice rather than an array, fallible conversion APIs can be used:
2835	///
2836	/// ```
2837	#[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2838	#[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2839	/// input = rest;*
2840	#[doc = concat!(" ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")]
2841	/// }
2842	/// ```
2843	#[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2844	#[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2845	#[must_use]
2846	#[inline]
2847	pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2848	Self::from_be(Self::from_ne_bytes(bytes))
2849	}
2850
2851	/// Create a native endian integer value from its representation
2852	/// as a byte array in little endian.
2853	///
2854	#[doc = $from_xe_bytes_doc]
2855	///
2856	/// # Examples
2857	///
2858	/// ```
2859	#[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")]
2860	#[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2861	/// ```
2862	///
2863	/// When starting from a slice rather than an array, fallible conversion APIs can be used:
2864	///
2865	/// ```
2866	#[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2867	#[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2868	/// input = rest;*
2869	#[doc = concat!(" ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")]
2870	/// }
2871	/// ```
2872	#[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2873	#[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2874	#[must_use]
2875	#[inline]
2876	pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2877	Self::from_le(Self::from_ne_bytes(bytes))
2878	}
2879
2880	/// Create a native endian integer value from its memory representation
2881	/// as a byte array in native endianness.
2882	///
2883	/// As the target platform's native endianness is used, portable code
2884	/// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as
2885	/// appropriate instead.
2886	///
2887	/// [`from_be_bytes`]: Self::from_be_bytes
2888	/// [`from_le_bytes`]: Self::from_le_bytes
2889	///
2890	#[doc = $from_xe_bytes_doc]
2891	///
2892	/// # Examples
2893	///
2894	/// ```
2895	#[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = `\"`big`\"`) {")]
2896	#[doc = concat!(" ", $be_bytes, "")]
2897	/// } else {
2898	#[doc = concat!(" ", $le_bytes, "")]
2899	/// });
2900	#[doc = concat!("assert_eq!(value, ", $swap_op, ");")]
2901	/// ```
2902	///
2903	/// When starting from a slice rather than an array, fallible conversion APIs can be used:
2904	///
2905	/// ```
2906	#[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")]
2907	#[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")]
2908	/// input = rest;*
2909	#[doc = concat!(" ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")]
2910	/// }
2911	/// ```
2912	#[stable(feature = "int_to_from_bytes", since = "1.32.0")]
2913	#[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")]
2914	#[must_use]
2915	// SAFETY: const sound because integers are plain old datatypes so we can always
2916	// transmute to them
2917	#[inline]
2918	pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self {
2919	// SAFETY: integers are plain old datatypes so we can always transmute to them
2920	unsafe { mem::transmute(bytes) }
2921	}
2922
2923	/// New code should prefer to use
2924	#[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")]
2925	///
2926	/// Returns the smallest value that can be represented by this integer type.
2927	#[stable(feature = "rust1", since = "1.0.0")]
2928	#[rustc_promotable]
2929	#[inline(always)]
2930	#[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2931	#[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")]
2932	pub const fn min_value() -> Self { Self::MIN }
2933
2934	/// New code should prefer to use
2935	#[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")]
2936	///
2937	/// Returns the largest value that can be represented by this integer type.
2938	#[stable(feature = "rust1", since = "1.0.0")]
2939	#[rustc_promotable]
2940	#[inline(always)]
2941	#[rustc_const_stable(feature = "const_max_value", since = "1.32.0")]
2942	#[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")]
2943	pub const fn max_value() -> Self { Self::MAX }
2944	}
2945	}
2946