1use crate::{CheckedMul, One};
2use core::num::Wrapping;
3use core::ops::Mul;
4
5/// Binary operator for raising a value to a power.
6pub trait Pow<RHS> {
7 /// The result after applying the operator.
8 type Output;
9
10 /// Returns `self` to the power `rhs`.
11 ///
12 /// # Examples
13 ///
14 /// ```
15 /// use num_traits::Pow;
16 /// assert_eq!(Pow::pow(10u32, 2u32), 100);
17 /// ```
18 fn pow(self, rhs: RHS) -> Self::Output;
19}
20
21macro_rules! pow_impl {
22 ($t:ty) => {
23 pow_impl!($t, u8);
24 pow_impl!($t, usize);
25
26 // FIXME: these should be possible
27 // pow_impl!($t, u16);
28 // pow_impl!($t, u32);
29 // pow_impl!($t, u64);
30 };
31 ($t:ty, $rhs:ty) => {
32 pow_impl!($t, $rhs, usize, pow);
33 };
34 ($t:ty, $rhs:ty, $desired_rhs:ty, $method:expr) => {
35 impl Pow<$rhs> for $t {
36 type Output = $t;
37 #[inline]
38 fn pow(self, rhs: $rhs) -> $t {
39 ($method)(self, <$desired_rhs>::from(rhs))
40 }
41 }
42
43 impl<'a> Pow<&'a $rhs> for $t {
44 type Output = $t;
45 #[inline]
46 fn pow(self, rhs: &'a $rhs) -> $t {
47 ($method)(self, <$desired_rhs>::from(*rhs))
48 }
49 }
50
51 impl<'a> Pow<$rhs> for &'a $t {
52 type Output = $t;
53 #[inline]
54 fn pow(self, rhs: $rhs) -> $t {
55 ($method)(*self, <$desired_rhs>::from(rhs))
56 }
57 }
58
59 impl<'a, 'b> Pow<&'a $rhs> for &'b $t {
60 type Output = $t;
61 #[inline]
62 fn pow(self, rhs: &'a $rhs) -> $t {
63 ($method)(*self, <$desired_rhs>::from(*rhs))
64 }
65 }
66 };
67}
68
69pow_impl!(u8, u8, u32, u8::pow);
70pow_impl!(u8, u16, u32, u8::pow);
71pow_impl!(u8, u32, u32, u8::pow);
72pow_impl!(u8, usize);
73pow_impl!(i8, u8, u32, i8::pow);
74pow_impl!(i8, u16, u32, i8::pow);
75pow_impl!(i8, u32, u32, i8::pow);
76pow_impl!(i8, usize);
77pow_impl!(u16, u8, u32, u16::pow);
78pow_impl!(u16, u16, u32, u16::pow);
79pow_impl!(u16, u32, u32, u16::pow);
80pow_impl!(u16, usize);
81pow_impl!(i16, u8, u32, i16::pow);
82pow_impl!(i16, u16, u32, i16::pow);
83pow_impl!(i16, u32, u32, i16::pow);
84pow_impl!(i16, usize);
85pow_impl!(u32, u8, u32, u32::pow);
86pow_impl!(u32, u16, u32, u32::pow);
87pow_impl!(u32, u32, u32, u32::pow);
88pow_impl!(u32, usize);
89pow_impl!(i32, u8, u32, i32::pow);
90pow_impl!(i32, u16, u32, i32::pow);
91pow_impl!(i32, u32, u32, i32::pow);
92pow_impl!(i32, usize);
93pow_impl!(u64, u8, u32, u64::pow);
94pow_impl!(u64, u16, u32, u64::pow);
95pow_impl!(u64, u32, u32, u64::pow);
96pow_impl!(u64, usize);
97pow_impl!(i64, u8, u32, i64::pow);
98pow_impl!(i64, u16, u32, i64::pow);
99pow_impl!(i64, u32, u32, i64::pow);
100pow_impl!(i64, usize);
101
102pow_impl!(u128, u8, u32, u128::pow);
103pow_impl!(u128, u16, u32, u128::pow);
104pow_impl!(u128, u32, u32, u128::pow);
105pow_impl!(u128, usize);
106
107pow_impl!(i128, u8, u32, i128::pow);
108pow_impl!(i128, u16, u32, i128::pow);
109pow_impl!(i128, u32, u32, i128::pow);
110pow_impl!(i128, usize);
111
112pow_impl!(usize, u8, u32, usize::pow);
113pow_impl!(usize, u16, u32, usize::pow);
114pow_impl!(usize, u32, u32, usize::pow);
115pow_impl!(usize, usize);
116pow_impl!(isize, u8, u32, isize::pow);
117pow_impl!(isize, u16, u32, isize::pow);
118pow_impl!(isize, u32, u32, isize::pow);
119pow_impl!(isize, usize);
120pow_impl!(Wrapping<u8>);
121pow_impl!(Wrapping<i8>);
122pow_impl!(Wrapping<u16>);
123pow_impl!(Wrapping<i16>);
124pow_impl!(Wrapping<u32>);
125pow_impl!(Wrapping<i32>);
126pow_impl!(Wrapping<u64>);
127pow_impl!(Wrapping<i64>);
128pow_impl!(Wrapping<u128>);
129pow_impl!(Wrapping<i128>);
130pow_impl!(Wrapping<usize>);
131pow_impl!(Wrapping<isize>);
132
133// FIXME: these should be possible
134// pow_impl!(u8, u64);
135// pow_impl!(i16, u64);
136// pow_impl!(i8, u64);
137// pow_impl!(u16, u64);
138// pow_impl!(u32, u64);
139// pow_impl!(i32, u64);
140// pow_impl!(u64, u64);
141// pow_impl!(i64, u64);
142// pow_impl!(usize, u64);
143// pow_impl!(isize, u64);
144
145#[cfg(any(feature = "std", feature = "libm"))]
146mod float_impls {
147 use super::Pow;
148 use crate::Float;
149
150 pow_impl!(f32, i8, i32, <f32 as Float>::powi);
151 pow_impl!(f32, u8, i32, <f32 as Float>::powi);
152 pow_impl!(f32, i16, i32, <f32 as Float>::powi);
153 pow_impl!(f32, u16, i32, <f32 as Float>::powi);
154 pow_impl!(f32, i32, i32, <f32 as Float>::powi);
155 pow_impl!(f64, i8, i32, <f64 as Float>::powi);
156 pow_impl!(f64, u8, i32, <f64 as Float>::powi);
157 pow_impl!(f64, i16, i32, <f64 as Float>::powi);
158 pow_impl!(f64, u16, i32, <f64 as Float>::powi);
159 pow_impl!(f64, i32, i32, <f64 as Float>::powi);
160 pow_impl!(f32, f32, f32, <f32 as Float>::powf);
161 pow_impl!(f64, f32, f64, <f64 as Float>::powf);
162 pow_impl!(f64, f64, f64, <f64 as Float>::powf);
163}
164
165/// Raises a value to the power of exp, using exponentiation by squaring.
166///
167/// Note that `0⁰` (`pow(0, 0)`) returns `1`. Mathematically this is undefined.
168///
169/// # Example
170///
171/// ```rust
172/// use num_traits::pow;
173///
174/// assert_eq!(pow(2i8, 4), 16);
175/// assert_eq!(pow(6u8, 3), 216);
176/// assert_eq!(pow(0u8, 0), 1); // Be aware if this case affects you
177/// ```
178#[inline]
179pub fn pow<T: Clone + One + Mul<T, Output = T>>(mut base: T, mut exp: usize) -> T {
180 if exp == 0 {
181 return T::one();
182 }
183
184 while exp & 1 == 0 {
185 base = base.clone() * base;
186 exp >>= 1;
187 }
188 if exp == 1 {
189 return base;
190 }
191
192 let mut acc: T = base.clone();
193 while exp > 1 {
194 exp >>= 1;
195 base = base.clone() * base;
196 if exp & 1 == 1 {
197 acc = acc * base.clone();
198 }
199 }
200 acc
201}
202
203/// Raises a value to the power of exp, returning `None` if an overflow occurred.
204///
205/// Note that `0⁰` (`checked_pow(0, 0)`) returns `Some(1)`. Mathematically this is undefined.
206///
207/// Otherwise same as the `pow` function.
208///
209/// # Example
210///
211/// ```rust
212/// use num_traits::checked_pow;
213///
214/// assert_eq!(checked_pow(2i8, 4), Some(16));
215/// assert_eq!(checked_pow(7i8, 8), None);
216/// assert_eq!(checked_pow(7u32, 8), Some(5_764_801));
217/// assert_eq!(checked_pow(0u32, 0), Some(1)); // Be aware if this case affect you
218/// ```
219#[inline]
220pub fn checked_pow<T: Clone + One + CheckedMul>(mut base: T, mut exp: usize) -> Option<T> {
221 if exp == 0 {
222 return Some(T::one());
223 }
224
225 while exp & 1 == 0 {
226 base = base.checked_mul(&base)?;
227 exp >>= 1;
228 }
229 if exp == 1 {
230 return Some(base);
231 }
232
233 let mut acc: T = base.clone();
234 while exp > 1 {
235 exp >>= 1;
236 base = base.checked_mul(&base)?;
237 if exp & 1 == 1 {
238 acc = acc.checked_mul(&base)?;
239 }
240 }
241 Some(acc)
242}
243