[stdlib] Update InlineArray (2) (#79866)

* Amend doc comments.
* Add `guard` for empty array.
* Add tests for initialization errors.
* Use `Self.` to call static method.
* Use `_checkIndex` in `swapAt` method.
* Wrap overlong lines.

Author: benrimmington

stdlib/public/core/InlineArray.swift

@@ -95,7 +95,10 @@ extension InlineArray where Element: ~Copyable {
   @_transparent
   internal var _mutableBuffer: UnsafeMutableBufferPointer<Element> {
     mutating get {
-      unsafe UnsafeMutableBufferPointer<Element>(start: _mutableAddress, count: count)
+      unsafe UnsafeMutableBufferPointer<Element>(
+        start: _mutableAddress,
+        count: count
+      )
     }
   }
 
@@ -121,14 +124,18 @@ extension InlineArray where Element: ~Copyable {
 @available(SwiftStdlib 6.2, *)
 extension InlineArray where Element: ~Copyable {
   /// Initializes every element in this array, by calling the given closure
-  /// for each index.
+  /// with each index.
   ///
   /// This will call the closure `count` times, where `count` is the static
   /// count of the array, to initialize every element by passing the closure
-  /// the index of the current element being initialized. The closure is allowed
-  /// to throw an error at any point during initialization at which point the
-  /// array will stop initialization, deinitialize every currently initialized
-  /// element, and throw the given error back out to the caller.
+  /// the index of the current element being initialized.
+  ///
+  ///     InlineArray<4, Int> { 1 << $0 }  //-> [1, 2, 4, 8]
+  ///
+  /// The closure is allowed to throw an error at any point during
+  /// initialization at which point the array will stop initialization,
+  /// deinitialize every currently initialized element, and throw the given
+  /// error back out to the caller.
   ///
   /// - Parameter body: A closure that returns an owned `Element` to emplace at
   ///   the passed in index.
@@ -139,9 +146,7 @@ extension InlineArray where Element: ~Copyable {
   public init<E: Error>(_ body: (Index) throws(E) -> Element) throws(E) {
 #if $BuiltinEmplaceTypedThrows
     self = try Builtin.emplace { (rawPtr) throws(E) -> () in
-      let buffer = InlineArray<count, Element>._initializationBuffer(
-        start: rawPtr
-      )
+      let buffer = Self._initializationBuffer(start: rawPtr)
 
       for i in 0 ..< count {
         do throws(E) {
@@ -164,19 +169,23 @@ extension InlineArray where Element: ~Copyable {
   }
 
   /// Initializes every element in this array, by calling the given closure
-  /// for each previously initialized element.
+  /// with each preceding element.
   ///
   /// This will call the closure `count - 1` times, where `count` is the static
   /// count of the array, to initialize every element by passing the closure an
-  /// immutable borrow reference to the previous element. The closure is allowed
-  /// to throw an error at any point during initialization at which point the
-  /// array will stop initialization, deinitialize every currently initialized
-  /// element, and throw the given error back out to the caller.
+  /// immutable borrow reference to the preceding element.
+  ///
+  ///     InlineArray<4, Int>(first: 1) { $0 << 1 }  //-> [1, 2, 4, 8]
+  ///
+  /// The closure is allowed to throw an error at any point during
+  /// initialization at which point the array will stop initialization,
+  /// deinitialize every currently initialized element, and throw the given
+  /// error back out to the caller.
   ///
   /// - Parameters:
   ///   - first: The first value to emplace into the array.
   ///   - next: A closure that takes an immutable borrow reference to the
-  ///     previous element, and returns an owned `Element` instance to emplace
+  ///     preceding element, and returns an owned `Element` instance to emplace
   ///     into the array.
   ///
   /// - Complexity: O(*n*), where *n* is the number of elements in the array.
@@ -194,11 +203,16 @@ extension InlineArray where Element: ~Copyable {
     var o: Element? = first
 
     self = try Builtin.emplace { (rawPtr) throws(E) -> () in
-      let buffer = InlineArray<count, Element>._initializationBuffer(
-        start: rawPtr
-      )
+      let buffer = Self._initializationBuffer(start: rawPtr)
 
-      unsafe buffer.initializeElement(at: 0, to: o.take()._consumingUncheckedUnwrapped())
+      guard Self.count > 0 else {
+        return
+      }
+
+      unsafe buffer.initializeElement(
+        at: 0,
+        to: o.take()._consumingUncheckedUnwrapped()
+      )
 
       for i in 1 ..< count {
         do throws(E) {
@@ -232,7 +246,7 @@ extension InlineArray where Element: Copyable {
   @_alwaysEmitIntoClient
   public init(repeating value: Element) {
     self = Builtin.emplace {
-      let buffer = InlineArray<count, Element>._initializationBuffer(start: $0)
+      let buffer = Self._initializationBuffer(start: $0)
 
       unsafe buffer.initialize(repeating: value)
     }
@@ -431,8 +445,8 @@ extension InlineArray where Element: ~Copyable {
       return
     }
 
-    _precondition(indices.contains(i), "Index out of bounds")
-    _precondition(indices.contains(j), "Index out of bounds")
+    _checkIndex(i)
+    _checkIndex(j)
 
     let ithElement = unsafe _mutableBuffer.moveElement(from: i)
     let jthElement = unsafe _mutableBuffer.moveElement(from: j)

test/stdlib/InlineArray.swift

@@ -36,6 +36,7 @@ enum InlineArrayTests {
     testSuite.test("Copyable",    testCopyable)
     testSuite.test("Noncopyable", testNoncopyable)
     testSuite.test("Uninhabited", testUninhabited)
+    testSuite.test("Throws",      testThrows)
     runAllTests()
   }
 
@@ -82,8 +83,10 @@ enum InlineArrayTests {
       let b = InlineArray<4, Int>(first: 1) { $0 << 1 }
       var c = InlineArray<4, Int>(repeating: 9)
       var d = InlineArray<4, Int>(repeating: 9)
+      let e = InlineArray<0, Int>(repeating: 9)
       _checkInlineArray(c, oracle: [9, 9, 9, 9])
       _checkInlineArray(d, oracle: [9, 9, 9, 9])
+      _checkInlineArray(e, oracle: [])
       c[0] = 1
       c[1] = 2
       c[2] = 4
@@ -150,6 +153,47 @@ enum InlineArrayTests {
       _checkInlineArray(f, oracle: [])
     }
   }
+
+  /// The closure is allowed to throw an error at any point during
+  /// initialization at which point the array will stop initialization,
+  /// deinitialize every currently initialized element, and throw the given
+  /// error back out to the caller.
+  @available(SwiftStdlib 6.2, *)
+  static func testThrows() {
+    let error = CancellationError()
+    do {
+      expectDoesNotThrow {
+        let a = try InlineArray<0, String> { _ in throw error }
+        _checkInlineArray(a, oracle: [])
+      }
+      _expectThrows {
+        let _ = try InlineArray<1, String> { _ in throw error }
+      }
+      _expectThrows {
+        let _ = try InlineArray<2, String> { index in
+          if index == 0 { "first" } else { throw error }
+        }
+      }
+    }
+    do {
+      expectDoesNotThrow {
+        let a = try InlineArray<0, String>(first: "first") { _ in throw error }
+        _checkInlineArray(a, oracle: [])
+      }
+      expectDoesNotThrow {
+        let a = try InlineArray<1, String>(first: "first") { _ in throw error }
+        _checkInlineArray(a, oracle: ["first"])
+      }
+      _expectThrows {
+        let _ = try InlineArray<2, String>(first: "first") { _ in throw error }
+      }
+      _expectThrows {
+        let _ = try InlineArray<3, String>(first: "first") { element in
+          if element == "first" { "second" } else { throw error }
+        }
+      }
+    }
+  }
 }
 
 //===----------------------------------------------------------------------===//
@@ -179,6 +223,24 @@ extension InlineArray where Element: ~Copyable {
 // MARK: - StdlibUnittest Additions
 //===----------------------------------------------------------------------===//
 
+/// Tests that the given closure always throws an error.
+func _expectThrows<Failure: Error>(
+  stackTrace: SourceLocStack = SourceLocStack(),
+  showFrame: Bool = true,
+  file: String = #file,
+  line: UInt = #line,
+  _ body: () throws(Failure) -> Void
+) {
+  do throws(Failure) {
+    try body()
+    expectUnreachable(
+      stackTrace: stackTrace.pushIf(showFrame, file: file, line: line)
+    )
+  } catch {
+    return
+  }
+}
+
 /// Tests the properties and subscripts of an `InlineArray` instance, by
 /// comparing them against an `Array` oracle with the expected elements.
 @available(SwiftStdlib 6.2, *)