Skip to content

Include notes about index mutation in span(after/before:) (+ other doc fixes) #541

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
natecook1000 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Include notes about index mutation in span(after/before:) (+ other doc fixes) #541

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions Sources/BasicContainers/RigidArray+Insertions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ extension RigidArray {
/// array at the specified position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -289,7 +289,7 @@ extension RigidArray {
/// array at the specified position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand All @@ -316,7 +316,7 @@ extension RigidArray {
/// Copies the elements of a span into this array at the specified position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -392,7 +392,7 @@ extension RigidArray {
/// position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -423,7 +423,7 @@ extension RigidArray {
/// position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved
Expand Down Expand Up @@ -452,7 +452,7 @@ extension RigidArray {
/// position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down
46 changes: 34 additions & 12 deletions Sources/BasicContainers/RigidArray.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,7 @@ extension RigidArray where Element: ~Copyable {
}

/// A Boolean value indicating whether this rigid array is fully populated.
///
/// If this property returns true, then the array's storage is at capacity,
/// and it cannot accommodate any additional elements.
///
Expand Down Expand Up @@ -210,6 +211,7 @@ extension RigidArray where Element: ~Copyable {
extension RigidArray where Element: ~Copyable {
/// Arbitrarily edit the storage underlying this array by invoking a
/// user-supplied closure with a mutable `OutputSpan` view over it.
///
/// This method calls its function argument precisely once, allowing it to
/// arbitrarily modify the contents of the output span it is given.
/// The argument is free to add, remove or reorder any items; however,
Expand Down Expand Up @@ -303,18 +305,22 @@ extension RigidArray where Element: ~Copyable {
/// start.
///
/// Valid indices consist of the position of every element and a "past the
/// end” position that’s not valid for use as a subscript argument.
/// end" position that's not valid for use as a subscript argument.
public typealias Index = Int

/// The position of the first element in a nonempty array. This is always zero.
/// The position of the first element in a nonempty array.
///
/// `startIndex` is always zero.
///
/// - Complexity: O(1)
@inlinable
@inline(__always)
public var startIndex: Int { 0 }

/// The array’s "past the end” position—that is, the position one greater than
/// the last valid subscript argument. This is always equal to array's count.
/// The array's "past the end" position—that is, the position one greater than
/// the last valid subscript argument.
///
/// `endIndex` is always equal to the array's count.
///
/// - Complexity: O(1)
@inlinable
Expand Down Expand Up @@ -389,10 +395,14 @@ extension RigidArray where Element: ~Copyable {
@available(SwiftStdlib 5.0, *)
extension RigidArray where Element: ~Copyable {
/// Return a borrowing span over the maximal storage chunk following the
/// specified position in the array. The span provides direct read-only access
/// to all array elements in the range `index ..< count`.
/// specified position in the array.
///
/// The returned span provides direct read-only access to all array elements
/// in the range `index ..< count`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `span(after:)` returns, `index` is equal to the array's
/// `endIndex`.
///
/// - Complexity: O(1)
@inlinable
Expand All @@ -402,10 +412,14 @@ extension RigidArray where Element: ~Copyable {
}

/// Return a borrowing span over the maximal storage chunk preceding the
/// specified position in the array. The span provides direct read-only access
/// to all array elements in the range `0 ..< index`.
/// specified position in the array.
///
/// The returned span provides direct read-only access to all array elements
/// in the range `0 ..< index`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `span(before:)` returns, `index` is equal to the array's
/// `startIndex`.
///
/// - Complexity: O(1)
@inlinable
Expand All @@ -418,10 +432,14 @@ extension RigidArray where Element: ~Copyable {
@available(SwiftStdlib 5.0, *)
extension RigidArray where Element: ~Copyable {
/// Return a mutable span over the maximal storage chunk following the
/// specified position in the array. The span provides direct mutating access
/// to all array elements in the range `index ..< count`.
/// specified position in the array.
///
/// The returned span provides direct mutating access to all array elements
/// in the range `index ..< count`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `mutableSpan(after:)` returns, `index` is equal to the array's
/// `endIndex`.
///
/// - Complexity: O(1)
@_lifetime(&self)
Expand All @@ -432,10 +450,14 @@ extension RigidArray where Element: ~Copyable {
}

/// Return a mutable span over the maximal storage chunk preceding the specified
/// position in the array. The span provides direct mutating access to all
/// array elements in the range `0 ..< index`.
/// position in the array.
///
/// The returned span provides direct mutating access to all array elements
/// in the range `0 ..< index`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `mutableSpan(before:)` returns, `index` is equal to the array's
/// `startIndex`.
///
/// - Complexity: O(1)
@_lifetime(&self)
Expand Down
12 changes: 6 additions & 6 deletions Sources/BasicContainers/UniqueArray+Insertions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ extension UniqueArray {
/// array at the specified position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -247,7 +247,7 @@ extension UniqueArray {
/// array at the specified position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -275,7 +275,7 @@ extension UniqueArray {
/// Copies the elements of a span into this array at the specified position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -305,7 +305,7 @@ extension UniqueArray {
/// position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down Expand Up @@ -340,7 +340,7 @@ extension UniqueArray {
/// position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved
Expand Down Expand Up @@ -372,7 +372,7 @@ extension UniqueArray {
/// position.
///
/// The new elements are inserted before the element currently at the
/// specified index. If you pass the array’s `endIndex` as the `index`
/// specified index. If you pass the array's `endIndex` as the `index`
/// parameter, then the new elements are appended to the end of the array.
///
/// All existing elements at or following the specified position are moved to
Expand Down
45 changes: 33 additions & 12 deletions Sources/BasicContainers/UniqueArray.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,7 @@ extension UniqueArray where Element: ~Copyable {
extension UniqueArray where Element: ~Copyable {
/// Arbitrarily edit the storage underlying this array by invoking a
/// user-supplied closure with a mutable `OutputSpan` view over it.
///
/// This method calls its function argument precisely once, allowing it to
/// arbitrarily modify the contents of the output span it is given.
/// The argument is free to add, remove or reorder any items; however,
Expand Down Expand Up @@ -194,18 +195,22 @@ extension UniqueArray where Element: ~Copyable {
/// start.
///
/// Valid indices consist of the position of every element and a "past the
/// end” position that’s not valid for use as a subscript argument.
/// end" position that's not valid for use as a subscript argument.
public typealias Index = Int

/// The position of the first element in a nonempty array. This is always zero.
/// The position of the first element in a nonempty array.
///
/// `startIndex` is always zero.
///
/// - Complexity: O(1)
@inlinable
@inline(__always)
public var startIndex: Int { _storage.startIndex }

/// The array’s "past the end” position—that is, the position one greater than
/// the last valid subscript argument. This is always equal to array's count.
/// The array's "past the end" position—that is, the position one greater than
/// the last valid subscript argument.
///
/// `endIndex` is always equal to the array's count.
///
/// - Complexity: O(1)
@inlinable
Expand Down Expand Up @@ -259,10 +264,14 @@ extension UniqueArray where Element: ~Copyable {
@available(SwiftStdlib 5.0, *)
extension UniqueArray where Element: ~Copyable {
/// Return a borrowing span over the maximal storage chunk following the
/// specified position in the array. The span provides direct read-only access
/// to all array elements in the range `index ..< count`.
/// specified position in the array.
///
/// The returned span provides direct read-only access to all array elements
/// in the range `index ..< count`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `span(after:)` returns, `index` is equal to the array's
/// `endIndex`.
///
/// - Complexity: O(1)
@inlinable
Expand All @@ -272,10 +281,14 @@ extension UniqueArray where Element: ~Copyable {
}

/// Return a borrowing span over the maximal storage chunk preceding the
/// specified position in the array. The span provides direct read-only access
/// to all array elements in the range `0 ..< index`.
/// specified position in the array.
///
/// The returned span provides direct read-only access to all array elements
/// in the range `0 ..< index`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `span(before:)` returns, `index` is equal to the array's
/// `startIndex`.
///
/// - Complexity: O(1)
@inlinable
Expand All @@ -288,10 +301,14 @@ extension UniqueArray where Element: ~Copyable {
@available(SwiftStdlib 5.0, *)
extension UniqueArray where Element: ~Copyable {
/// Return a mutable span over the maximal storage chunk following the
/// specified position in the array. The span provides direct mutating access
/// to all array elements in the range `index ..< count`.
/// specified position in the array.
///
/// The returned span provides direct mutating access to all array elements
/// in the range `index ..< count`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `mutableSpan(after:)` returns, `index` is equal to the array's
/// `endIndex`.
///
/// - Complexity: O(1)
@_lifetime(&self)
Expand All @@ -302,10 +319,14 @@ extension UniqueArray where Element: ~Copyable {
}

/// Return a mutable span over the maximal storage chunk preceding the specified
/// position in the array. The span provides direct mutating access to all
/// array elements in the range `0 ..< index`.
/// position in the array.
///
/// The returned span provides direct mutating access to all array elements
/// in the range `0 ..< index`.
///
/// - Parameter index: A valid index in the array, including the end index.
/// When `mutableSpan(before:)` returns, `index` is equal to the array's
/// `startIndex`.
///
/// - Complexity: O(1)
@_lifetime(&self)
Expand Down
2 changes: 1 addition & 1 deletion Sources/BitCollections/BitArray/BitArray+Collection.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ extension BitArray: RandomAccessCollection, MutableCollection {
@inlinable @inline(__always)
public var startIndex: Int { 0 }

/// The collection’s “past the end” position--that is, the position one step
/// The collection's "past the end" position--that is, the position one step
/// after the last valid subscript argument.
///
/// - Complexity: O(1)
Expand Down
2 changes: 1 addition & 1 deletion Sources/BitCollections/BitSet/BitSet+BidirectionalCollection.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ extension BitSet: Collection, BidirectionalCollection {
Index(_position: _read { $0.startIndex })
}

/// The collection’s “past the end” position--that is, the position one step
/// The collection's "past the end" position--that is, the position one step
/// after the last valid subscript argument.
///
/// - Complexity: O(1)
Expand Down
4 changes: 2 additions & 2 deletions Sources/BitCollections/BitSet/BitSet+Extras.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ extension BitSet {
}
}

/// Accesses the contiguous subrange of the collection’s elements that are
/// Accesses the contiguous subrange of the collection's elements that are
/// contained within a specific integer range.
///
/// let bits: BitSet = [2, 5, 6, 8, 9]
Expand Down Expand Up @@ -122,7 +122,7 @@ extension BitSet {
return Slice(base: self, bounds: bounds)
}

/// Accesses the contiguous subrange of the collection’s elements that are
/// Accesses the contiguous subrange of the collection's elements that are
/// contained within a specific integer range expression.
///
/// let bits: BitSet = [2, 5, 6, 8, 9]
Expand Down
6 changes: 3 additions & 3 deletions Sources/DequeModule/Deque+Collection.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ extension Deque: RandomAccessCollection {
@inline(__always)
public var startIndex: Int { 0 }

/// The deque’s “past the end” position—that is, the position one greater than
/// The deque's "past the end" position—that is, the position one greater than
/// the last valid subscript argument.
///
/// For an instance of `Deque`, `endIndex` is always equal to its `count`. If
Expand Down Expand Up @@ -349,7 +349,7 @@ extension Deque: RandomAccessCollection {
/// than or equal to `startIndex` and less than `endIndex`.
///
/// - Complexity: Reading an element from a deque is O(1). Writing is O(1)
/// unless the deque’s storage is shared with another deque, in which case
/// unless the deque's storage is shared with another deque, in which case
/// writing is O(`count`).
@inlinable
public subscript(index: Int) -> Element {
Expand Down Expand Up @@ -743,7 +743,7 @@ extension Deque: RangeReplaceableCollection {
/// Inserts a new element at the specified position.
///
/// The new element is inserted before the element currently at the specified
/// index. If you pass the deque’s `endIndex` as the `index` parameter, the
/// index. If you pass the deque's `endIndex` as the `index` parameter, the
/// new element is appended to the deque.
///
/// - Parameters:
Expand Down
2 changes: 1 addition & 1 deletion Sources/HashTreeCollections/TreeDictionary/TreeDictionary+Collection.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ extension TreeDictionary: Collection {
return Index(_root: _root.unmanaged, version: _version, path: path)
}

/// The collection’s “past the end” position—that is, the position one greater
/// The collection's "past the end" position—that is, the position one greater
/// than the last valid subscript argument.
///
/// - Complexity: O(1)
Expand Down
Loading
Loading