         return result
     }
 
+    /// Decrement this integer by one.
+    /// - Requires: !isZero
+    /// - Complexity: O(count)
     public mutating func decrement(shift shift: Int = 0) {
         self.subtractDigitInPlace(1, shift: shift)
     }
 }
 
+/// Subtract `b` from `a` and return the result.
+/// - Requires: a >= b
+/// - Complexity: O(a.count)
 @warn_unused_result
 public func -(a: BigUInt, b: BigUInt) -> BigUInt {
     return a.subtract(b)
 }
 
+/// Subtract `b` from `a` and store the result in `a`.
+/// - Requires: a >= b
+/// - Complexity: O(a.count)
 public func -=(inout a: BigUInt, b: BigUInt) {
     a.subtractInPlace(b, shift: 0)
 }


extension BigUInt: Hashable {
    public var hashValue: Int {
        var hash: UInt64 = UInt64(count).byteSwapped
        for i in 0..<count {
            let shift: UInt64 = ((UInt64(i) << 5) - UInt64(i)) & 63


extension String {
    public init(_ v: BigUInt) { self.init(v, radix: 10, uppercase: false) }

    /// Create an instance representing v in the given radix (base).
    ///
    /// Numerals greater than 9 are represented as letters from the English alphabet,
    /// starting with `a` if `uppercase` is false or `A` otherwise.
    ///
    /// - Requires: radix > 1 && radix <= 36
    /// - Complexity: O(count) when radix is a power of two; otherwise O(count^2).
    public init(_ v: BigUInt, radix: Int, uppercase: Bool = false) {
        precondition(radix > 1)
        let (charsPerDigit, power) = BigUInt.charsPerDigitForRadix(radix)
