BinaryInteger/power(_:)

[oscbyspro]

I'll add an exponentiation extension to BinaryInteger. It should wrap around and return an error indicator, making the result equivalent to repeated BinaryInteger/times(_:) calls. Negative and infinite exponents will be banned using Natural<T>.

extension BinaryInteger {

    /// Returns the `power` and `error` of `self` raised to `exponent`.
    ///
    /// ```swift
    /// U8(1).power(Natural(2)) // value: 001, error: false
    /// U8(2).power(Natural(3)) // value: 008, error: false
    /// U8(3).power(Natural(5)) // value: 243, error: false
    /// U8(5).power(Natural(7)) // value: 045, error: true 
    /// U8.exactly(00000078125) // value: 045, error: true
    /// ```
    ///
    /// - Note: Unsigned systems integers are always natural.
    ///
    @inlinable public borrowing func power(_ exponent: borrowing Natural<Self>) -> Fallible<Self> { ... }
}

[oscbyspro]

Clamping the exponent to UX in the arbitrary case seems like a decent way of reducing the cost of shifting, although shifting is relatively cheap. It works because the allocation limit is IX.max bits. It also works when |self| is 0 or 1. Edit: I suppose it isn't quite that simple, given that (-1)^x is allocatable, yet it flips sign depending on whether the exponent is odd or even.

[oscbyspro]

Hm. I'm reluctant to allow signed exponents because I don't want to think about 0^-x and the like. But, it turns out that infinite values just work. Most inputs with infinite exponents cannot be allocated, but that's equally true for big-but-finite exponents. So perhaps T.Magnitude is preferred over Natural<T>. I also don't need unsigned systems integer convenience methods if the exponent type is T.Magnitude.