Make SyntaxCollection conform to RangeReplaceableCollection and remove add* methods on syntax nodes that have a collection as child

Conforming `SyntaxCollection` to `RangeReplaceableCollection` gives it a lot of the functions you know from `Swift.Array`.

And with those methods, we no longer need the `add*` methods on syntax nodes that have a syntax collection as their child.

Author: ahoppen

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SyntaxNodesFile.swift

@@ -203,6 +203,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
               ///                  `\(child.varOrCaseName)` collection.
               /// - returns: A copy of the receiver with the provided `\(raw: childElt)`
               ///            appended to its `\(child.varOrCaseName)` collection.
+              @available(*, deprecated, message: "Use node.\(child.varOrCaseName).append(newElement) instead")
               public func add\(raw: childElt)(_ element: \(raw: childEltType)) -> \(node.kind.syntaxType) {
                 var collection: RawSyntax
                 let arena = SyntaxArena()

Sources/SwiftSyntax/SyntaxCollection.swift

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public protocol SyntaxCollection: SyntaxProtocol, BidirectionalCollection, MutableCollection where Element: SyntaxProtocol {
+public protocol SyntaxCollection: SyntaxProtocol, BidirectionalCollection, MutableCollection, RangeReplaceableCollection where Element: SyntaxProtocol {
   associatedtype Iterator = SyntaxCollectionIterator<Element>
 
   /// The ``SyntaxKind`` of the syntax node that conforms to ``SyntaxCollection``.
@@ -33,6 +33,11 @@ extension SyntaxCollection {
     self.init(Syntax(data))!
   }
 
+  /// Create an empty ``SyntaxCollection`` with no children.
+  public init() {
+    self.init([])
+  }
+
   public init<Children: Sequence>(_ children: Children) where Children.Element == Element {
     let arena = SyntaxArena()
     // Extend the lifetime of children so their arenas don't get destroyed
@@ -89,6 +94,19 @@ extension SyntaxCollection {
     return node.indexInParent
   }
 
+  /// Replace the nodes in `subrange` by `newElements`.
+  public mutating func replaceSubrange(_ subrange: Range<SyntaxChildrenIndex>, with newElements: some Collection<Element>) {
+    // We only access the raw nodes of `newElements` below.
+    // Keep `newElements` alive so their arena doesn't get deallocated.
+    withExtendedLifetime(newElements) {
+      var newLayout = layoutView.formLayoutArray()
+      let layoutRangeLowerBound = (subrange.lowerBound.data?.indexInParent).map(Int.init) ?? newLayout.endIndex
+      let layoutRangeUpperBound = (subrange.upperBound.data?.indexInParent).map(Int.init) ?? newLayout.endIndex
+      newLayout.replaceSubrange(layoutRangeLowerBound..<layoutRangeUpperBound, with: newElements.map { $0.raw })
+      self = replacingLayout(newLayout)
+    }
+  }
+
   /// Creates a new collection by appending the provided syntax element
   /// to the children.
   ///
@@ -208,6 +226,55 @@ public struct SyntaxCollectionIterator<E: SyntaxProtocol>: IteratorProtocol {
   }
 }
 
+// MARK: Specializations of functions from RangeReplaceableCollection
+
+extension SyntaxCollection {
+  /// Returns a new ``SyntaxCollection`` that just contains the elements
+  /// satisfying the given predicate.
+  ///
+  /// - Parameter isIncluded: A closure that takes an element of the
+  ///   collection as its argument and returns a Boolean value indicating
+  ///   whether the element should be included in the returned collection.
+  /// - Returns: A ``SyntaxCollection`` of the elements that `isIncluded` allowed.
+  public func filter(_ isIncluded: (Element) throws -> Bool) rethrows -> Self {
+    // This implementation is mor performant than `RangeReplacableCollection.filter`
+    // because `RangeReplacableCollection.filter` calls `replaceSubrange` for
+    // every included element, which is an expensive operation on
+    // `SyntaxCollection` since all the parents need to be rewritten. It’s more
+    // efficient to filter all the elements first and then create a final result.
+    // Also, `RangeReplacableCollection.filter` creates an empty collection
+    // first and appends to that collection, which means that the filtered
+    // collection doesn’t have a parent. This implementation makes sure that
+    // the filtered sequence has the same parent
+    var result = self
+    result.replaceSubrange(self.startIndex..<self.endIndex, with: try Array(self).filter(isIncluded))
+    return result
+  }
+
+  /// Removes all elements from the collection.
+  ///
+  /// - Parameter keepCapacity: Ignored for `SyntaxCollection`
+  public mutating func removeAll(keepingCapacity keepCapacity: Bool = false) {
+    // The default implementation of this in `RangeReplacableCollection` creates
+    // a node without a parent, which is not what we want.
+    replaceSubrange(startIndex..<endIndex, with: EmptyCollection())
+  }
+
+  /// Creates a new collection by concatenating the elements of a sequence and a
+  /// collection. The parent of the new collection will be the parent of `rhs`
+  ///
+  /// - Parameters:
+  ///   - lhs: A collection or finite sequence.
+  ///   - rhs: A range-replaceable collection.
+  public static func + <Other: Sequence>(lhs: Other, rhs: Self) -> Self where Element == Other.Element {
+    // The standard implementation in `RangeReplacableCollection` does not
+    // maintain the parent of `rhs`. This implementation does.
+    var result = rhs
+    result.insert(contentsOf: Array(lhs), at: result.startIndex)
+    return result
+  }
+}
+
 /// Conformance to `BidirectionalCollection`.
 extension SyntaxCollection {
   public func makeIterator() -> SyntaxCollectionIterator<Element> {