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

malachite_base/num/basic/
integers.rs
