malachite_base/num/basic/
integers.rs

1// Copyright © 2026 Mikhail Hogrefe
2//
3// This file is part of Malachite.
4//
5// Malachite is free software: you can redistribute it and/or modify it under the terms of the GNU
6// Lesser General Public License (LGPL) as published by the Free Software Foundation; either version
7// 3 of the License, or (at your option) any later version. See <https://www.gnu.org/licenses/>.
8
9use crate::comparison::traits::{Max, Min};
10use crate::named::Named;
11use crate::num::arithmetic::traits::{
12    AbsDiff, AddMul, AddMulAssign, ArithmeticCheckedShl, ArithmeticCheckedShr, Average,
13    AverageAssign, AverageRound, AverageRoundAssign, BalancedMod, BinomialCoefficient, CeilingRoot,
14    CeilingRootAssign, CeilingSqrt, CeilingSqrtAssign, CheckedAdd, CheckedAddMul,
15    CheckedBinomialCoefficient, CheckedDiv, CheckedMul, CheckedMulAddMul, CheckedMulSubMul,
16    CheckedNeg, CheckedPow, CheckedRoot, CheckedSqrt, CheckedSquare, CheckedSub, CheckedSubMul,
17    DivAssignMod, DivAssignModEuclidean, DivAssignModPrecomputed, DivAssignRem, DivEuclidean,
18    DivEuclideanAssign, DivExact, DivExactAssign, DivMod, DivModEuclidean, DivModPrecomputed,
19    DivRem, DivRound, DivRoundAssign, DivisibleBy, DivisibleByPowerOf2, EqMod, EqModPowerOf2,
20    ExtendedGcd, FloorRoot, FloorRootAssign, FloorSqrt, FloorSqrtAssign, JacobiSymbol,
21    KroneckerSymbol, LegendreSymbol, Mod, ModAssign, ModEuclidean, ModEuclideanAssign, ModPowerOf2,
22    ModPowerOf2Assign, MulAddMul, MulAddMulAssign, MulSubMul, MulSubMulAssign, OverflowingAdd,
23    OverflowingAddAssign, OverflowingAddMul, OverflowingAddMulAssign, OverflowingDiv,
24    OverflowingDivAssign, OverflowingMul, OverflowingMulAddMul, OverflowingMulAddMulAssign,
25    OverflowingMulAssign, OverflowingMulSubMul, OverflowingMulSubMulAssign, OverflowingNeg,
26    OverflowingNegAssign, OverflowingPow, OverflowingPowAssign, OverflowingSquare,
27    OverflowingSquareAssign, OverflowingSub, OverflowingSubAssign, OverflowingSubMul,
28    OverflowingSubMulAssign, Parity, Pow, PowAssign, PowerOf2, RemPowerOf2, RemPowerOf2Assign,
29    RotateLeft, RotateLeftAssign, RotateRight, RotateRightAssign, RoundToMultiple,
30    RoundToMultipleAssign, RoundToMultipleOfPowerOf2, RoundToMultipleOfPowerOf2Assign,
31    SaturatingAdd, SaturatingAddAssign, SaturatingAddMul, SaturatingAddMulAssign, SaturatingMul,
32    SaturatingMulAddMul, SaturatingMulAddMulAssign, SaturatingMulAssign, SaturatingMulSubMul,
33    SaturatingMulSubMulAssign, SaturatingPow, SaturatingPowAssign, SaturatingSquare,
34    SaturatingSquareAssign, SaturatingSub, SaturatingSubAssign, SaturatingSubMul,
35    SaturatingSubMulAssign, ShlRound, ShlRoundAssign, ShrRound, ShrRoundAssign, Sign, Square,
36    SquareAssign, SubMul, SubMulAssign, WrappingAdd, WrappingAddAssign, WrappingAddMul,
37    WrappingAddMulAssign, WrappingDiv, WrappingDivAssign, WrappingMul, WrappingMulAddMul,
38    WrappingMulAddMulAssign, WrappingMulAssign, WrappingMulSubMul, WrappingMulSubMulAssign,
39    WrappingNeg, WrappingNegAssign, WrappingPow, WrappingPowAssign, WrappingSquare,
40    WrappingSquareAssign, WrappingSub, WrappingSubAssign, WrappingSubMul, WrappingSubMulAssign,
41};
42use crate::num::basic::traits::{One, Two, Zero};
43use crate::num::conversion::traits::{
44    ConvertibleFrom, ExactFrom, ExactInto, FromSciString, FromStringBase, IsInteger,
45    OverflowingFrom, OverflowingInto, RoundingFrom, RoundingInto, SaturatingFrom, SaturatingInto,
46    ToSci, ToStringBase, WrappingFrom, WrappingInto,
47};
48use crate::num::factorization::traits::{
49    ExpressAsPower, IsPower, IsSquare, RemovePower, RemovePowerAssign,
50};
51use crate::num::float::NiceFloat;
52use crate::num::logic::traits::{
53    BitAccess, BitBlockAccess, BitConvertible, BitIterable, BitScan, CountOnes, CountZeros,
54    LeadingZeros, LowMask, NotAssign, SignificantBits, TrailingZeros,
55};
56#[cfg(feature = "random")]
57use crate::num::random::HasRandomPrimitiveInts;
58use core::fmt::{Binary, Debug, Display, LowerHex, Octal, UpperHex};
59use core::hash::Hash;
60use core::iter::{Product, Sum};
61use core::ops::{
62    Add, AddAssign, BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor, BitXorAssign, Div, DivAssign,
63    Mul, MulAssign, Not, Rem, RemAssign, Shl, ShlAssign, Shr, ShrAssign, Sub, SubAssign,
64};
65use core::panic::{RefUnwindSafe, UnwindSafe};
66use core::str::FromStr;
67
68pub const USIZE_IS_U32: bool = usize::WIDTH == u32::WIDTH;
69pub const USIZE_IS_U64: bool = usize::WIDTH == u64::WIDTH;
70
71// Checks that usize is equivalent to u32 or u64, at compile time. The rest of Malachite can assume
72// that this condition is true.
73const _USIZE_ASSERTION: () = assert!(USIZE_IS_U32 || USIZE_IS_U64);
74
75/// The bounds that [`PrimitiveInt`] has only when the `random` feature is enabled.
76///
77/// With the feature on this is [`HasRandomPrimitiveInts`]; with it off it is empty. Every type
78/// meeting the bounds implements it automatically, so it never needs to be implemented by hand.
79///
80/// It exists because `#[cfg]` cannot be attached to an individual supertrait bound: without it,
81/// making one bound conditional would mean writing all ~450 bounds of [`PrimitiveInt`] twice, once
82/// per feature configuration, where a bound added to only one copy makes the two configurations
83/// disagree silently.
84#[cfg(feature = "random")]
85pub trait PrimitiveIntRandomBounds: HasRandomPrimitiveInts {}
86
87#[cfg(feature = "random")]
88impl<T: HasRandomPrimitiveInts> PrimitiveIntRandomBounds for T {}
89
90/// The bounds that [`PrimitiveInt`] has only when the `random` feature is enabled.
91///
92/// With the feature off, as here, there are none.
93#[cfg(not(feature = "random"))]
94pub trait PrimitiveIntRandomBounds {}
95
96#[cfg(not(feature = "random"))]
97impl<T> PrimitiveIntRandomBounds for T {}
98
99/// Defines functions on primitive integer types: uxx, ixx, usize, and isize.
100///
101/// The different types are distinguished by whether they are signed or unsigned, and by their
102/// widths. The width $W$ is the number of bits in the type. For example, the width of [`u32`] or
103/// [`i32`] is 32. Each type has $2^W$ distinct values.
104///
105/// Let $n$ be a value of type `Self`. If `Self` is unsigned, $0 \leq n < 2^W$. If `Self` is signed,
106/// $2^{W-1} \leq n < 2^{W-1}$.
107pub trait PrimitiveInt:
108    'static
109    + AbsDiff<Self>
110    + Add<Self, Output = Self>
111    + AddAssign<Self>
112    + AddMul<Self, Self, Output = Self>
113    + AddMulAssign<Self, Self>
114    + MulAddMul<Output = Self>
115    + MulAddMulAssign<Self, Self, Self>
116    + MulSubMul<Output = Self>
117    + MulSubMulAssign<Self, Self, Self>
118    + ArithmeticCheckedShl<i128, Output = Self>
119    + ArithmeticCheckedShl<i16, Output = Self>
120    + ArithmeticCheckedShl<i32, Output = Self>
121    + ArithmeticCheckedShl<i64, Output = Self>
122    + ArithmeticCheckedShl<i8, Output = Self>
123    + ArithmeticCheckedShl<isize, Output = Self>
124    + ArithmeticCheckedShl<u128, Output = Self>
125    + ArithmeticCheckedShl<u16, Output = Self>
126    + ArithmeticCheckedShl<u32, Output = Self>
127    + ArithmeticCheckedShl<u64, Output = Self>
128    + ArithmeticCheckedShl<u8, Output = Self>
129    + ArithmeticCheckedShl<usize, Output = Self>
130    + ArithmeticCheckedShr<i128, Output = Self>
131    + ArithmeticCheckedShr<i16, Output = Self>
132    + ArithmeticCheckedShr<i32, Output = Self>
133    + ArithmeticCheckedShr<i64, Output = Self>
134    + ArithmeticCheckedShr<i8, Output = Self>
135    + ArithmeticCheckedShr<isize, Output = Self>
136    + Average<Self, Output = Self>
137    + AverageAssign<Self>
138    + AverageRound<Self, Output = Self>
139    + AverageRoundAssign<Self>
140    + BalancedMod<Self>
141    + Binary
142    + BinomialCoefficient<Self>
143    + BitAccess
144    + BitAnd<Self, Output = Self>
145    + BitAndAssign<Self>
146    + BitBlockAccess
147    + BitConvertible
148    + BitIterable
149    + BitOr<Self, Output = Self>
150    + BitOrAssign<Self>
151    + BitScan
152    + BitXor<Self, Output = Self>
153    + BitXorAssign<Self>
154    + CeilingRoot<u64, Output = Self>
155    + CeilingRootAssign<u64>
156    + CeilingSqrt<Output = Self>
157    + CeilingSqrtAssign
158    + CheckedAdd<Self, Output = Self>
159    + CheckedAddMul<Self, Self, Output = Self>
160    + CheckedMulAddMul<Self, Self, Self, Output = Self>
161    + CheckedMulSubMul<Self, Self, Self, Output = Self>
162    + CheckedBinomialCoefficient<Self>
163    + CheckedDiv<Self, Output = Self>
164    + CheckedMul<Self, Output = Self>
165    + CheckedNeg<Output = Self>
166    + CheckedPow<u64, Output = Self>
167    + CheckedRoot<u64, Output = Self>
168    + CheckedSqrt<Output = Self>
169    + CheckedSquare<Output = Self>
170    + CheckedSub<Self, Output = Self>
171    + CheckedSubMul<Self, Self, Output = Self>
172    + Clone
173    + ConvertibleFrom<f32>
174    + ConvertibleFrom<f64>
175    + ConvertibleFrom<i128>
176    + ConvertibleFrom<i16>
177    + ConvertibleFrom<i32>
178    + ConvertibleFrom<i64>
179    + ConvertibleFrom<i8>
180    + ConvertibleFrom<isize>
181    + ConvertibleFrom<u128>
182    + ConvertibleFrom<u16>
183    + ConvertibleFrom<u32>
184    + ConvertibleFrom<u64>
185    + ConvertibleFrom<u8>
186    + ConvertibleFrom<usize>
187    + Copy
188    + CountOnes
189    + CountZeros
190    + Debug
191    + Default
192    + Display
193    + Div<Self, Output = Self>
194    + DivAssign<Self>
195    + DivAssignModEuclidean<Self, ModOutput = Self>
196    + DivAssignMod<Self, ModOutput = Self>
197    + DivAssignRem<Self, RemOutput = Self>
198    + DivEuclidean<Self, Output = Self>
199    + DivEuclideanAssign<Self>
200    + DivModEuclidean<Self, DivOutput = Self, ModOutput = Self>
201    + DivExact<Self, Output = Self>
202    + DivExactAssign<Self>
203    + DivMod<Self, DivOutput = Self, ModOutput = Self>
204    + DivModPrecomputed<Self, DivOutput = Self, ModOutput = Self>
205    + DivAssignModPrecomputed<Self>
206    + DivRem<Self, DivOutput = Self, RemOutput = Self>
207    + DivRound<Self, Output = Self>
208    + DivRoundAssign<Self>
209    + DivisibleBy<Self>
210    + DivisibleByPowerOf2
211    + Eq
212    + EqMod<Self, Self>
213    + EqModPowerOf2<Self>
214    + ExactFrom<i128>
215    + ExactFrom<i16>
216    + ExactFrom<i32>
217    + ExactFrom<i64>
218    + ExactFrom<i8>
219    + ExactFrom<isize>
220    + ExactFrom<u128>
221    + ExactFrom<u16>
222    + ExactFrom<u32>
223    + ExactFrom<u64>
224    + ExactFrom<u8>
225    + ExactFrom<usize>
226    + ExactInto<i128>
227    + ExactInto<i16>
228    + ExactInto<i32>
229    + ExactInto<i64>
230    + ExactInto<i8>
231    + ExactInto<isize>
232    + ExactInto<u128>
233    + ExactInto<u16>
234    + ExactInto<u32>
235    + ExactInto<u64>
236    + ExactInto<u8>
237    + ExactInto<usize>
238    + ExpressAsPower
239    + ExtendedGcd<Self>
240    + FloorRoot<u64, Output = Self>
241    + FloorRootAssign<u64>
242    + FloorSqrt<Output = Self>
243    + FloorSqrtAssign
244    + From<bool>
245    + FromSciString
246    + FromStr
247    + FromStringBase
248    + PrimitiveIntRandomBounds
249    + Hash
250    + IsInteger
251    + IsPower
252    + IsSquare
253    + JacobiSymbol<Self>
254    + KroneckerSymbol<Self>
255    + LeadingZeros
256    + LegendreSymbol<Self>
257    + LowMask
258    + LowerHex
259    + Max
260    + Min
261    + Mod<Self, Output = Self>
262    + ModAssign<Self>
263    + ModEuclidean<Self, Output = Self>
264    + ModEuclideanAssign<Self>
265    + ModPowerOf2
266    + ModPowerOf2Assign
267    + Mul<Self, Output = Self>
268    + MulAssign<Self>
269    + Named
270    + Not<Output = Self>
271    + NotAssign
272    + Octal
273    + One
274    + Ord
275    + OverflowingAdd<Self, Output = Self>
276    + OverflowingAddAssign<Self>
277    + OverflowingAddMul<Self, Self, Output = Self>
278    + OverflowingAddMulAssign<Self, Self>
279    + OverflowingMulAddMul<Self, Self, Self, Output = Self>
280    + OverflowingMulAddMulAssign<Self, Self, Self>
281    + OverflowingMulSubMul<Self, Self, Self, Output = Self>
282    + OverflowingMulSubMulAssign<Self, Self, Self>
283    + OverflowingDiv<Self, Output = Self>
284    + OverflowingDivAssign<Self>
285    + OverflowingFrom<i128>
286    + OverflowingFrom<i16>
287    + OverflowingFrom<i32>
288    + OverflowingFrom<i64>
289    + OverflowingFrom<i8>
290    + OverflowingFrom<isize>
291    + OverflowingFrom<u128>
292    + OverflowingFrom<u16>
293    + OverflowingFrom<u32>
294    + OverflowingFrom<u64>
295    + OverflowingFrom<u8>
296    + OverflowingFrom<usize>
297    + OverflowingInto<i128>
298    + OverflowingInto<i16>
299    + OverflowingInto<i32>
300    + OverflowingInto<i64>
301    + OverflowingInto<i8>
302    + OverflowingInto<isize>
303    + OverflowingInto<u128>
304    + OverflowingInto<u16>
305    + OverflowingInto<u32>
306    + OverflowingInto<u64>
307    + OverflowingInto<u8>
308    + OverflowingInto<usize>
309    + OverflowingMul<Self, Output = Self>
310    + OverflowingMulAssign<Self>
311    + OverflowingNeg<Output = Self>
312    + OverflowingNegAssign
313    + OverflowingPow<u64, Output = Self>
314    + OverflowingPowAssign<u64>
315    + OverflowingSquare<Output = Self>
316    + OverflowingSquareAssign
317    + OverflowingSub<Self, Output = Self>
318    + OverflowingSubAssign<Self>
319    + OverflowingSubMul<Self, Self, Output = Self>
320    + OverflowingSubMulAssign<Self, Self>
321    + Parity
322    + PartialEq<Self>
323    + PartialOrd<Self>
324    + Pow<u64, Output = Self>
325    + PowAssign<u64>
326    + PowerOf2<u64>
327    + Product
328    + RefUnwindSafe
329    + Rem<Self, Output = Self>
330    + RemAssign<Self>
331    + RemPowerOf2<Output = Self>
332    + RemPowerOf2Assign
333    + RemovePower<Self, Output = Self>
334    + RemovePowerAssign<Self>
335    + RotateLeft<Output = Self>
336    + RotateLeftAssign
337    + RotateRight<Output = Self>
338    + RotateRightAssign
339    + RoundToMultiple<Self, Output = Self>
340    + RoundToMultipleAssign<Self>
341    + RoundToMultipleOfPowerOf2<u64, Output = Self>
342    + RoundToMultipleOfPowerOf2Assign<u64>
343    + RoundingFrom<f32>
344    + RoundingFrom<f64>
345    + RoundingInto<f32>
346    + RoundingInto<f64>
347    + SaturatingAdd<Self, Output = Self>
348    + SaturatingAddAssign<Self>
349    + SaturatingAddMul<Self, Self, Output = Self>
350    + SaturatingAddMulAssign<Self, Self>
351    + SaturatingMulAddMul<Self, Self, Self, Output = Self>
352    + SaturatingMulAddMulAssign<Self, Self, Self>
353    + SaturatingMulSubMul<Self, Self, Self, Output = Self>
354    + SaturatingMulSubMulAssign<Self, Self, Self>
355    + SaturatingFrom<i128>
356    + SaturatingFrom<i16>
357    + SaturatingFrom<i32>
358    + SaturatingFrom<i64>
359    + SaturatingFrom<i8>
360    + SaturatingFrom<isize>
361    + SaturatingFrom<u128>
362    + SaturatingFrom<u16>
363    + SaturatingFrom<u32>
364    + SaturatingFrom<u64>
365    + SaturatingFrom<u8>
366    + SaturatingFrom<usize>
367    + SaturatingInto<i128>
368    + SaturatingInto<i16>
369    + SaturatingInto<i32>
370    + SaturatingInto<i64>
371    + SaturatingInto<i8>
372    + SaturatingInto<isize>
373    + SaturatingInto<u128>
374    + SaturatingInto<u16>
375    + SaturatingInto<u32>
376    + SaturatingInto<u64>
377    + SaturatingInto<u8>
378    + SaturatingInto<usize>
379    + SaturatingMul<Self, Output = Self>
380    + SaturatingMulAssign<Self>
381    + SaturatingPow<u64, Output = Self>
382    + SaturatingPowAssign<u64>
383    + SaturatingSquare<Output = Self>
384    + SaturatingSquareAssign
385    + SaturatingSub<Self, Output = Self>
386    + SaturatingSubAssign<Self>
387    + SaturatingSubMul<Self, Self, Output = Self>
388    + SaturatingSubMulAssign<Self, Self>
389    + Shl<i128, Output = Self>
390    + Shl<i16, Output = Self>
391    + Shl<i32, Output = Self>
392    + Shl<i64, Output = Self>
393    + Shl<i8, Output = Self>
394    + Shl<u128, Output = Self>
395    + Shl<u16, Output = Self>
396    + Shl<u32, Output = Self>
397    + Shl<u64, Output = Self>
398    + Shl<u8, Output = Self>
399    + ShlAssign<i128>
400    + ShlAssign<i16>
401    + ShlAssign<i32>
402    + ShlAssign<i64>
403    + ShlAssign<i8>
404    + ShlAssign<isize>
405    + ShlAssign<u128>
406    + ShlAssign<u16>
407    + ShlAssign<u32>
408    + ShlAssign<u64>
409    + ShlAssign<u8>
410    + ShlAssign<usize>
411    + ShlRound<i128, Output = Self>
412    + ShlRound<i16, Output = Self>
413    + ShlRound<i32, Output = Self>
414    + ShlRound<i64, Output = Self>
415    + ShlRound<i8, Output = Self>
416    + ShlRound<isize, Output = Self>
417    + ShlRoundAssign<i128>
418    + ShlRoundAssign<i16>
419    + ShlRoundAssign<i32>
420    + ShlRoundAssign<i64>
421    + ShlRoundAssign<i8>
422    + ShlRoundAssign<isize>
423    + Shr<i128, Output = Self>
424    + Shr<i16, Output = Self>
425    + Shr<i32, Output = Self>
426    + Shr<i64, Output = Self>
427    + Shr<i8, Output = Self>
428    + Shr<isize, Output = Self>
429    + Shr<u128, Output = Self>
430    + Shr<u16, Output = Self>
431    + Shr<u32, Output = Self>
432    + Shr<u64, Output = Self>
433    + Shr<u8, Output = Self>
434    + Shr<usize, Output = Self>
435    + ShrAssign<i128>
436    + ShrAssign<i16>
437    + ShrAssign<i32>
438    + ShrAssign<i64>
439    + ShrAssign<i8>
440    + ShrAssign<isize>
441    + ShrAssign<u128>
442    + ShrAssign<u16>
443    + ShrAssign<u32>
444    + ShrAssign<u64>
445    + ShrAssign<u8>
446    + ShrAssign<usize>
447    + ShrRound<i128, Output = Self>
448    + ShrRound<i16, Output = Self>
449    + ShrRound<i32, Output = Self>
450    + ShrRound<i64, Output = Self>
451    + ShrRound<i8, Output = Self>
452    + ShrRound<isize, Output = Self>
453    + ShrRound<u128, Output = Self>
454    + ShrRound<u16, Output = Self>
455    + ShrRound<u32, Output = Self>
456    + ShrRound<u64, Output = Self>
457    + ShrRound<u8, Output = Self>
458    + ShrRound<usize, Output = Self>
459    + ShrRoundAssign<i128>
460    + ShrRoundAssign<i16>
461    + ShrRoundAssign<i32>
462    + ShrRoundAssign<i64>
463    + ShrRoundAssign<i8>
464    + ShrRoundAssign<isize>
465    + ShrRoundAssign<u128>
466    + ShrRoundAssign<u16>
467    + ShrRoundAssign<u32>
468    + ShrRoundAssign<u64>
469    + ShrRoundAssign<u8>
470    + ShrRoundAssign<usize>
471    + Sign
472    + SignificantBits
473    + Sized
474    + Square<Output = Self>
475    + SquareAssign
476    + Sub<Self, Output = Self>
477    + SubAssign<Self>
478    + SubMul<Self, Self, Output = Self>
479    + SubMulAssign<Self, Self>
480    + Sum<Self>
481    + ToSci
482    + ToStringBase
483    + TrailingZeros
484    + TryFrom<NiceFloat<f32>>
485    + TryFrom<i128>
486    + TryFrom<i16>
487    + TryFrom<i32>
488    + TryFrom<i64>
489    + TryFrom<i8>
490    + TryFrom<isize>
491    + TryFrom<u128>
492    + TryFrom<u16>
493    + TryFrom<u32>
494    + TryFrom<u64>
495    + TryFrom<u8>
496    + TryFrom<usize>
497    + TryInto<NiceFloat<f32>>
498    + TryInto<i128>
499    + TryInto<i16>
500    + TryInto<i32>
501    + TryInto<i64>
502    + TryInto<i8>
503    + TryInto<isize>
504    + TryInto<u128>
505    + TryInto<u16>
506    + TryInto<u32>
507    + TryInto<u64>
508    + TryInto<u8>
509    + TryInto<usize>
510    + Two
511    + UnwindSafe
512    + UpperHex
513    + WrappingAdd<Self, Output = Self>
514    + WrappingAddAssign<Self>
515    + WrappingAddMul<Self, Self, Output = Self>
516    + WrappingAddMulAssign<Self, Self>
517    + WrappingMulAddMul<Self, Self, Self, Output = Self>
518    + WrappingMulAddMulAssign<Self, Self, Self>
519    + WrappingMulSubMul<Self, Self, Self, Output = Self>
520    + WrappingMulSubMulAssign<Self, Self, Self>
521    + WrappingDiv<Self, Output = Self>
522    + WrappingDivAssign<Self>
523    + WrappingFrom<i128>
524    + WrappingFrom<i16>
525    + WrappingFrom<i32>
526    + WrappingFrom<i64>
527    + WrappingFrom<i8>
528    + WrappingFrom<isize>
529    + WrappingFrom<u128>
530    + WrappingFrom<u16>
531    + WrappingFrom<u32>
532    + WrappingFrom<u64>
533    + WrappingFrom<u8>
534    + WrappingFrom<usize>
535    + WrappingInto<i128>
536    + WrappingInto<i16>
537    + WrappingInto<i32>
538    + WrappingInto<i64>
539    + WrappingInto<i8>
540    + WrappingInto<isize>
541    + WrappingInto<u128>
542    + WrappingInto<u16>
543    + WrappingInto<u32>
544    + WrappingInto<u64>
545    + WrappingInto<u8>
546    + WrappingInto<usize>
547    + WrappingMul<Self, Output = Self>
548    + WrappingMulAssign<Self>
549    + WrappingNeg<Output = Self>
550    + WrappingNegAssign
551    + WrappingPow<u64, Output = Self>
552    + WrappingPowAssign<u64>
553    + WrappingSquare<Output = Self>
554    + WrappingSquareAssign
555    + WrappingSub<Self, Output = Self>
556    + WrappingSubAssign<Self>
557    + WrappingSubMul<Self, Self, Output = Self>
558    + WrappingSubMulAssign<Self, Self>
559    + Zero
560{
561    /// The number of bits of `Self`.
562    const WIDTH: u64;
563
564    /// The base-2 logarithm of the number of bits of `Self`.
565    ///
566    /// Whenever you need to use `n / WIDTH`, you can use `n >> LOG_WIDTH` instead.
567    ///
568    /// This is $\log_2 W$.
569    ///
570    /// Note that this value is correct for all of the built-in primitive integer types, but it will
571    /// not be correct for custom types whose $W$ is not a power of 2. For such implementations,
572    /// `LOG_WIDTH` should not be used.
573    const LOG_WIDTH: u64 = Self::WIDTH.trailing_zeros() as u64;
574
575    /// A mask that consists of `LOG_WIDTH` bits.
576    ///
577    /// Whenever you need to use `n % WIDTH`, you can use `n & WIDTH_MASK` instead.
578    ///
579    /// This is $W - 1$.
580    ///
581    /// Note that this value is correct for all of the built-in primitive integer types, but it will
582    /// not be correct for custom types whose $W$ is not a power of 2. For such implementations,
583    /// `WIDTH_MASK` should not be used.
584    const WIDTH_MASK: u64 = Self::WIDTH - 1;
585
586    /// Gets the most-significant bit of `Self`. For signed integers, this is the sign bit.
587    ///
588    /// If `Self` is unsigned, $f(n) = (n \geq 2^{W-1})$. If `Self` is unsigned, $f(n) = (n < 0)$.
589    ///
590    /// # Worst-case complexity
591    /// Constant time and additional memory.
592    ///
593    /// # Examples
594    /// ```
595    /// use malachite_base::num::basic::integers::PrimitiveInt;
596    ///
597    /// assert_eq!(123u32.get_highest_bit(), false);
598    /// assert_eq!(4000000000u32.get_highest_bit(), true);
599    /// assert_eq!(2000000000i32.get_highest_bit(), false);
600    /// assert_eq!((-2000000000i32).get_highest_bit(), true);
601    /// ```
602    #[inline]
603    fn get_highest_bit(&self) -> bool {
604        self.get_bit(Self::WIDTH - 1)
605    }
606}
607
608/// Defines basic trait implementations that are the same for unsigned and signed types.
609macro_rules! impl_basic_traits_primitive_int {
610    ($t:ident, $width:expr) => {
611        /// # Examples
612        ///
613        /// See [here](self).
614        impl PrimitiveInt for $t {
615            const WIDTH: u64 = $width;
616        }
617
618        impl_named!($t);
619
620        /// The constant 0.
621        ///
622        /// # Examples
623        /// See [here](self).
624        impl Zero for $t {
625            const ZERO: $t = 0;
626        }
627
628        /// The constant 1.
629        ///
630        /// # Examples
631        /// See [here](self).
632        impl One for $t {
633            const ONE: $t = 1;
634        }
635
636        /// The constant 2.
637        ///
638        /// # Examples
639        /// See [here](self).
640        impl Two for $t {
641            const TWO: $t = 2;
642        }
643
644        /// The lowest value representable by this type.
645        ///
646        /// If `Self` is unsigned, `MIN` is 0. If `Self` is signed, `MIN` is $-2^{W-1}$.
647        ///
648        /// # Examples
649        /// See [here](self).
650        impl Min for $t {
651            const MIN: $t = $t::MIN;
652        }
653
654        /// The highest value representable by this type.
655        ///
656        /// If `Self` is unsigned, `MAX` is $2^W-1$. If `Self` is signed, `MAX` is $2^{W-1}-1$.
657        ///
658        /// # Examples
659        /// See [here](self).
660        impl Max for $t {
661            const MAX: $t = $t::MAX;
662        }
663    };
664}
665impl_basic_traits_primitive_int!(u8, 8);
666impl_basic_traits_primitive_int!(u16, 16);
667impl_basic_traits_primitive_int!(u32, 32);
668impl_basic_traits_primitive_int!(u64, 64);
669impl_basic_traits_primitive_int!(u128, 128);
670impl_basic_traits_primitive_int!(usize, 0usize.trailing_zeros() as u64);
671impl_basic_traits_primitive_int!(i8, 8);
672impl_basic_traits_primitive_int!(i16, 16);
673impl_basic_traits_primitive_int!(i32, 32);
674impl_basic_traits_primitive_int!(i64, 64);
675impl_basic_traits_primitive_int!(i128, 128);
676impl_basic_traits_primitive_int!(isize, 0usize.trailing_zeros() as u64);
malachite_base/num/basic/integers.rs

malachite_base/num/basic/
integers.rs
