[SE-0368] StaticBigInt: add the Swift wrapper type

Author: benrimmington

stdlib/public/core/CMakeLists.txt

@@ -2,7 +2,7 @@
 #
 # This source file is part of the Swift.org open source project
 #
-# Copyright (c) 2014 - 2019 Apple Inc. and the Swift project authors
+# Copyright (c) 2014 - 2022 Apple Inc. and the Swift project authors
 # Licensed under Apache License v2.0 with Runtime Library Exception
 #
 # See https://swift.org/LICENSE.txt for license information
@@ -226,6 +226,7 @@ set(SWIFTLIB_SOURCES
   PlaygroundDisplay.swift
   CommandLine.swift
   SliceBuffer.swift
+  StaticBigInt.swift
   UnfoldSequence.swift
   VarArgs.swift
   Zip.swift

stdlib/public/core/GroupInfo.json

@@ -167,7 +167,8 @@
     "Integers": [
       "Integers.swift",
       "IntegerTypes.swift",
-      "IntegerParsing.swift"],
+      "IntegerParsing.swift",
+      "StaticBigInt.swift"],
     "Floating": [
       "FloatingPoint.swift",
       "FloatingPointParsing.swift",

stdlib/public/core/StaticBigInt.swift

@@ -0,0 +1,235 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// An immutable arbitrary-precision signed integer.
+///
+/// `StaticBigInt` is primarily intended to be used as the associated type of an
+/// `ExpressibleByIntegerLiteral` conformance.
+@available(SwiftStdlib 5.8, *)
+@frozen
+public struct StaticBigInt:
+  _ExpressibleByBuiltinIntegerLiteral,
+  ExpressibleByIntegerLiteral,
+  Sendable
+{
+  @available(SwiftStdlib 5.8, *)
+  @usableFromInline
+  internal let _value: Builtin.IntLiteral
+
+  @available(SwiftStdlib 5.8, *)
+  @inlinable
+  public init(_builtinIntegerLiteral value: Builtin.IntLiteral) {
+    _value = value
+  }
+
+  /// Returns the given value unchanged.
+  @_alwaysEmitIntoClient
+  public static prefix func + (_ rhs: Self) -> Self {
+    rhs
+  }
+}
+
+//===----------------------------------------------------------------------===//
+// MARK: - Binary Representation
+//===----------------------------------------------------------------------===//
+
+@available(SwiftStdlib 5.8, *)
+extension StaticBigInt {
+
+  /// Returns `-1`, `0`, or `+1` to indicate whether this value is less than,
+  /// equal to, or greater than zero.
+  ///
+  /// The return type is `Int` rather than `Self`.
+  @available(SwiftStdlib 5.8, *)
+  @inlinable
+  public func signum() -> Int {
+    _isNegative ? -1 : (bitWidth == 1) ? 0 : +1
+  }
+
+  @available(SwiftStdlib 5.8, *)
+  @inlinable
+  internal var _isNegative: Bool {
+    Bool(Builtin.isNegative_IntLiteral(_value))
+  }
+
+  /// Returns the minimal number of bits in this value's binary representation,
+  /// including the sign bit, and excluding the sign extension.
+  ///
+  /// The following examples show the least significant byte of each value's
+  /// binary representation, separated into excluded and included bits.
+  ///
+  /// * `-4` (`0b11111_100`) is 3 bits.
+  /// * `-3` (`0b11111_101`) is 3 bits.
+  /// * `-2` (`0b111111_10`) is 2 bits.
+  /// * `-1` (`0b1111111_1`) is 1 bit.
+  /// * `+0` (`0b0000000_0`) is 1 bit.
+  /// * `+1` (`0b000000_01`) is 2 bits.
+  /// * `+2` (`0b00000_010`) is 3 bits.
+  /// * `+3` (`0b00000_011`) is 3 bits.
+  @available(SwiftStdlib 5.8, *)
+  @inlinable
+  public var bitWidth: Int {
+    Int(Builtin.bitWidth_IntLiteral(_value))
+  }
+
+  /// Returns an element of this value's binary representation.
+  ///
+  /// The elements are ordered from least significant to most significant, with
+  /// an infinite sign extension. Negative values are in two's complement.
+  ///
+  ///     let value: StaticBigInt = -0x8000000000000000_0000000000000000
+  ///     value.bitWidth        //-> 128
+  ///     value[0] as UInt64    //-> 0x0000000000000000
+  ///     value[1] as UInt64    //-> 0x8000000000000000
+  ///     value[2] as UInt64    //-> 0xFFFFFFFFFFFFFFFF
+  ///
+  ///     let value: StaticBigInt = -1
+  ///     value.bitWidth        //-> 1
+  ///     value[0] as UInt64    //-> 0xFFFFFFFFFFFFFFFF
+  ///     value[1] as UInt64    //-> 0xFFFFFFFFFFFFFFFF
+  ///     value[2] as UInt64    //-> 0xFFFFFFFFFFFFFFFF
+  ///
+  ///     let value: StaticBigInt = +0
+  ///     value.bitWidth        //-> 1
+  ///     value[0] as UInt64    //-> 0x0000000000000000
+  ///     value[1] as UInt64    //-> 0x0000000000000000
+  ///     value[2] as UInt64    //-> 0x0000000000000000
+  ///
+  ///     let value: StaticBigInt = +0x7FFFFFFFFFFFFFFF_FFFFFFFFFFFFFFFF
+  ///     value.bitWidth        //-> 128
+  ///     value[0] as UInt64    //-> 0xFFFFFFFFFFFFFFFF
+  ///     value[1] as UInt64    //-> 0x7FFFFFFFFFFFFFFF
+  ///     value[2] as UInt64    //-> 0x0000000000000000
+  ///
+  /// - Parameter index: A nonnegative zero-based index.
+  /// - Returns: A fixed-width unsigned integer. Word-sized types are preferred.
+  @available(SwiftStdlib 5.8, *)
+  @inlinable
+  public subscript<Element>(_ index: Int) -> Element
+  where
+    Element: _ExpressibleByBuiltinIntegerLiteral,
+    Element: FixedWidthInteger,
+    Element: UnsignedInteger
+  {
+    _precondition(index >= 0, "index out of range")
+    guard index * Element.bitWidth < bitWidth else {
+      return _isNegative ? ~0 : 0
+    }
+    guard Element.bitWidth == UInt.bitWidth else {
+      return self[_slowElementAt: index]
+    }
+    return Element(_truncatingBits: UInt(
+      Builtin.wordAtIndex_IntLiteral(_value, index._builtinWordValue)
+    ))
+  }
+
+  @available(SwiftStdlib 5.8, *)
+  @usableFromInline
+  internal subscript<Element>(_slowElementAt index: Int) -> Element
+  where
+    Element: _ExpressibleByBuiltinIntegerLiteral,
+    Element: FixedWidthInteger,
+    Element: UnsignedInteger
+  {
+    _internalInvariant(index >= 0, "index out of range")
+    let bitIndex = index * Element.bitWidth
+    var wordIndex = bitIndex >> UInt.bitWidth.trailingZeroBitCount
+    if UInt.bitWidth.isMultiple(of: Element.bitWidth) {
+      // Create a single-word element, using a *masking* shift.
+      let word: UInt = self[wordIndex]
+      return Element(_truncatingBits: word &>> bitIndex)
+    } else if Element.bitWidth.isMultiple(of: UInt.bitWidth) {
+      // Create a multi-word element.
+      var result = Element.zero
+      for wordOffset in 0..<(Element.bitWidth / UInt.bitWidth) {
+        let word: UInt = self[wordIndex]
+        result |= Element(_truncatingBits: word) << (wordOffset * UInt.bitWidth)
+        wordIndex += 1
+      }
+      return result
+    } else {
+      _preconditionFailure("element type not supported")
+    }
+  }
+}
+
+//===----------------------------------------------------------------------===//
+// MARK: - Textual Representation
+//===----------------------------------------------------------------------===//
+
+@available(SwiftStdlib 5.8, *)
+extension StaticBigInt: CustomDebugStringConvertible {
+
+  @available(SwiftStdlib 5.8, *)
+  public var debugDescription: String {
+    let isNegative = _isNegative
+    let prefix = isNegative ? "-0x" : "+0x"
+
+    // Equivalent to `ceil(bitWidthExcludingSignBit / fourBitsPerHexDigit)`.
+    // Underestimated for `-(16 ** y)` values (e.g. "-0x1", "-0x10", "-0x100").
+    let capacity = prefix.utf8.count + (((bitWidth - 1) + 3) / 4)
+    var result = String(unsafeUninitializedCapacity: capacity) { buffer in
+
+      // Ignore extra capacity by rebasing, then pre-initialize with zeros.
+      var buffer = UnsafeMutableBufferPointer(rebasing: buffer.prefix(capacity))
+      buffer.initialize(repeating: UInt8(ascii: "0"))
+
+      // Use a 32-bit element type, to generate small hexadecimal strings.
+      typealias Element = UInt32
+      let hexDigitsPerElement = Element.bitWidth / 4
+      _internalInvariant(hexDigitsPerElement <= _SmallString.capacity)
+
+      // Lazily compute the magnitude, starting with the least significant bits.
+      var overflow = isNegative
+      for bitIndex in stride(from: 0, to: bitWidth, by: Element.bitWidth) {
+        let elementIndex = bitIndex >> Element.bitWidth.trailingZeroBitCount
+        var element: Element = self[elementIndex]
+        if isNegative {
+          element = ~element
+          if overflow {
+            (element, overflow) = element.addingReportingOverflow(1)
+          }
+        }
+
+        // Overwrite trailing zeros with hexadecimal digits.
+        // FIXME: <https://forums.swift.org/t/better-buffer-slices/55689>
+        let hexDigits = String(element, radix: 16, uppercase: true)
+        _ = UnsafeMutableBufferPointer(
+          rebasing: buffer.suffix(hexDigits.utf8.count)
+        ).initialize(from: hexDigits.utf8)
+        buffer = UnsafeMutableBufferPointer(
+          rebasing: buffer.dropLast(hexDigitsPerElement)
+        )
+      }
+      return capacity
+    }
+
+    // Overwrite leading zeros with the "±0x" indicator.
+    if let upToIndex = result.firstIndex(where: { $0 != "0" }) {
+      result.replaceSubrange(..<upToIndex, with: prefix)
+    } else {
+      result = "+0x0"
+    }
+    return result
+  }
+}
+
+#if SWIFT_ENABLE_REFLECTION
+@available(SwiftStdlib 5.8, *)
+extension StaticBigInt: CustomReflectable {
+
+  @available(SwiftStdlib 5.8, *)
+  public var customMirror: Mirror {
+    Mirror(self, unlabeledChildren: EmptyCollection<Void>())
+  }
+}
+#endif