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

malachite_base/num/basic/
integers.rs
