Make styled range store generic (CodeEditApp#323)

### Description

This makes the `StyledRangeStore` type generic and `Sendable`. This type
was originally created for storing relative ranges of highlight values
(captures and modifiers). It excels at storing values for subranges of
data even for large documents. I'm hoping to make this type a generic
type we can use in other places in the package, like code folding, to
store document state that needs to be maintained in lock-step with the
document's real contents.

Detailed changes:
- Renamed `StyledRangeStore` to `RangeStore`, as well as all associated
types.
- Made `RangeStore` a value type (struct) with copy-on-write semantics,
allowing for it to be concurrency safe and `Sendable`.
> This doesn't have any effect on performance with the existing
highlighter code. The highlighter code modifies the storage objects it
uses in-place, so there is no copying necessary, only mutating.
- Made `RangeStore` store a new, generic, `RangeStoreElement` type.
- Updated `StyledRangeContainer` to use the updated `RangeStore`, with a
custom element type that stores captures and modifiers.
- Updated `StyledRangeContainer` to use a raised version of the
`combineLower[Higher]Priority` methods only where they're relevant
(instead of the requirement being on `RangeStoreElement`).
- Updated relevant tests.

### Related Issues

* CodeEditApp#43

### Checklist

- [x] I read and understood the [contributing
guide](https://github.com/CodeEditApp/CodeEdit/blob/main/CONTRIBUTING.md)
as well as the [code of
conduct](https://github.com/CodeEditApp/CodeEdit/blob/main/CODE_OF_CONDUCT.md)
- [x] The issues this PR addresses are related to each other
- [x] My changes generate no new warnings
- [x] My code builds and runs on my machine
- [x] My changes are all related to the related issue above
- [x] I documented my code

### Screenshots

No behavior changes. This is in prep for CodeEditApp#43, but also lays the
groundwork for other features using a type like this.

Author: thecoolwinter

Sources/CodeEditSourceEditor/Highlighting/Highlighter.swift

@@ -17,7 +17,7 @@ import OSLog
 ///
 /// This class manages multiple objects that help perform this task:
 /// - ``StyledRangeContainer``
-/// - ``StyledRangeStore``
+/// - ``RangeStore``
 /// - ``VisibleRangeProvider``
 /// - ``HighlightProviderState``
 ///
@@ -34,12 +34,12 @@ import OSLog
 /// |
 /// | Queries coalesced styles
 /// v
-/// +-------------------------------+             +-----------------------------+
-/// |    StyledRangeContainer       |   ------>   |      StyledRangeStore[]     |
-/// |                               |             |                             | Stores styles for one provider
-/// |  - manages combined ranges    |             |  - stores raw ranges &      |
-/// |  - layers highlight styles    |             |    captures                 |
-/// |  + getAttributesForRange()    |             +-----------------------------+
+/// +-------------------------------+             +-------------------------+
+/// |    StyledRangeContainer       |   ------>   |      RangeStore[]       |
+/// |                               |             |                         | Stores styles for one provider
+/// |  - manages combined ranges    |             |  - stores raw ranges &  |
+/// |  - layers highlight styles    |             |    captures             |
+/// |  + getAttributesForRange()    |             +-------------------------+
 /// +-------------------------------+
 /// ^
 /// | Sends highlighted runs
@@ -276,7 +276,7 @@ extension Highlighter: StyledRangeContainerDelegate {
             guard let range = NSRange(location: offset, length: run.length).intersection(range) else {
                 continue
             }
-            storage?.setAttributes(attributeProvider.attributesFor(run.capture), range: range)
+            storage?.setAttributes(attributeProvider.attributesFor(run.value?.capture), range: range)
             offset += range.length
         }
 

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeContainer.swift

@@ -18,7 +18,34 @@ protocol StyledRangeContainerDelegate: AnyObject {
 /// See ``runsIn(range:)`` for more details on how conflicting highlights are handled.
 @MainActor
 class StyledRangeContainer {
-    var _storage: [ProviderID: StyledRangeStore] = [:]
+    struct StyleElement: RangeStoreElement, CustomDebugStringConvertible {
+        var capture: CaptureName?
+        var modifiers: CaptureModifierSet
+
+        var isEmpty: Bool {
+            capture == nil && modifiers.isEmpty
+        }
+
+        func combineLowerPriority(_ other: StyleElement?) -> StyleElement {
+            StyleElement(
+                capture: self.capture ?? other?.capture,
+                modifiers: modifiers.union(other?.modifiers ?? [])
+            )
+        }
+
+        func combineHigherPriority(_ other: StyleElement?) -> StyleElement {
+            StyleElement(
+                capture: other?.capture ?? self.capture,
+                modifiers: modifiers.union(other?.modifiers ?? [])
+            )
+        }
+
+        var debugDescription: String {
+            "\(capture?.stringValue ?? "(empty)"), \(modifiers)"
+        }
+    }
+
+    var _storage: [ProviderID: RangeStore<StyleElement>] = [:]
     weak var delegate: StyledRangeContainerDelegate?
 
     /// Initialize the container with a list of provider identifiers. Each provider is given an id, they should be
@@ -28,13 +55,13 @@ class StyledRangeContainer {
     ///   - providers: An array of identifiers given to providers.
     init(documentLength: Int, providers: [ProviderID]) {
         for provider in providers {
-            _storage[provider] = StyledRangeStore(documentLength: documentLength)
+            _storage[provider] = RangeStore<StyleElement>(documentLength: documentLength)
         }
     }
 
     func addProvider(_ id: ProviderID, documentLength: Int) {
         assert(!_storage.keys.contains(id), "Provider already exists")
-        _storage[id] = StyledRangeStore(documentLength: documentLength)
+        _storage[id] = RangeStore<StyleElement>(documentLength: documentLength)
     }
 
     func removeProvider(_ id: ProviderID) {
@@ -55,10 +82,18 @@ class StyledRangeContainer {
     ///
     /// - Parameter range: The range to query.
     /// - Returns: An array of continuous styled runs.
-    func runsIn(range: NSRange) -> [StyledRangeStoreRun] {
+    func runsIn(range: NSRange) -> [RangeStoreRun<StyleElement>] {
+        func combineLowerPriority(_ lhs: inout RangeStoreRun<StyleElement>, _ rhs: RangeStoreRun<StyleElement>) {
+            lhs.value = lhs.value?.combineLowerPriority(rhs.value) ?? rhs.value
+        }
+
+        func combineHigherPriority(_ lhs: inout RangeStoreRun<StyleElement>, _ rhs: RangeStoreRun<StyleElement>) {
+            lhs.value = lhs.value?.combineHigherPriority(rhs.value) ?? rhs.value
+        }
+
         // Ordered by priority, lower = higher priority.
         var allRuns = _storage.sorted(by: { $0.key < $1.key }).map { $0.value.runs(in: range.intRange) }
-        var runs: [StyledRangeStoreRun] = []
+        var runs: [RangeStoreRun<StyleElement>] = []
 
         var minValue = allRuns.compactMap { $0.last }.enumerated().min(by: { $0.1.length < $1.1.length })
 
@@ -70,9 +105,9 @@ class StyledRangeContainer {
             for idx in (0..<allRuns.count).reversed() where idx != minRunIdx {
                 guard let last = allRuns[idx].last else { continue }
                 if idx < minRunIdx {
-                    minRun.combineHigherPriority(last)
+                    combineHigherPriority(&minRun, last)
                 } else {
-                    minRun.combineLowerPriority(last)
+                    combineLowerPriority(&minRun, last)
                 }
 
                 if last.length == minRun.length {
@@ -93,8 +128,8 @@ class StyledRangeContainer {
     }
 
     func storageUpdated(replacedContentIn range: Range<Int>, withCount newLength: Int) {
-        _storage.values.forEach {
-            $0.storageUpdated(replacedCharactersIn: range, withCount: newLength)
+        for key in _storage.keys {
+            _storage[key]?.storageUpdated(replacedCharactersIn: range, withCount: newLength)
         }
     }
 }
@@ -109,11 +144,11 @@ extension StyledRangeContainer: HighlightProviderStateDelegate {
     ///   - rangeToHighlight: The range to apply the highlights to.
     func applyHighlightResult(provider: ProviderID, highlights: [HighlightRange], rangeToHighlight: NSRange) {
         assert(rangeToHighlight != .notFound, "NSNotFound is an invalid highlight range")
-        guard let storage = _storage[provider] else {
+        guard var storage = _storage[provider] else {
             assertionFailure("No storage found for the given provider: \(provider)")
             return
         }
-        var runs: [StyledRangeStoreRun] = []
+        var runs: [RangeStoreRun<StyleElement>] = []
         var lastIndex = rangeToHighlight.lowerBound
 
         for highlight in highlights {
@@ -123,10 +158,9 @@ extension StyledRangeContainer: HighlightProviderStateDelegate {
                 continue // Skip! Overlapping
             }
             runs.append(
-                StyledRangeStoreRun(
+                RangeStoreRun<StyleElement>(
                     length: highlight.range.length,
-                    capture: highlight.capture,
-                    modifiers: highlight.modifiers
+                    value: StyleElement(capture: highlight.capture, modifiers: highlight.modifiers)
                 )
             )
             lastIndex = highlight.range.max
@@ -137,6 +171,7 @@ extension StyledRangeContainer: HighlightProviderStateDelegate {
         }
 
         storage.set(runs: runs, for: rangeToHighlight.intRange)
+        _storage[provider] = storage
         delegate?.styleContainerDidUpdate(in: rangeToHighlight)
     }
 }

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeStore/StyledRangeStore+OffsetMetric.swift

@@ -1,13 +1,13 @@
 //
-//  StyledRangeStore+Internals.swift
+//  RangeStore+Internals.swift
 //  CodeEditSourceEditor
 //
 //  Created by Khan Winter on 10/25/24
 //
 
 import _RopeModule
 
-extension StyledRangeStore {
+extension RangeStore {
     /// Coalesce items before and after the given range.
     ///
     /// Compares the next run with the run at the given range. If they're the same, removes the next run and grows the
@@ -16,7 +16,7 @@ extension StyledRangeStore {
     /// rather than the queried one.
     ///
     /// - Parameter range: The range of the item to coalesce around.
-    func coalesceNearby(range: Range<Int>) {
+    mutating func coalesceNearby(range: Range<Int>) {
         var index = findIndex(at: range.lastIndex).index
         if index < _guts.endIndex && _guts.index(after: index) != _guts.endIndex {
             coalesceRunAfter(index: &index)
@@ -30,11 +30,11 @@ extension StyledRangeStore {
     }
 
     /// Check if the run and the run after it are equal, and if so remove the next one and concatenate the two.
-    private func coalesceRunAfter(index: inout Index) {
+    private mutating func coalesceRunAfter(index: inout Index) {
         let thisRun = _guts[index]
         let nextRun = _guts[_guts.index(after: index)]
 
-        if thisRun.styleCompare(nextRun) {
+        if thisRun.compareValue(nextRun) {
             _guts.update(at: &index, by: { $0.length += nextRun.length })
 
             var nextIndex = index

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeStore/StyledRangeStoreRun.swift

@@ -1,11 +1,11 @@
 //
-//  StyledRangeStore+FindIndex.swift
+//  RangeStore+FindIndex.swift
 //  CodeEditSourceEditor
 //
 //  Created by Khan Winter on 1/6/25.
 //
 
-extension StyledRangeStore {
+extension RangeStore {
     /// Finds a Rope index, given a string offset.
     /// - Parameter offset: The offset to query for.
     /// - Returns: The index of the containing element in the rope.

Sources/CodeEditSourceEditor/Highlighting/StyledRangeContainer/StyledRangeStore/StyledRangeStore+Coalesce.swift renamed to Sources/CodeEditSourceEditor/RangeStore/RangeStore+Coalesce.swift

@@ -0,0 +1,22 @@
+//
+//  RangeStore+OffsetMetric.swift
+//  CodeEditSourceEditor
+//
+//  Created by Khan Winter on 10/25/24
+//
+
+import _RopeModule
+
+extension RangeStore {
+    struct OffsetMetric: RopeMetric {
+        typealias Element = StoredRun
+
+        func size(of summary: RangeStore.StoredRun.Summary) -> Int {
+            summary.length
+        }
+
+        func index(at offset: Int, in element: RangeStore.StoredRun) -> Int {
+            return offset
+        }
+    }
+}