]>
Commit | Line | Data |
---|---|---|
1b1a35ee | 1 | macro_rules! int_impl { |
5869c6ff XL |
2 | ($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, |
3 | $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr, | |
1b1a35ee XL |
4 | $reversed:expr, $le_bytes:expr, $be_bytes:expr, |
5 | $to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => { | |
5869c6ff XL |
6 | /// The smallest value that can be represented by this integer type. |
7 | /// | |
8 | /// # Examples | |
9 | /// | |
10 | /// Basic usage: | |
11 | /// | |
12 | /// ``` | |
13 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, ", stringify!($Min), ");")] | |
14 | /// ``` | |
15 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
16 | pub const MIN: Self = !0 ^ ((!0 as $UnsignedT) >> 1) as Self; | |
17 | ||
18 | /// The largest value that can be represented by this integer type. | |
19 | /// | |
20 | /// # Examples | |
21 | /// | |
22 | /// Basic usage: | |
23 | /// | |
24 | /// ``` | |
25 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($Max), ");")] | |
26 | /// ``` | |
27 | #[stable(feature = "assoc_int_consts", since = "1.43.0")] | |
28 | pub const MAX: Self = !Self::MIN; | |
29 | ||
30 | /// The size of this integer type in bits. | |
31 | /// | |
32 | /// # Examples | |
33 | /// | |
34 | /// ``` | |
35 | /// #![feature(int_bits_const)] | |
36 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")] | |
37 | /// ``` | |
38 | #[unstable(feature = "int_bits_const", issue = "76904")] | |
39 | pub const BITS: u32 = $BITS; | |
40 | ||
41 | /// Converts a string slice in a given base to an integer. | |
42 | /// | |
43 | /// The string is expected to be an optional `+` or `-` sign followed by digits. | |
44 | /// Leading and trailing whitespace represent an error. Digits are a subset of these characters, | |
45 | /// depending on `radix`: | |
46 | /// | |
47 | /// * `0-9` | |
48 | /// * `a-z` | |
49 | /// * `A-Z` | |
50 | /// | |
51 | /// # Panics | |
52 | /// | |
53 | /// This function panics if `radix` is not in the range from 2 to 36. | |
54 | /// | |
55 | /// # Examples | |
56 | /// | |
57 | /// Basic usage: | |
58 | /// | |
59 | /// ``` | |
60 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::from_str_radix(\"A\", 16), Ok(10));")] | |
61 | /// ``` | |
62 | #[stable(feature = "rust1", since = "1.0.0")] | |
63 | pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError> { | |
64 | from_str_radix(src, radix) | |
65 | } | |
66 | ||
67 | /// Returns the number of ones in the binary representation of `self`. | |
68 | /// | |
69 | /// # Examples | |
70 | /// | |
71 | /// Basic usage: | |
72 | /// | |
73 | /// ``` | |
74 | #[doc = concat!("let n = 0b100_0000", stringify!($SelfT), ";")] | |
75 | /// | |
76 | /// assert_eq!(n.count_ones(), 1); | |
77 | /// ``` | |
78 | /// | |
79 | #[stable(feature = "rust1", since = "1.0.0")] | |
80 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
81 | #[doc(alias = "popcount")] | |
82 | #[doc(alias = "popcnt")] | |
83 | #[inline] | |
84 | pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() } | |
85 | ||
86 | /// Returns the number of zeros in the binary representation of `self`. | |
87 | /// | |
88 | /// # Examples | |
89 | /// | |
90 | /// Basic usage: | |
91 | /// | |
92 | /// ``` | |
93 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 1);")] | |
94 | /// ``` | |
95 | #[stable(feature = "rust1", since = "1.0.0")] | |
96 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
97 | #[inline] | |
98 | pub const fn count_zeros(self) -> u32 { | |
99 | (!self).count_ones() | |
100 | } | |
101 | ||
102 | /// Returns the number of leading zeros in the binary representation of `self`. | |
103 | /// | |
104 | /// # Examples | |
105 | /// | |
106 | /// Basic usage: | |
107 | /// | |
108 | /// ``` | |
109 | #[doc = concat!("let n = -1", stringify!($SelfT), ";")] | |
110 | /// | |
111 | /// assert_eq!(n.leading_zeros(), 0); | |
112 | /// ``` | |
113 | #[stable(feature = "rust1", since = "1.0.0")] | |
114 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
115 | #[inline] | |
116 | pub const fn leading_zeros(self) -> u32 { | |
117 | (self as $UnsignedT).leading_zeros() | |
118 | } | |
119 | ||
120 | /// Returns the number of trailing zeros in the binary representation of `self`. | |
121 | /// | |
122 | /// # Examples | |
123 | /// | |
124 | /// Basic usage: | |
125 | /// | |
126 | /// ``` | |
127 | #[doc = concat!("let n = -4", stringify!($SelfT), ";")] | |
128 | /// | |
129 | /// assert_eq!(n.trailing_zeros(), 2); | |
130 | /// ``` | |
131 | #[stable(feature = "rust1", since = "1.0.0")] | |
132 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
133 | #[inline] | |
134 | pub const fn trailing_zeros(self) -> u32 { | |
135 | (self as $UnsignedT).trailing_zeros() | |
136 | } | |
137 | ||
138 | /// Returns the number of leading ones in the binary representation of `self`. | |
139 | /// | |
140 | /// # Examples | |
141 | /// | |
142 | /// Basic usage: | |
143 | /// | |
144 | /// ``` | |
145 | #[doc = concat!("let n = -1", stringify!($SelfT), ";")] | |
146 | /// | |
147 | #[doc = concat!("assert_eq!(n.leading_ones(), ", stringify!($BITS), ");")] | |
148 | /// ``` | |
149 | #[stable(feature = "leading_trailing_ones", since = "1.46.0")] | |
150 | #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")] | |
151 | #[inline] | |
152 | pub const fn leading_ones(self) -> u32 { | |
153 | (self as $UnsignedT).leading_ones() | |
154 | } | |
155 | ||
156 | /// Returns the number of trailing ones in the binary representation of `self`. | |
157 | /// | |
158 | /// # Examples | |
159 | /// | |
160 | /// Basic usage: | |
161 | /// | |
162 | /// ``` | |
163 | #[doc = concat!("let n = 3", stringify!($SelfT), ";")] | |
164 | /// | |
165 | /// assert_eq!(n.trailing_ones(), 2); | |
166 | /// ``` | |
167 | #[stable(feature = "leading_trailing_ones", since = "1.46.0")] | |
168 | #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")] | |
169 | #[inline] | |
170 | pub const fn trailing_ones(self) -> u32 { | |
171 | (self as $UnsignedT).trailing_ones() | |
172 | } | |
173 | ||
174 | /// Shifts the bits to the left by a specified amount, `n`, | |
175 | /// wrapping the truncated bits to the end of the resulting integer. | |
176 | /// | |
177 | /// Please note this isn't the same operation as the `<<` shifting operator! | |
178 | /// | |
179 | /// # Examples | |
180 | /// | |
181 | /// Basic usage: | |
182 | /// | |
183 | /// ``` | |
184 | #[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")] | |
185 | #[doc = concat!("let m = ", $rot_result, ";")] | |
186 | /// | |
187 | #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")] | |
188 | /// ``` | |
189 | #[stable(feature = "rust1", since = "1.0.0")] | |
190 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
191 | #[must_use = "this returns the result of the operation, \ | |
192 | without modifying the original"] | |
193 | #[inline] | |
194 | pub const fn rotate_left(self, n: u32) -> Self { | |
195 | (self as $UnsignedT).rotate_left(n) as Self | |
196 | } | |
197 | ||
198 | /// Shifts the bits to the right by a specified amount, `n`, | |
199 | /// wrapping the truncated bits to the beginning of the resulting | |
200 | /// integer. | |
201 | /// | |
202 | /// Please note this isn't the same operation as the `>>` shifting operator! | |
203 | /// | |
204 | /// # Examples | |
205 | /// | |
206 | /// Basic usage: | |
207 | /// | |
208 | /// ``` | |
209 | #[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")] | |
210 | #[doc = concat!("let m = ", $rot_op, ";")] | |
211 | /// | |
212 | #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")] | |
213 | /// ``` | |
214 | #[stable(feature = "rust1", since = "1.0.0")] | |
215 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
216 | #[must_use = "this returns the result of the operation, \ | |
217 | without modifying the original"] | |
218 | #[inline] | |
219 | pub const fn rotate_right(self, n: u32) -> Self { | |
220 | (self as $UnsignedT).rotate_right(n) as Self | |
221 | } | |
222 | ||
223 | /// Reverses the byte order of the integer. | |
224 | /// | |
225 | /// # Examples | |
226 | /// | |
227 | /// Basic usage: | |
228 | /// | |
229 | /// ``` | |
230 | #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")] | |
231 | /// | |
232 | /// let m = n.swap_bytes(); | |
233 | /// | |
234 | #[doc = concat!("assert_eq!(m, ", $swapped, ");")] | |
235 | /// ``` | |
236 | #[stable(feature = "rust1", since = "1.0.0")] | |
237 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
238 | #[inline] | |
239 | pub const fn swap_bytes(self) -> Self { | |
240 | (self as $UnsignedT).swap_bytes() as Self | |
241 | } | |
242 | ||
243 | /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit, | |
244 | /// second least-significant bit becomes second most-significant bit, etc. | |
245 | /// | |
246 | /// # Examples | |
247 | /// | |
248 | /// Basic usage: | |
249 | /// | |
250 | /// ``` | |
251 | #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")] | |
252 | /// let m = n.reverse_bits(); | |
253 | /// | |
254 | #[doc = concat!("assert_eq!(m, ", $reversed, ");")] | |
255 | #[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")] | |
256 | /// ``` | |
257 | #[stable(feature = "reverse_bits", since = "1.37.0")] | |
258 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
259 | #[inline] | |
260 | #[must_use] | |
261 | pub const fn reverse_bits(self) -> Self { | |
262 | (self as $UnsignedT).reverse_bits() as Self | |
263 | } | |
264 | ||
265 | /// Converts an integer from big endian to the target's endianness. | |
266 | /// | |
267 | /// On big endian this is a no-op. On little endian the bytes are swapped. | |
268 | /// | |
269 | /// # Examples | |
270 | /// | |
271 | /// Basic usage: | |
272 | /// | |
273 | /// ``` | |
274 | #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] | |
275 | /// | |
276 | /// if cfg!(target_endian = "big") { | |
277 | #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n)")] | |
278 | /// } else { | |
279 | #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")] | |
280 | /// } | |
281 | /// ``` | |
282 | #[stable(feature = "rust1", since = "1.0.0")] | |
283 | #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] | |
284 | #[inline] | |
285 | pub const fn from_be(x: Self) -> Self { | |
286 | #[cfg(target_endian = "big")] | |
287 | { | |
288 | x | |
289 | } | |
290 | #[cfg(not(target_endian = "big"))] | |
291 | { | |
292 | x.swap_bytes() | |
293 | } | |
294 | } | |
295 | ||
296 | /// Converts an integer from little endian to the target's endianness. | |
297 | /// | |
298 | /// On little endian this is a no-op. On big endian the bytes are swapped. | |
299 | /// | |
300 | /// # Examples | |
301 | /// | |
302 | /// Basic usage: | |
303 | /// | |
304 | /// ``` | |
305 | #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] | |
306 | /// | |
307 | /// if cfg!(target_endian = "little") { | |
308 | #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n)")] | |
309 | /// } else { | |
310 | #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")] | |
311 | /// } | |
312 | /// ``` | |
313 | #[stable(feature = "rust1", since = "1.0.0")] | |
314 | #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] | |
315 | #[inline] | |
316 | pub const fn from_le(x: Self) -> Self { | |
317 | #[cfg(target_endian = "little")] | |
318 | { | |
319 | x | |
320 | } | |
321 | #[cfg(not(target_endian = "little"))] | |
322 | { | |
323 | x.swap_bytes() | |
324 | } | |
325 | } | |
326 | ||
327 | /// Converts `self` to big endian from the target's endianness. | |
328 | /// | |
329 | /// On big endian this is a no-op. On little endian the bytes are swapped. | |
330 | /// | |
331 | /// # Examples | |
332 | /// | |
333 | /// Basic usage: | |
334 | /// | |
335 | /// ``` | |
336 | #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] | |
337 | /// | |
338 | /// if cfg!(target_endian = "big") { | |
339 | /// assert_eq!(n.to_be(), n) | |
340 | /// } else { | |
341 | /// assert_eq!(n.to_be(), n.swap_bytes()) | |
342 | /// } | |
343 | /// ``` | |
344 | #[stable(feature = "rust1", since = "1.0.0")] | |
345 | #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] | |
346 | #[inline] | |
347 | pub const fn to_be(self) -> Self { // or not to be? | |
348 | #[cfg(target_endian = "big")] | |
349 | { | |
350 | self | |
351 | } | |
352 | #[cfg(not(target_endian = "big"))] | |
353 | { | |
354 | self.swap_bytes() | |
355 | } | |
356 | } | |
357 | ||
358 | /// Converts `self` to little endian from the target's endianness. | |
359 | /// | |
360 | /// On little endian this is a no-op. On big endian the bytes are swapped. | |
361 | /// | |
362 | /// # Examples | |
363 | /// | |
364 | /// Basic usage: | |
365 | /// | |
366 | /// ``` | |
367 | #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] | |
368 | /// | |
369 | /// if cfg!(target_endian = "little") { | |
370 | /// assert_eq!(n.to_le(), n) | |
371 | /// } else { | |
372 | /// assert_eq!(n.to_le(), n.swap_bytes()) | |
373 | /// } | |
374 | /// ``` | |
375 | #[stable(feature = "rust1", since = "1.0.0")] | |
376 | #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] | |
377 | #[inline] | |
378 | pub const fn to_le(self) -> Self { | |
379 | #[cfg(target_endian = "little")] | |
380 | { | |
381 | self | |
382 | } | |
383 | #[cfg(not(target_endian = "little"))] | |
384 | { | |
385 | self.swap_bytes() | |
386 | } | |
387 | } | |
388 | ||
389 | /// Checked integer addition. Computes `self + rhs`, returning `None` | |
390 | /// if overflow occurred. | |
391 | /// | |
392 | /// # Examples | |
393 | /// | |
394 | /// Basic usage: | |
395 | /// | |
396 | /// ``` | |
397 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), Some(", stringify!($SelfT), "::MAX - 1));")] | |
398 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")] | |
399 | /// ``` | |
400 | #[stable(feature = "rust1", since = "1.0.0")] | |
401 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
402 | #[must_use = "this returns the result of the operation, \ | |
403 | without modifying the original"] | |
404 | #[inline] | |
405 | pub const fn checked_add(self, rhs: Self) -> Option<Self> { | |
406 | let (a, b) = self.overflowing_add(rhs); | |
407 | if unlikely!(b) {None} else {Some(a)} | |
408 | } | |
409 | ||
410 | /// Unchecked integer addition. Computes `self + rhs`, assuming overflow | |
411 | /// cannot occur. This results in undefined behavior when | |
412 | #[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`.")] | |
413 | #[unstable( | |
414 | feature = "unchecked_math", | |
415 | reason = "niche optimization path", | |
416 | issue = "none", | |
417 | )] | |
418 | #[must_use = "this returns the result of the operation, \ | |
419 | without modifying the original"] | |
420 | #[inline] | |
421 | pub unsafe fn unchecked_add(self, rhs: Self) -> Self { | |
422 | // SAFETY: the caller must uphold the safety contract for | |
423 | // `unchecked_add`. | |
424 | unsafe { intrinsics::unchecked_add(self, rhs) } | |
425 | } | |
426 | ||
427 | /// Checked integer subtraction. Computes `self - rhs`, returning `None` if | |
428 | /// overflow occurred. | |
429 | /// | |
430 | /// # Examples | |
431 | /// | |
432 | /// Basic usage: | |
433 | /// | |
434 | /// ``` | |
435 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(1), Some(", stringify!($SelfT), "::MIN + 1));")] | |
436 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(3), None);")] | |
437 | /// ``` | |
438 | #[stable(feature = "rust1", since = "1.0.0")] | |
439 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
440 | #[must_use = "this returns the result of the operation, \ | |
441 | without modifying the original"] | |
442 | #[inline] | |
443 | pub const fn checked_sub(self, rhs: Self) -> Option<Self> { | |
444 | let (a, b) = self.overflowing_sub(rhs); | |
445 | if unlikely!(b) {None} else {Some(a)} | |
446 | } | |
447 | ||
448 | /// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow | |
449 | /// cannot occur. This results in undefined behavior when | |
450 | #[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`.")] | |
451 | #[unstable( | |
452 | feature = "unchecked_math", | |
453 | reason = "niche optimization path", | |
454 | issue = "none", | |
455 | )] | |
456 | #[must_use = "this returns the result of the operation, \ | |
457 | without modifying the original"] | |
458 | #[inline] | |
459 | pub unsafe fn unchecked_sub(self, rhs: Self) -> Self { | |
460 | // SAFETY: the caller must uphold the safety contract for | |
461 | // `unchecked_sub`. | |
462 | unsafe { intrinsics::unchecked_sub(self, rhs) } | |
463 | } | |
464 | ||
465 | /// Checked integer multiplication. Computes `self * rhs`, returning `None` if | |
466 | /// overflow occurred. | |
467 | /// | |
468 | /// # Examples | |
469 | /// | |
470 | /// Basic usage: | |
471 | /// | |
472 | /// ``` | |
473 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(1), Some(", stringify!($SelfT), "::MAX));")] | |
474 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")] | |
475 | /// ``` | |
476 | #[stable(feature = "rust1", since = "1.0.0")] | |
477 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
478 | #[must_use = "this returns the result of the operation, \ | |
479 | without modifying the original"] | |
480 | #[inline] | |
481 | pub const fn checked_mul(self, rhs: Self) -> Option<Self> { | |
482 | let (a, b) = self.overflowing_mul(rhs); | |
483 | if unlikely!(b) {None} else {Some(a)} | |
484 | } | |
485 | ||
486 | /// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow | |
487 | /// cannot occur. This results in undefined behavior when | |
488 | #[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`.")] | |
489 | #[unstable( | |
490 | feature = "unchecked_math", | |
491 | reason = "niche optimization path", | |
492 | issue = "none", | |
493 | )] | |
494 | #[must_use = "this returns the result of the operation, \ | |
495 | without modifying the original"] | |
496 | #[inline] | |
497 | pub unsafe fn unchecked_mul(self, rhs: Self) -> Self { | |
498 | // SAFETY: the caller must uphold the safety contract for | |
499 | // `unchecked_mul`. | |
500 | unsafe { intrinsics::unchecked_mul(self, rhs) } | |
501 | } | |
502 | ||
503 | /// Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0` | |
504 | /// or the division results in overflow. | |
505 | /// | |
506 | /// # Examples | |
507 | /// | |
508 | /// Basic usage: | |
509 | /// | |
510 | /// ``` | |
511 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div(-1), Some(", stringify!($Max), "));")] | |
512 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div(-1), None);")] | |
513 | #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);")] | |
514 | /// ``` | |
515 | #[stable(feature = "rust1", since = "1.0.0")] | |
6a06907d | 516 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.52.0")] |
5869c6ff XL |
517 | #[must_use = "this returns the result of the operation, \ |
518 | without modifying the original"] | |
519 | #[inline] | |
520 | pub const fn checked_div(self, rhs: Self) -> Option<Self> { | |
521 | if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) { | |
522 | None | |
523 | } else { | |
524 | // SAFETY: div by zero and by INT_MIN have been checked above | |
525 | Some(unsafe { intrinsics::unchecked_div(self, rhs) }) | |
526 | } | |
527 | } | |
528 | ||
529 | /// Checked Euclidean division. Computes `self.div_euclid(rhs)`, | |
530 | /// returning `None` if `rhs == 0` or the division results in overflow. | |
531 | /// | |
532 | /// # Examples | |
533 | /// | |
534 | /// Basic usage: | |
535 | /// | |
536 | /// ``` | |
537 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));")] | |
538 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div_euclid(-1), None);")] | |
539 | #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);")] | |
540 | /// ``` | |
541 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 542 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
543 | #[must_use = "this returns the result of the operation, \ |
544 | without modifying the original"] | |
545 | #[inline] | |
546 | pub const fn checked_div_euclid(self, rhs: Self) -> Option<Self> { | |
547 | if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) { | |
548 | None | |
549 | } else { | |
550 | Some(self.div_euclid(rhs)) | |
551 | } | |
552 | } | |
553 | ||
554 | /// Checked integer remainder. Computes `self % rhs`, returning `None` if | |
555 | /// `rhs == 0` or the division results in overflow. | |
556 | /// | |
557 | /// # Examples | |
558 | /// | |
559 | /// Basic usage: | |
560 | /// | |
561 | /// ``` | |
562 | /// | |
563 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")] | |
564 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")] | |
565 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);")] | |
566 | /// ``` | |
567 | #[stable(feature = "wrapping", since = "1.7.0")] | |
6a06907d | 568 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.52.0")] |
5869c6ff XL |
569 | #[must_use = "this returns the result of the operation, \ |
570 | without modifying the original"] | |
571 | #[inline] | |
572 | pub const fn checked_rem(self, rhs: Self) -> Option<Self> { | |
573 | if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) { | |
574 | None | |
575 | } else { | |
576 | // SAFETY: div by zero and by INT_MIN have been checked above | |
577 | Some(unsafe { intrinsics::unchecked_rem(self, rhs) }) | |
578 | } | |
579 | } | |
580 | ||
581 | /// Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None` | |
582 | /// if `rhs == 0` or the division results in overflow. | |
583 | /// | |
584 | /// # Examples | |
585 | /// | |
586 | /// Basic usage: | |
587 | /// | |
588 | /// ``` | |
589 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")] | |
590 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")] | |
591 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);")] | |
592 | /// ``` | |
593 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 594 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
595 | #[must_use = "this returns the result of the operation, \ |
596 | without modifying the original"] | |
597 | #[inline] | |
598 | pub const fn checked_rem_euclid(self, rhs: Self) -> Option<Self> { | |
599 | if unlikely!(rhs == 0 || (self == Self::MIN && rhs == -1)) { | |
600 | None | |
601 | } else { | |
602 | Some(self.rem_euclid(rhs)) | |
603 | } | |
604 | } | |
605 | ||
606 | /// Checked negation. Computes `-self`, returning `None` if `self == MIN`. | |
607 | /// | |
608 | /// # Examples | |
609 | /// | |
610 | /// Basic usage: | |
611 | /// | |
612 | /// ``` | |
613 | /// | |
614 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));")] | |
615 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);")] | |
616 | /// ``` | |
617 | #[stable(feature = "wrapping", since = "1.7.0")] | |
618 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
619 | #[inline] | |
620 | pub const fn checked_neg(self) -> Option<Self> { | |
621 | let (a, b) = self.overflowing_neg(); | |
622 | if unlikely!(b) {None} else {Some(a)} | |
623 | } | |
624 | ||
625 | /// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger | |
626 | /// than or equal to the number of bits in `self`. | |
627 | /// | |
628 | /// # Examples | |
629 | /// | |
630 | /// Basic usage: | |
631 | /// | |
632 | /// ``` | |
633 | #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")] | |
634 | #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);")] | |
635 | /// ``` | |
636 | #[stable(feature = "wrapping", since = "1.7.0")] | |
637 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
638 | #[must_use = "this returns the result of the operation, \ | |
639 | without modifying the original"] | |
640 | #[inline] | |
641 | pub const fn checked_shl(self, rhs: u32) -> Option<Self> { | |
642 | let (a, b) = self.overflowing_shl(rhs); | |
643 | if unlikely!(b) {None} else {Some(a)} | |
644 | } | |
645 | ||
646 | /// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is | |
647 | /// larger than or equal to the number of bits in `self`. | |
648 | /// | |
649 | /// # Examples | |
650 | /// | |
651 | /// Basic usage: | |
652 | /// | |
653 | /// ``` | |
654 | #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")] | |
655 | #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);")] | |
656 | /// ``` | |
657 | #[stable(feature = "wrapping", since = "1.7.0")] | |
658 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
659 | #[must_use = "this returns the result of the operation, \ | |
660 | without modifying the original"] | |
661 | #[inline] | |
662 | pub const fn checked_shr(self, rhs: u32) -> Option<Self> { | |
663 | let (a, b) = self.overflowing_shr(rhs); | |
664 | if unlikely!(b) {None} else {Some(a)} | |
665 | } | |
666 | ||
667 | /// Checked absolute value. Computes `self.abs()`, returning `None` if | |
668 | /// `self == MIN`. | |
669 | /// | |
670 | /// # Examples | |
671 | /// | |
672 | /// Basic usage: | |
673 | /// | |
674 | /// ``` | |
675 | /// | |
676 | #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));")] | |
677 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);")] | |
678 | /// ``` | |
679 | #[stable(feature = "no_panic_abs", since = "1.13.0")] | |
680 | #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] | |
681 | #[inline] | |
682 | pub const fn checked_abs(self) -> Option<Self> { | |
683 | if self.is_negative() { | |
684 | self.checked_neg() | |
685 | } else { | |
686 | Some(self) | |
687 | } | |
688 | } | |
689 | ||
690 | /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if | |
691 | /// overflow occurred. | |
692 | /// | |
693 | /// # Examples | |
694 | /// | |
695 | /// Basic usage: | |
696 | /// | |
697 | /// ``` | |
698 | #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")] | |
699 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")] | |
700 | /// ``` | |
701 | ||
702 | #[stable(feature = "no_panic_pow", since = "1.34.0")] | |
703 | #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] | |
704 | #[must_use = "this returns the result of the operation, \ | |
705 | without modifying the original"] | |
706 | #[inline] | |
707 | pub const fn checked_pow(self, mut exp: u32) -> Option<Self> { | |
708 | if exp == 0 { | |
709 | return Some(1); | |
710 | } | |
711 | let mut base = self; | |
712 | let mut acc: Self = 1; | |
713 | ||
714 | while exp > 1 { | |
715 | if (exp & 1) == 1 { | |
716 | acc = try_opt!(acc.checked_mul(base)); | |
1b1a35ee | 717 | } |
5869c6ff XL |
718 | exp /= 2; |
719 | base = try_opt!(base.checked_mul(base)); | |
720 | } | |
721 | // since exp!=0, finally the exp must be 1. | |
722 | // Deal with the final bit of the exponent separately, since | |
723 | // squaring the base afterwards is not necessary and may cause a | |
724 | // needless overflow. | |
725 | Some(try_opt!(acc.checked_mul(base))) | |
726 | } | |
727 | ||
728 | /// Saturating integer addition. Computes `self + rhs`, saturating at the numeric | |
729 | /// bounds instead of overflowing. | |
730 | /// | |
731 | /// # Examples | |
732 | /// | |
733 | /// Basic usage: | |
734 | /// | |
735 | /// ``` | |
736 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")] | |
737 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(100), ", stringify!($SelfT), "::MAX);")] | |
738 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_add(-1), ", stringify!($SelfT), "::MIN);")] | |
739 | /// ``` | |
740 | ||
741 | #[stable(feature = "rust1", since = "1.0.0")] | |
742 | #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] | |
743 | #[must_use = "this returns the result of the operation, \ | |
744 | without modifying the original"] | |
745 | #[inline] | |
746 | pub const fn saturating_add(self, rhs: Self) -> Self { | |
747 | intrinsics::saturating_add(self, rhs) | |
748 | } | |
749 | ||
750 | /// Saturating integer subtraction. Computes `self - rhs`, saturating at the | |
751 | /// numeric bounds instead of overflowing. | |
752 | /// | |
753 | /// # Examples | |
754 | /// | |
755 | /// Basic usage: | |
756 | /// | |
757 | /// ``` | |
758 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);")] | |
759 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub(100), ", stringify!($SelfT), "::MIN);")] | |
760 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_sub(-1), ", stringify!($SelfT), "::MAX);")] | |
761 | /// ``` | |
762 | #[stable(feature = "rust1", since = "1.0.0")] | |
763 | #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] | |
764 | #[must_use = "this returns the result of the operation, \ | |
765 | without modifying the original"] | |
766 | #[inline] | |
767 | pub const fn saturating_sub(self, rhs: Self) -> Self { | |
768 | intrinsics::saturating_sub(self, rhs) | |
769 | } | |
770 | ||
771 | /// Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN` | |
772 | /// instead of overflowing. | |
773 | /// | |
774 | /// # Examples | |
775 | /// | |
776 | /// Basic usage: | |
777 | /// | |
778 | /// ``` | |
779 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);")] | |
780 | #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);")] | |
781 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_neg(), ", stringify!($SelfT), "::MAX);")] | |
782 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_neg(), ", stringify!($SelfT), "::MIN + 1);")] | |
783 | /// ``` | |
784 | ||
785 | #[stable(feature = "saturating_neg", since = "1.45.0")] | |
786 | #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] | |
787 | #[inline] | |
788 | pub const fn saturating_neg(self) -> Self { | |
789 | intrinsics::saturating_sub(0, self) | |
790 | } | |
791 | ||
792 | /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self == | |
793 | /// MIN` instead of overflowing. | |
794 | /// | |
795 | /// # Examples | |
796 | /// | |
797 | /// Basic usage: | |
798 | /// | |
799 | /// ``` | |
800 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);")] | |
801 | #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);")] | |
802 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_abs(), ", stringify!($SelfT), "::MAX);")] | |
803 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).saturating_abs(), ", stringify!($SelfT), "::MAX);")] | |
804 | /// ``` | |
805 | ||
806 | #[stable(feature = "saturating_neg", since = "1.45.0")] | |
807 | #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] | |
808 | #[inline] | |
809 | pub const fn saturating_abs(self) -> Self { | |
810 | if self.is_negative() { | |
811 | self.saturating_neg() | |
812 | } else { | |
813 | self | |
814 | } | |
815 | } | |
816 | ||
817 | /// Saturating integer multiplication. Computes `self * rhs`, saturating at the | |
818 | /// numeric bounds instead of overflowing. | |
819 | /// | |
820 | /// # Examples | |
821 | /// | |
822 | /// Basic usage: | |
823 | /// | |
824 | /// ``` | |
825 | /// | |
826 | #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);")] | |
827 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);")] | |
828 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);")] | |
829 | /// ``` | |
830 | #[stable(feature = "wrapping", since = "1.7.0")] | |
831 | #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] | |
832 | #[must_use = "this returns the result of the operation, \ | |
833 | without modifying the original"] | |
834 | #[inline] | |
835 | pub const fn saturating_mul(self, rhs: Self) -> Self { | |
836 | match self.checked_mul(rhs) { | |
837 | Some(x) => x, | |
838 | None => if (self < 0) == (rhs < 0) { | |
839 | Self::MAX | |
1b1a35ee | 840 | } else { |
5869c6ff | 841 | Self::MIN |
1b1a35ee XL |
842 | } |
843 | } | |
844 | } | |
845 | ||
5869c6ff XL |
846 | /// Saturating integer exponentiation. Computes `self.pow(exp)`, |
847 | /// saturating at the numeric bounds instead of overflowing. | |
848 | /// | |
849 | /// # Examples | |
850 | /// | |
851 | /// Basic usage: | |
852 | /// | |
853 | /// ``` | |
854 | /// | |
855 | #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")] | |
856 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")] | |
857 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")] | |
858 | /// ``` | |
859 | #[stable(feature = "no_panic_pow", since = "1.34.0")] | |
860 | #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] | |
861 | #[must_use = "this returns the result of the operation, \ | |
862 | without modifying the original"] | |
863 | #[inline] | |
864 | pub const fn saturating_pow(self, exp: u32) -> Self { | |
865 | match self.checked_pow(exp) { | |
866 | Some(x) => x, | |
867 | None if self < 0 && exp % 2 == 1 => Self::MIN, | |
868 | None => Self::MAX, | |
869 | } | |
870 | } | |
871 | ||
872 | /// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the | |
873 | /// boundary of the type. | |
874 | /// | |
875 | /// # Examples | |
876 | /// | |
877 | /// Basic usage: | |
878 | /// | |
879 | /// ``` | |
880 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);")] | |
881 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT), "::MIN + 1);")] | |
882 | /// ``` | |
883 | #[stable(feature = "rust1", since = "1.0.0")] | |
884 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
885 | #[must_use = "this returns the result of the operation, \ | |
886 | without modifying the original"] | |
887 | #[inline] | |
888 | pub const fn wrapping_add(self, rhs: Self) -> Self { | |
889 | intrinsics::wrapping_add(self, rhs) | |
890 | } | |
891 | ||
892 | /// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the | |
893 | /// boundary of the type. | |
894 | /// | |
895 | /// # Examples | |
896 | /// | |
897 | /// Basic usage: | |
898 | /// | |
899 | /// ``` | |
900 | #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);")] | |
901 | #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ", stringify!($SelfT), "::MAX);")] | |
902 | /// ``` | |
903 | #[stable(feature = "rust1", since = "1.0.0")] | |
904 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
905 | #[must_use = "this returns the result of the operation, \ | |
906 | without modifying the original"] | |
907 | #[inline] | |
908 | pub const fn wrapping_sub(self, rhs: Self) -> Self { | |
909 | intrinsics::wrapping_sub(self, rhs) | |
910 | } | |
911 | ||
912 | /// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at | |
913 | /// the boundary of the type. | |
914 | /// | |
915 | /// # Examples | |
916 | /// | |
917 | /// Basic usage: | |
918 | /// | |
919 | /// ``` | |
920 | #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);")] | |
921 | /// assert_eq!(11i8.wrapping_mul(12), -124); | |
922 | /// ``` | |
923 | #[stable(feature = "rust1", since = "1.0.0")] | |
924 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
925 | #[must_use = "this returns the result of the operation, \ | |
926 | without modifying the original"] | |
927 | #[inline] | |
928 | pub const fn wrapping_mul(self, rhs: Self) -> Self { | |
929 | intrinsics::wrapping_mul(self, rhs) | |
930 | } | |
931 | ||
932 | /// Wrapping (modular) division. Computes `self / rhs`, wrapping around at the | |
933 | /// boundary of the type. | |
934 | /// | |
935 | /// The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where | |
936 | /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value | |
937 | /// that is too large to represent in the type. In such a case, this function returns `MIN` itself. | |
938 | /// | |
939 | /// # Panics | |
940 | /// | |
941 | /// This function will panic if `rhs` is 0. | |
942 | /// | |
943 | /// # Examples | |
944 | /// | |
945 | /// Basic usage: | |
946 | /// | |
947 | /// ``` | |
948 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")] | |
949 | /// assert_eq!((-128i8).wrapping_div(-1), -128); | |
950 | /// ``` | |
951 | #[stable(feature = "num_wrapping", since = "1.2.0")] | |
6a06907d | 952 | #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")] |
5869c6ff XL |
953 | #[must_use = "this returns the result of the operation, \ |
954 | without modifying the original"] | |
955 | #[inline] | |
956 | pub const fn wrapping_div(self, rhs: Self) -> Self { | |
957 | self.overflowing_div(rhs).0 | |
958 | } | |
959 | ||
960 | /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`, | |
961 | /// wrapping around at the boundary of the type. | |
962 | /// | |
963 | /// Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value | |
964 | /// for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the | |
965 | /// type. In this case, this method returns `MIN` itself. | |
966 | /// | |
967 | /// # Panics | |
968 | /// | |
969 | /// This function will panic if `rhs` is 0. | |
970 | /// | |
971 | /// # Examples | |
972 | /// | |
973 | /// Basic usage: | |
974 | /// | |
975 | /// ``` | |
976 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")] | |
977 | /// assert_eq!((-128i8).wrapping_div_euclid(-1), -128); | |
978 | /// ``` | |
979 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 980 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
981 | #[must_use = "this returns the result of the operation, \ |
982 | without modifying the original"] | |
983 | #[inline] | |
984 | pub const fn wrapping_div_euclid(self, rhs: Self) -> Self { | |
985 | self.overflowing_div_euclid(rhs).0 | |
986 | } | |
987 | ||
988 | /// Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the | |
989 | /// boundary of the type. | |
990 | /// | |
991 | /// Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y` | |
992 | /// invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case, | |
993 | /// this function returns `0`. | |
994 | /// | |
995 | /// # Panics | |
996 | /// | |
997 | /// This function will panic if `rhs` is 0. | |
998 | /// | |
999 | /// # Examples | |
1000 | /// | |
1001 | /// Basic usage: | |
1002 | /// | |
1003 | /// ``` | |
1004 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")] | |
1005 | /// assert_eq!((-128i8).wrapping_rem(-1), 0); | |
1006 | /// ``` | |
1007 | #[stable(feature = "num_wrapping", since = "1.2.0")] | |
6a06907d | 1008 | #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")] |
5869c6ff XL |
1009 | #[must_use = "this returns the result of the operation, \ |
1010 | without modifying the original"] | |
1011 | #[inline] | |
1012 | pub const fn wrapping_rem(self, rhs: Self) -> Self { | |
1013 | self.overflowing_rem(rhs).0 | |
1014 | } | |
1015 | ||
1016 | /// Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around | |
1017 | /// at the boundary of the type. | |
1018 | /// | |
1019 | /// Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value | |
1020 | /// for the type). In this case, this method returns 0. | |
1021 | /// | |
1022 | /// # Panics | |
1023 | /// | |
1024 | /// This function will panic if `rhs` is 0. | |
1025 | /// | |
1026 | /// # Examples | |
1027 | /// | |
1028 | /// Basic usage: | |
1029 | /// | |
1030 | /// ``` | |
1031 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")] | |
1032 | /// assert_eq!((-128i8).wrapping_rem_euclid(-1), 0); | |
1033 | /// ``` | |
1034 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 1035 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
1036 | #[must_use = "this returns the result of the operation, \ |
1037 | without modifying the original"] | |
1038 | #[inline] | |
1039 | pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self { | |
1040 | self.overflowing_rem_euclid(rhs).0 | |
1041 | } | |
1042 | ||
1043 | /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary | |
1044 | /// of the type. | |
1045 | /// | |
1046 | /// The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN` | |
1047 | /// is the negative minimal value for the type); this is a positive value that is too large to represent | |
1048 | /// in the type. In such a case, this function returns `MIN` itself. | |
1049 | /// | |
1050 | /// # Examples | |
1051 | /// | |
1052 | /// Basic usage: | |
1053 | /// | |
1054 | /// ``` | |
1055 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);")] | |
1056 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT), "::MIN);")] | |
1057 | /// ``` | |
1058 | #[stable(feature = "num_wrapping", since = "1.2.0")] | |
1059 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1060 | #[inline] | |
1061 | pub const fn wrapping_neg(self) -> Self { | |
1062 | self.overflowing_neg().0 | |
1063 | } | |
1064 | ||
1065 | /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes | |
1066 | /// any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type. | |
1067 | /// | |
1068 | /// Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to | |
1069 | /// the range of the type, rather than the bits shifted out of the LHS being returned to the other end. | |
6a06907d | 1070 | /// The primitive integer types all implement a [`rotate_left`](Self::rotate_left) function, |
5869c6ff XL |
1071 | /// which may be what you want instead. |
1072 | /// | |
1073 | /// # Examples | |
1074 | /// | |
1075 | /// Basic usage: | |
1076 | /// | |
1077 | /// ``` | |
1078 | #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);")] | |
1079 | #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);")] | |
1080 | /// ``` | |
1081 | #[stable(feature = "num_wrapping", since = "1.2.0")] | |
1082 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1083 | #[must_use = "this returns the result of the operation, \ | |
1084 | without modifying the original"] | |
1085 | #[inline] | |
1086 | pub const fn wrapping_shl(self, rhs: u32) -> Self { | |
1087 | // SAFETY: the masking by the bitsize of the type ensures that we do not shift | |
1088 | // out of bounds | |
1089 | unsafe { | |
1090 | intrinsics::unchecked_shl(self, (rhs & ($BITS - 1)) as $SelfT) | |
1091 | } | |
1092 | } | |
1093 | ||
1094 | /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask` | |
1095 | /// removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type. | |
1096 | /// | |
1097 | /// Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted | |
1098 | /// to the range of the type, rather than the bits shifted out of the LHS being returned to the other | |
6a06907d | 1099 | /// end. The primitive integer types all implement a [`rotate_right`](Self::rotate_right) function, |
5869c6ff XL |
1100 | /// which may be what you want instead. |
1101 | /// | |
1102 | /// # Examples | |
1103 | /// | |
1104 | /// Basic usage: | |
1105 | /// | |
1106 | /// ``` | |
1107 | #[doc = concat!("assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);")] | |
1108 | /// assert_eq!((-128i16).wrapping_shr(64), -128); | |
1109 | /// ``` | |
1110 | #[stable(feature = "num_wrapping", since = "1.2.0")] | |
1111 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1112 | #[must_use = "this returns the result of the operation, \ | |
1113 | without modifying the original"] | |
1114 | #[inline] | |
1115 | pub const fn wrapping_shr(self, rhs: u32) -> Self { | |
1116 | // SAFETY: the masking by the bitsize of the type ensures that we do not shift | |
1117 | // out of bounds | |
1118 | unsafe { | |
1119 | intrinsics::unchecked_shr(self, (rhs & ($BITS - 1)) as $SelfT) | |
1120 | } | |
1121 | } | |
1122 | ||
1123 | /// Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at | |
1124 | /// the boundary of the type. | |
1125 | /// | |
1126 | /// The only case where such wrapping can occur is when one takes the absolute value of the negative | |
1127 | /// minimal value for the type; this is a positive value that is too large to represent in the type. In | |
1128 | /// such a case, this function returns `MIN` itself. | |
1129 | /// | |
1130 | /// # Examples | |
1131 | /// | |
1132 | /// Basic usage: | |
1133 | /// | |
1134 | /// ``` | |
1135 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);")] | |
1136 | #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);")] | |
1137 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT), "::MIN);")] | |
1138 | /// assert_eq!((-128i8).wrapping_abs() as u8, 128); | |
1139 | /// ``` | |
1140 | #[stable(feature = "no_panic_abs", since = "1.13.0")] | |
1141 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1142 | #[allow(unused_attributes)] | |
1143 | #[inline] | |
1144 | pub const fn wrapping_abs(self) -> Self { | |
1145 | if self.is_negative() { | |
1146 | self.wrapping_neg() | |
1147 | } else { | |
1148 | self | |
1149 | } | |
1150 | } | |
1151 | ||
1152 | /// Computes the absolute value of `self` without any wrapping | |
1153 | /// or panicking. | |
1154 | /// | |
1155 | /// | |
1156 | /// # Examples | |
1157 | /// | |
1158 | /// Basic usage: | |
1159 | /// | |
1160 | /// ``` | |
1161 | #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");")] | |
1162 | #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");")] | |
1163 | /// assert_eq!((-128i8).unsigned_abs(), 128u8); | |
1164 | /// ``` | |
1165 | #[stable(feature = "unsigned_abs", since = "1.51.0")] | |
1166 | #[rustc_const_stable(feature = "unsigned_abs", since = "1.51.0")] | |
1167 | #[inline] | |
1168 | pub const fn unsigned_abs(self) -> $UnsignedT { | |
1169 | self.wrapping_abs() as $UnsignedT | |
1170 | } | |
1171 | ||
1172 | /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`, | |
1173 | /// wrapping around at the boundary of the type. | |
1174 | /// | |
1175 | /// # Examples | |
1176 | /// | |
1177 | /// Basic usage: | |
1178 | /// | |
1179 | /// ``` | |
1180 | #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")] | |
1181 | /// assert_eq!(3i8.wrapping_pow(5), -13); | |
1182 | /// assert_eq!(3i8.wrapping_pow(6), -39); | |
1183 | /// ``` | |
1184 | #[stable(feature = "no_panic_pow", since = "1.34.0")] | |
1185 | #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] | |
1186 | #[must_use = "this returns the result of the operation, \ | |
1187 | without modifying the original"] | |
1188 | #[inline] | |
1189 | pub const fn wrapping_pow(self, mut exp: u32) -> Self { | |
1190 | if exp == 0 { | |
1191 | return 1; | |
1192 | } | |
1193 | let mut base = self; | |
1194 | let mut acc: Self = 1; | |
1195 | ||
1196 | while exp > 1 { | |
1197 | if (exp & 1) == 1 { | |
1198 | acc = acc.wrapping_mul(base); | |
1b1a35ee | 1199 | } |
5869c6ff XL |
1200 | exp /= 2; |
1201 | base = base.wrapping_mul(base); | |
1202 | } | |
1203 | ||
1204 | // since exp!=0, finally the exp must be 1. | |
1205 | // Deal with the final bit of the exponent separately, since | |
1206 | // squaring the base afterwards is not necessary and may cause a | |
1207 | // needless overflow. | |
1208 | acc.wrapping_mul(base) | |
1209 | } | |
1210 | ||
1211 | /// Calculates `self` + `rhs` | |
1212 | /// | |
1213 | /// Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would | |
1214 | /// occur. If an overflow would have occurred then the wrapped value is returned. | |
1215 | /// | |
1216 | /// # Examples | |
1217 | /// | |
1218 | /// Basic usage: | |
1219 | /// | |
1220 | /// ``` | |
1221 | /// | |
1222 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")] | |
1223 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT), "::MIN, true));")] | |
1224 | /// ``` | |
1225 | #[stable(feature = "wrapping", since = "1.7.0")] | |
1226 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1227 | #[must_use = "this returns the result of the operation, \ | |
1228 | without modifying the original"] | |
1229 | #[inline] | |
1230 | pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) { | |
1231 | let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT); | |
1232 | (a as Self, b) | |
1233 | } | |
1234 | ||
1235 | /// Calculates `self` - `rhs` | |
1236 | /// | |
1237 | /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow | |
1238 | /// would occur. If an overflow would have occurred then the wrapped value is returned. | |
1239 | /// | |
1240 | /// # Examples | |
1241 | /// | |
1242 | /// Basic usage: | |
1243 | /// | |
1244 | /// ``` | |
1245 | /// | |
1246 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")] | |
1247 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")] | |
1248 | /// ``` | |
1249 | #[stable(feature = "wrapping", since = "1.7.0")] | |
1250 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1251 | #[must_use = "this returns the result of the operation, \ | |
1252 | without modifying the original"] | |
1253 | #[inline] | |
1254 | pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) { | |
1255 | let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT); | |
1256 | (a as Self, b) | |
1257 | } | |
1258 | ||
1259 | /// Calculates the multiplication of `self` and `rhs`. | |
1260 | /// | |
1261 | /// Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow | |
1262 | /// would occur. If an overflow would have occurred then the wrapped value is returned. | |
1263 | /// | |
1264 | /// # Examples | |
1265 | /// | |
1266 | /// Basic usage: | |
1267 | /// | |
1268 | /// ``` | |
1269 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));")] | |
1270 | /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true)); | |
1271 | /// ``` | |
1272 | #[stable(feature = "wrapping", since = "1.7.0")] | |
1273 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1274 | #[must_use = "this returns the result of the operation, \ | |
1275 | without modifying the original"] | |
1276 | #[inline] | |
1277 | pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) { | |
1278 | let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT); | |
1279 | (a as Self, b) | |
1280 | } | |
1281 | ||
1282 | /// Calculates the divisor when `self` is divided by `rhs`. | |
1283 | /// | |
1284 | /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would | |
1285 | /// occur. If an overflow would occur then self is returned. | |
1286 | /// | |
1287 | /// # Panics | |
1288 | /// | |
1289 | /// This function will panic if `rhs` is 0. | |
1290 | /// | |
1291 | /// # Examples | |
1292 | /// | |
1293 | /// Basic usage: | |
1294 | /// | |
1295 | /// ``` | |
1296 | /// | |
1297 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")] | |
1298 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT), "::MIN, true));")] | |
1299 | /// ``` | |
1300 | #[inline] | |
1301 | #[stable(feature = "wrapping", since = "1.7.0")] | |
6a06907d | 1302 | #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] |
5869c6ff XL |
1303 | #[must_use = "this returns the result of the operation, \ |
1304 | without modifying the original"] | |
1305 | pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) { | |
1306 | if unlikely!(self == Self::MIN && rhs == -1) { | |
1307 | (self, true) | |
1308 | } else { | |
1309 | (self / rhs, false) | |
1310 | } | |
1311 | } | |
1312 | ||
1313 | /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`. | |
1314 | /// | |
1315 | /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would | |
1316 | /// occur. If an overflow would occur then `self` is returned. | |
1317 | /// | |
1318 | /// # Panics | |
1319 | /// | |
1320 | /// This function will panic if `rhs` is 0. | |
1321 | /// | |
1322 | /// # Examples | |
1323 | /// | |
1324 | /// Basic usage: | |
1325 | /// | |
1326 | /// ``` | |
1327 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")] | |
1328 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT), "::MIN, true));")] | |
1329 | /// ``` | |
1330 | #[inline] | |
1331 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 1332 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
1333 | #[must_use = "this returns the result of the operation, \ |
1334 | without modifying the original"] | |
1335 | pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) { | |
1336 | if unlikely!(self == Self::MIN && rhs == -1) { | |
1337 | (self, true) | |
1338 | } else { | |
1339 | (self.div_euclid(rhs), false) | |
1340 | } | |
1341 | } | |
1342 | ||
1343 | /// Calculates the remainder when `self` is divided by `rhs`. | |
1344 | /// | |
1345 | /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an | |
1346 | /// arithmetic overflow would occur. If an overflow would occur then 0 is returned. | |
1347 | /// | |
1348 | /// # Panics | |
1349 | /// | |
1350 | /// This function will panic if `rhs` is 0. | |
1351 | /// | |
1352 | /// # Examples | |
1353 | /// | |
1354 | /// Basic usage: | |
1355 | /// | |
1356 | /// ``` | |
1357 | /// | |
1358 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")] | |
1359 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));")] | |
1360 | /// ``` | |
1361 | #[inline] | |
1362 | #[stable(feature = "wrapping", since = "1.7.0")] | |
6a06907d | 1363 | #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] |
5869c6ff XL |
1364 | #[must_use = "this returns the result of the operation, \ |
1365 | without modifying the original"] | |
1366 | pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) { | |
1367 | if unlikely!(self == Self::MIN && rhs == -1) { | |
1368 | (0, true) | |
1369 | } else { | |
1370 | (self % rhs, false) | |
1371 | } | |
1372 | } | |
1373 | ||
1374 | ||
1375 | /// Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`. | |
1376 | /// | |
1377 | /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an | |
1378 | /// arithmetic overflow would occur. If an overflow would occur then 0 is returned. | |
1379 | /// | |
1380 | /// # Panics | |
1381 | /// | |
1382 | /// This function will panic if `rhs` is 0. | |
1383 | /// | |
1384 | /// # Examples | |
1385 | /// | |
1386 | /// Basic usage: | |
1387 | /// | |
1388 | /// ``` | |
1389 | #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")] | |
1390 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));")] | |
1391 | /// ``` | |
1392 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 1393 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
1394 | #[must_use = "this returns the result of the operation, \ |
1395 | without modifying the original"] | |
1396 | #[inline] | |
1397 | pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) { | |
1398 | if unlikely!(self == Self::MIN && rhs == -1) { | |
1399 | (0, true) | |
1400 | } else { | |
1401 | (self.rem_euclid(rhs), false) | |
1402 | } | |
1403 | } | |
1404 | ||
1405 | ||
1406 | /// Negates self, overflowing if this is equal to the minimum value. | |
1407 | /// | |
1408 | /// Returns a tuple of the negated version of self along with a boolean indicating whether an overflow | |
1409 | /// happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the | |
1410 | /// minimum value will be returned again and `true` will be returned for an overflow happening. | |
1411 | /// | |
1412 | /// # Examples | |
1413 | /// | |
1414 | /// Basic usage: | |
1415 | /// | |
1416 | /// ``` | |
1417 | #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));")] | |
1418 | #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT), "::MIN, true));")] | |
1419 | /// ``` | |
1420 | #[inline] | |
1421 | #[stable(feature = "wrapping", since = "1.7.0")] | |
1422 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1423 | #[allow(unused_attributes)] | |
1424 | pub const fn overflowing_neg(self) -> (Self, bool) { | |
1425 | if unlikely!(self == Self::MIN) { | |
1426 | (Self::MIN, true) | |
1427 | } else { | |
1428 | (-self, false) | |
1429 | } | |
1430 | } | |
1431 | ||
1432 | /// Shifts self left by `rhs` bits. | |
1433 | /// | |
1434 | /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift | |
1435 | /// value was larger than or equal to the number of bits. If the shift value is too large, then value is | |
1436 | /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift. | |
1437 | /// | |
1438 | /// # Examples | |
1439 | /// | |
1440 | /// Basic usage: | |
1441 | /// | |
1442 | /// ``` | |
1443 | #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")] | |
1444 | /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true)); | |
1445 | /// ``` | |
1446 | #[stable(feature = "wrapping", since = "1.7.0")] | |
1447 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1448 | #[must_use = "this returns the result of the operation, \ | |
1449 | without modifying the original"] | |
1450 | #[inline] | |
1451 | pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) { | |
1452 | (self.wrapping_shl(rhs), (rhs > ($BITS - 1))) | |
1453 | } | |
1454 | ||
1455 | /// Shifts self right by `rhs` bits. | |
1456 | /// | |
1457 | /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift | |
1458 | /// value was larger than or equal to the number of bits. If the shift value is too large, then value is | |
1459 | /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift. | |
1460 | /// | |
1461 | /// # Examples | |
1462 | /// | |
1463 | /// Basic usage: | |
1464 | /// | |
1465 | /// ``` | |
1466 | #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")] | |
1467 | /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true)); | |
1468 | /// ``` | |
1469 | #[stable(feature = "wrapping", since = "1.7.0")] | |
1470 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1471 | #[must_use = "this returns the result of the operation, \ | |
1472 | without modifying the original"] | |
1473 | #[inline] | |
1474 | pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) { | |
1475 | (self.wrapping_shr(rhs), (rhs > ($BITS - 1))) | |
1476 | } | |
1477 | ||
1478 | /// Computes the absolute value of `self`. | |
1479 | /// | |
1480 | /// Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow | |
1481 | /// happened. If self is the minimum value | |
1482 | #[doc = concat!("(e.g., ", stringify!($SelfT), "::MIN for values of type ", stringify!($SelfT), "),")] | |
1483 | /// then the minimum value will be returned again and true will be returned | |
1484 | /// for an overflow happening. | |
1485 | /// | |
1486 | /// # Examples | |
1487 | /// | |
1488 | /// Basic usage: | |
1489 | /// | |
1490 | /// ``` | |
1491 | #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));")] | |
1492 | #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));")] | |
1493 | #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT), "::MIN, true));")] | |
1494 | /// ``` | |
1495 | #[stable(feature = "no_panic_abs", since = "1.13.0")] | |
1496 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1497 | #[inline] | |
1498 | pub const fn overflowing_abs(self) -> (Self, bool) { | |
1499 | (self.wrapping_abs(), self == Self::MIN) | |
1500 | } | |
1501 | ||
1502 | /// Raises self to the power of `exp`, using exponentiation by squaring. | |
1503 | /// | |
1504 | /// Returns a tuple of the exponentiation along with a bool indicating | |
1505 | /// whether an overflow happened. | |
1506 | /// | |
1507 | /// # Examples | |
1508 | /// | |
1509 | /// Basic usage: | |
1510 | /// | |
1511 | /// ``` | |
1512 | #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")] | |
1513 | /// assert_eq!(3i8.overflowing_pow(5), (-13, true)); | |
1514 | /// ``` | |
1515 | #[stable(feature = "no_panic_pow", since = "1.34.0")] | |
1516 | #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] | |
1517 | #[must_use = "this returns the result of the operation, \ | |
1518 | without modifying the original"] | |
1519 | #[inline] | |
1520 | pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) { | |
1521 | if exp == 0 { | |
1522 | return (1,false); | |
1523 | } | |
1524 | let mut base = self; | |
1525 | let mut acc: Self = 1; | |
1526 | let mut overflown = false; | |
1527 | // Scratch space for storing results of overflowing_mul. | |
1528 | let mut r; | |
1529 | ||
1530 | while exp > 1 { | |
1531 | if (exp & 1) == 1 { | |
1532 | r = acc.overflowing_mul(base); | |
1533 | acc = r.0; | |
1b1a35ee XL |
1534 | overflown |= r.1; |
1535 | } | |
5869c6ff XL |
1536 | exp /= 2; |
1537 | r = base.overflowing_mul(base); | |
1538 | base = r.0; | |
1539 | overflown |= r.1; | |
1540 | } | |
1541 | ||
1542 | // since exp!=0, finally the exp must be 1. | |
1543 | // Deal with the final bit of the exponent separately, since | |
1544 | // squaring the base afterwards is not necessary and may cause a | |
1545 | // needless overflow. | |
1546 | r = acc.overflowing_mul(base); | |
1547 | r.1 |= overflown; | |
1548 | r | |
1549 | } | |
1550 | ||
1551 | /// Raises self to the power of `exp`, using exponentiation by squaring. | |
1552 | /// | |
1553 | /// # Examples | |
1554 | /// | |
1555 | /// Basic usage: | |
1556 | /// | |
1557 | /// ``` | |
1558 | #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")] | |
1559 | /// | |
1560 | /// assert_eq!(x.pow(5), 32); | |
1561 | /// ``` | |
1562 | #[stable(feature = "rust1", since = "1.0.0")] | |
1563 | #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] | |
1564 | #[must_use = "this returns the result of the operation, \ | |
1565 | without modifying the original"] | |
1566 | #[inline] | |
1567 | #[rustc_inherit_overflow_checks] | |
1568 | pub const fn pow(self, mut exp: u32) -> Self { | |
1569 | if exp == 0 { | |
1570 | return 1; | |
1571 | } | |
1572 | let mut base = self; | |
1573 | let mut acc = 1; | |
1574 | ||
1575 | while exp > 1 { | |
1576 | if (exp & 1) == 1 { | |
1577 | acc = acc * base; | |
1b1a35ee | 1578 | } |
5869c6ff XL |
1579 | exp /= 2; |
1580 | base = base * base; | |
1581 | } | |
1582 | ||
1583 | // since exp!=0, finally the exp must be 1. | |
1584 | // Deal with the final bit of the exponent separately, since | |
1585 | // squaring the base afterwards is not necessary and may cause a | |
1586 | // needless overflow. | |
1587 | acc * base | |
1588 | } | |
1589 | ||
1590 | /// Calculates the quotient of Euclidean division of `self` by `rhs`. | |
1591 | /// | |
1592 | /// This computes the integer `n` such that `self = n * rhs + self.rem_euclid(rhs)`, | |
1593 | /// with `0 <= self.rem_euclid(rhs) < rhs`. | |
1594 | /// | |
1595 | /// In other words, the result is `self / rhs` rounded to the integer `n` | |
1596 | /// such that `self >= n * rhs`. | |
1597 | /// If `self > 0`, this is equal to round towards zero (the default in Rust); | |
1598 | /// if `self < 0`, this is equal to round towards +/- infinity. | |
1599 | /// | |
1600 | /// # Panics | |
1601 | /// | |
1602 | /// This function will panic if `rhs` is 0 or the division results in overflow. | |
1603 | /// | |
1604 | /// # Examples | |
1605 | /// | |
1606 | /// Basic usage: | |
1607 | /// | |
1608 | /// ``` | |
1609 | #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")] | |
1610 | /// let b = 4; | |
1611 | /// | |
1612 | /// assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1 | |
1613 | /// assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1 | |
1614 | /// assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2 | |
1615 | /// assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2 | |
1616 | /// ``` | |
1617 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 1618 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
1619 | #[must_use = "this returns the result of the operation, \ |
1620 | without modifying the original"] | |
1621 | #[inline] | |
1622 | #[rustc_inherit_overflow_checks] | |
1623 | pub const fn div_euclid(self, rhs: Self) -> Self { | |
1624 | let q = self / rhs; | |
1625 | if self % rhs < 0 { | |
1626 | return if rhs > 0 { q - 1 } else { q + 1 } | |
1627 | } | |
1628 | q | |
1629 | } | |
1630 | ||
1631 | ||
1632 | /// Calculates the least nonnegative remainder of `self (mod rhs)`. | |
1633 | /// | |
1634 | /// This is done as if by the Euclidean division algorithm -- given | |
1635 | /// `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and | |
1636 | /// `0 <= r < abs(rhs)`. | |
1637 | /// | |
1638 | /// # Panics | |
1639 | /// | |
1640 | /// This function will panic if `rhs` is 0 or the division results in overflow. | |
1641 | /// | |
1642 | /// # Examples | |
1643 | /// | |
1644 | /// Basic usage: | |
1645 | /// | |
1646 | /// ``` | |
1647 | #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")] | |
1648 | /// let b = 4; | |
1649 | /// | |
1650 | /// assert_eq!(a.rem_euclid(b), 3); | |
1651 | /// assert_eq!((-a).rem_euclid(b), 1); | |
1652 | /// assert_eq!(a.rem_euclid(-b), 3); | |
1653 | /// assert_eq!((-a).rem_euclid(-b), 1); | |
1654 | /// ``` | |
1655 | #[stable(feature = "euclidean_division", since = "1.38.0")] | |
6a06907d | 1656 | #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] |
5869c6ff XL |
1657 | #[must_use = "this returns the result of the operation, \ |
1658 | without modifying the original"] | |
1659 | #[inline] | |
1660 | #[rustc_inherit_overflow_checks] | |
1661 | pub const fn rem_euclid(self, rhs: Self) -> Self { | |
1662 | let r = self % rhs; | |
1663 | if r < 0 { | |
1664 | if rhs < 0 { | |
1665 | r - rhs | |
1b1a35ee | 1666 | } else { |
5869c6ff | 1667 | r + rhs |
1b1a35ee | 1668 | } |
5869c6ff XL |
1669 | } else { |
1670 | r | |
1b1a35ee XL |
1671 | } |
1672 | } | |
1673 | ||
5869c6ff XL |
1674 | /// Computes the absolute value of `self`. |
1675 | /// | |
1676 | /// # Overflow behavior | |
1677 | /// | |
1678 | /// The absolute value of | |
1679 | #[doc = concat!("`", stringify!($SelfT), "::MIN`")] | |
1680 | /// cannot be represented as an | |
1681 | #[doc = concat!("`", stringify!($SelfT), "`,")] | |
1682 | /// and attempting to calculate it will cause an overflow. This means | |
1683 | /// that code in debug mode will trigger a panic on this case and | |
1684 | /// optimized code will return | |
1685 | #[doc = concat!("`", stringify!($SelfT), "::MIN`")] | |
1686 | /// without a panic. | |
1687 | /// | |
1688 | /// # Examples | |
1689 | /// | |
1690 | /// Basic usage: | |
1691 | /// | |
1692 | /// ``` | |
1693 | #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".abs(), 10);")] | |
1694 | #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").abs(), 10);")] | |
1695 | /// ``` | |
1696 | #[stable(feature = "rust1", since = "1.0.0")] | |
1697 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1698 | #[allow(unused_attributes)] | |
1699 | #[inline] | |
1700 | #[rustc_inherit_overflow_checks] | |
1701 | pub const fn abs(self) -> Self { | |
1702 | // Note that the #[inline] above means that the overflow | |
1703 | // semantics of the subtraction depend on the crate we're being | |
1704 | // inlined into. | |
1705 | if self.is_negative() { | |
1706 | -self | |
1707 | } else { | |
1708 | self | |
1709 | } | |
1710 | } | |
1711 | ||
1712 | /// Returns a number representing sign of `self`. | |
1713 | /// | |
1714 | /// - `0` if the number is zero | |
1715 | /// - `1` if the number is positive | |
1716 | /// - `-1` if the number is negative | |
1717 | /// | |
1718 | /// # Examples | |
1719 | /// | |
1720 | /// Basic usage: | |
1721 | /// | |
1722 | /// ``` | |
1723 | #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".signum(), 1);")] | |
1724 | #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".signum(), 0);")] | |
1725 | #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").signum(), -1);")] | |
1726 | /// ``` | |
1727 | #[stable(feature = "rust1", since = "1.0.0")] | |
1728 | #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")] | |
1729 | #[inline] | |
1730 | pub const fn signum(self) -> Self { | |
1731 | match self { | |
1732 | n if n > 0 => 1, | |
1733 | 0 => 0, | |
1734 | _ => -1, | |
1735 | } | |
1736 | } | |
1737 | ||
1738 | /// Returns `true` if `self` is positive and `false` if the number is zero or | |
1739 | /// negative. | |
1740 | /// | |
1741 | /// # Examples | |
1742 | /// | |
1743 | /// Basic usage: | |
1744 | /// | |
1745 | /// ``` | |
1746 | #[doc = concat!("assert!(10", stringify!($SelfT), ".is_positive());")] | |
1747 | #[doc = concat!("assert!(!(-10", stringify!($SelfT), ").is_positive());")] | |
1748 | /// ``` | |
1749 | #[stable(feature = "rust1", since = "1.0.0")] | |
1750 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1751 | #[inline] | |
1752 | pub const fn is_positive(self) -> bool { self > 0 } | |
1753 | ||
1754 | /// Returns `true` if `self` is negative and `false` if the number is zero or | |
1755 | /// positive. | |
1756 | /// | |
1757 | /// # Examples | |
1758 | /// | |
1759 | /// Basic usage: | |
1760 | /// | |
1761 | /// ``` | |
1762 | #[doc = concat!("assert!((-10", stringify!($SelfT), ").is_negative());")] | |
1763 | #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_negative());")] | |
1764 | /// ``` | |
1765 | #[stable(feature = "rust1", since = "1.0.0")] | |
1766 | #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] | |
1767 | #[inline] | |
1768 | pub const fn is_negative(self) -> bool { self < 0 } | |
1769 | ||
1770 | /// Return the memory representation of this integer as a byte array in | |
1771 | /// big-endian (network) byte order. | |
1772 | /// | |
1773 | #[doc = $to_xe_bytes_doc] | |
1774 | /// | |
1775 | /// # Examples | |
1776 | /// | |
1777 | /// ``` | |
1778 | #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")] | |
1779 | #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")] | |
1780 | /// ``` | |
1781 | #[stable(feature = "int_to_from_bytes", since = "1.32.0")] | |
1782 | #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] | |
1783 | #[inline] | |
1784 | pub const fn to_be_bytes(self) -> [u8; mem::size_of::<Self>()] { | |
1785 | self.to_be().to_ne_bytes() | |
1786 | } | |
1787 | ||
1788 | /// Return the memory representation of this integer as a byte array in | |
1789 | /// little-endian byte order. | |
1790 | /// | |
1791 | #[doc = $to_xe_bytes_doc] | |
1792 | /// | |
1793 | /// # Examples | |
1794 | /// | |
1795 | /// ``` | |
1796 | #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")] | |
1797 | #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")] | |
1798 | /// ``` | |
1799 | #[stable(feature = "int_to_from_bytes", since = "1.32.0")] | |
1800 | #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] | |
1801 | #[inline] | |
1802 | pub const fn to_le_bytes(self) -> [u8; mem::size_of::<Self>()] { | |
1803 | self.to_le().to_ne_bytes() | |
1804 | } | |
1805 | ||
1806 | /// Return the memory representation of this integer as a byte array in | |
1807 | /// native byte order. | |
1808 | /// | |
1809 | /// As the target platform's native endianness is used, portable code | |
1810 | /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, | |
1811 | /// instead. | |
1812 | /// | |
1813 | #[doc = $to_xe_bytes_doc] | |
1814 | /// | |
6a06907d XL |
1815 | /// [`to_be_bytes`]: Self::to_be_bytes |
1816 | /// [`to_le_bytes`]: Self::to_le_bytes | |
5869c6ff XL |
1817 | /// |
1818 | /// # Examples | |
1819 | /// | |
1820 | /// ``` | |
1821 | #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")] | |
1822 | /// assert_eq!( | |
1823 | /// bytes, | |
1824 | /// if cfg!(target_endian = "big") { | |
1825 | #[doc = concat!(" ", $be_bytes)] | |
1826 | /// } else { | |
1827 | #[doc = concat!(" ", $le_bytes)] | |
1828 | /// } | |
1829 | /// ); | |
1830 | /// ``` | |
1831 | #[stable(feature = "int_to_from_bytes", since = "1.32.0")] | |
1832 | #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] | |
1833 | // SAFETY: const sound because integers are plain old datatypes so we can always | |
1834 | // transmute them to arrays of bytes | |
1835 | #[rustc_allow_const_fn_unstable(const_fn_transmute)] | |
1836 | #[inline] | |
1837 | pub const fn to_ne_bytes(self) -> [u8; mem::size_of::<Self>()] { | |
1838 | // SAFETY: integers are plain old datatypes so we can always transmute them to | |
1839 | // arrays of bytes | |
1840 | unsafe { mem::transmute(self) } | |
1841 | } | |
1842 | ||
1843 | /// Return the memory representation of this integer as a byte array in | |
1844 | /// native byte order. | |
1845 | /// | |
1846 | /// [`to_ne_bytes`] should be preferred over this whenever possible. | |
1847 | /// | |
6a06907d | 1848 | /// [`to_ne_bytes`]: Self::to_ne_bytes |
5869c6ff XL |
1849 | /// |
1850 | /// # Examples | |
1851 | /// | |
1852 | /// ``` | |
1853 | /// #![feature(num_as_ne_bytes)] | |
1854 | #[doc = concat!("let num = ", $swap_op, stringify!($SelfT), ";")] | |
1855 | /// let bytes = num.as_ne_bytes(); | |
1856 | /// assert_eq!( | |
1857 | /// bytes, | |
1858 | /// if cfg!(target_endian = "big") { | |
1859 | #[doc = concat!(" &", $be_bytes)] | |
1860 | /// } else { | |
1861 | #[doc = concat!(" &", $le_bytes)] | |
1862 | /// } | |
1863 | /// ); | |
1864 | /// ``` | |
1865 | #[unstable(feature = "num_as_ne_bytes", issue = "76976")] | |
1866 | #[inline] | |
1867 | pub fn as_ne_bytes(&self) -> &[u8; mem::size_of::<Self>()] { | |
1868 | // SAFETY: integers are plain old datatypes so we can always transmute them to | |
1869 | // arrays of bytes | |
1870 | unsafe { &*(self as *const Self as *const _) } | |
1871 | } | |
1872 | ||
1873 | /// Create an integer value from its representation as a byte array in | |
1874 | /// big endian. | |
1875 | /// | |
1876 | #[doc = $to_xe_bytes_doc] | |
1877 | /// | |
1878 | /// # Examples | |
1879 | /// | |
1880 | /// ``` | |
1881 | #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")] | |
1882 | #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] | |
1883 | /// ``` | |
1884 | /// | |
1885 | /// When starting from a slice rather than an array, fallible conversion APIs can be used: | |
1886 | /// | |
1887 | /// ``` | |
1888 | /// use std::convert::TryInto; | |
1889 | /// | |
1890 | #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] | |
1891 | #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] | |
1892 | /// *input = rest; | |
1893 | #[doc = concat!(" ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")] | |
1894 | /// } | |
1895 | /// ``` | |
1896 | #[stable(feature = "int_to_from_bytes", since = "1.32.0")] | |
1897 | #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] | |
1898 | #[inline] | |
1899 | pub const fn from_be_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self { | |
1900 | Self::from_be(Self::from_ne_bytes(bytes)) | |
1901 | } | |
1902 | ||
1903 | /// Create an integer value from its representation as a byte array in | |
1904 | /// little endian. | |
1905 | /// | |
1906 | #[doc = $to_xe_bytes_doc] | |
1907 | /// | |
1908 | /// # Examples | |
1909 | /// | |
1910 | /// ``` | |
1911 | #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")] | |
1912 | #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] | |
1913 | /// ``` | |
1914 | /// | |
1915 | /// When starting from a slice rather than an array, fallible conversion APIs can be used: | |
1916 | /// | |
1917 | /// ``` | |
1918 | /// use std::convert::TryInto; | |
1919 | /// | |
1920 | #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] | |
1921 | #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] | |
1922 | /// *input = rest; | |
1923 | #[doc = concat!(" ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")] | |
1924 | /// } | |
1925 | /// ``` | |
1926 | #[stable(feature = "int_to_from_bytes", since = "1.32.0")] | |
1927 | #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] | |
1928 | #[inline] | |
1929 | pub const fn from_le_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self { | |
1930 | Self::from_le(Self::from_ne_bytes(bytes)) | |
1931 | } | |
1932 | ||
1933 | /// Create an integer value from its memory representation as a byte | |
1934 | /// array in native endianness. | |
1935 | /// | |
1936 | /// As the target platform's native endianness is used, portable code | |
1937 | /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as | |
1938 | /// appropriate instead. | |
1939 | /// | |
6a06907d XL |
1940 | /// [`from_be_bytes`]: Self::from_be_bytes |
1941 | /// [`from_le_bytes`]: Self::from_le_bytes | |
5869c6ff XL |
1942 | /// |
1943 | #[doc = $to_xe_bytes_doc] | |
1944 | /// | |
1945 | /// # Examples | |
1946 | /// | |
1947 | /// ``` | |
1948 | #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")] | |
1949 | #[doc = concat!(" ", $be_bytes)] | |
1950 | /// } else { | |
1951 | #[doc = concat!(" ", $le_bytes)] | |
1952 | /// }); | |
1953 | #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] | |
1954 | /// ``` | |
1955 | /// | |
1956 | /// When starting from a slice rather than an array, fallible conversion APIs can be used: | |
1957 | /// | |
1958 | /// ``` | |
1959 | /// use std::convert::TryInto; | |
1960 | /// | |
1961 | #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] | |
1962 | #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] | |
1963 | /// *input = rest; | |
1964 | #[doc = concat!(" ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")] | |
1965 | /// } | |
1966 | /// ``` | |
1967 | #[stable(feature = "int_to_from_bytes", since = "1.32.0")] | |
1968 | #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] | |
1969 | // SAFETY: const sound because integers are plain old datatypes so we can always | |
1970 | // transmute to them | |
1971 | #[rustc_allow_const_fn_unstable(const_fn_transmute)] | |
1972 | #[inline] | |
1973 | pub const fn from_ne_bytes(bytes: [u8; mem::size_of::<Self>()]) -> Self { | |
1974 | // SAFETY: integers are plain old datatypes so we can always transmute to them | |
1975 | unsafe { mem::transmute(bytes) } | |
1976 | } | |
1977 | ||
1978 | /// New code should prefer to use | |
6a06907d | 1979 | #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")] |
5869c6ff XL |
1980 | /// |
1981 | /// Returns the smallest value that can be represented by this integer type. | |
1982 | #[stable(feature = "rust1", since = "1.0.0")] | |
1983 | #[inline(always)] | |
1984 | #[rustc_promotable] | |
1985 | #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")] | |
1986 | #[rustc_deprecated(since = "TBD", reason = "replaced by the `MIN` associated constant on this type")] | |
1987 | pub const fn min_value() -> Self { | |
1988 | Self::MIN | |
1989 | } | |
1990 | ||
1991 | /// New code should prefer to use | |
6a06907d | 1992 | #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")] |
5869c6ff XL |
1993 | /// |
1994 | /// Returns the largest value that can be represented by this integer type. | |
1995 | #[stable(feature = "rust1", since = "1.0.0")] | |
1996 | #[inline(always)] | |
1997 | #[rustc_promotable] | |
1998 | #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")] | |
1999 | #[rustc_deprecated(since = "TBD", reason = "replaced by the `MAX` associated constant on this type")] | |
2000 | pub const fn max_value() -> Self { | |
2001 | Self::MAX | |
74b04a01 | 2002 | } |
1b1a35ee | 2003 | } |
32a655c1 | 2004 | } |