CircularBuffer

public struct CircularBuffer<Element> : CustomStringConvertible
extension CircularBuffer: Collection, MutableCollection
extension CircularBuffer: RandomAccessCollection
extension CircularBuffer: RangeReplaceableCollection
extension CircularBuffer: ExpressibleByArrayLiteral
extension CircularBuffer: Equatable where Element: Equatable
extension CircularBuffer: Hashable where Element: Hashable

An automatically expanding ring buffer implementation backed by a ContiguousArray. Even though this implementation will automatically expand if more elements than initialCapacity are stored, it’s advantageous to prevent expansions from happening frequently. Expansions will always force an allocation and a copy to happen.

Show on GitHub

Collection/MutableCollection implementation

  • Declaration

    Swift

    public typealias Element = Element
    Show on GitHub

  • Declaration

    Swift

    public typealias Indices = DefaultIndices<CircularBuffer<Element>>
    Show on GitHub

  • Undocumented

    Declaration

    Swift

    public typealias RangeType<Bound> = Range<Bound> where Bound : Strideable, Bound.Stride : SignedInteger
    Show on GitHub

  • Declaration

    Swift

    public typealias SubSequence = CircularBuffer<Element>
    Show on GitHub

  • Returns the position immediately after the given index.

    The successor of an index must be well defined. For an index i into a collection c, calling c.index(after: i) returns the same index every time.

    Declaration

    Swift

    @inlinable
public func index(after: Index) -> Index

    Parameters

    i

    A valid index of the collection. i must be less than endIndex.

    Return Value

    The index value immediately after i.

    Show on GitHub

  • Returns the index before index.

    Declaration

    Swift

    @inlinable
public func index(before: Index) -> Index
    Show on GitHub

  • Accesses the element at the specified index.

    You can subscript CircularBuffer with any valid index other than the CircularBuffer‘s end index. The end index refers to the position one past the last element of a collection, so it doesn’t correspond with an element.

    Complexity

    O(1)

    Declaration

    Swift

    @inlinable
public subscript(position: Index) -> Element { get set }

    Parameters

    position

    The position of the element to access. position must be a valid index of the collection that is not equal to the endIndex property.
    Show on GitHub

  • The position of the first element in a nonempty CircularBuffer.

    If the CircularBuffer is empty, startIndex is equal to endIndex.

    Declaration

    Swift

    @inlinable
public var startIndex: Index { get }
    Show on GitHub

  • The CircularBuffer‘s “past the end” position—that is, the position one greater than the last valid subscript argument.

    When you need a range that includes the last element of a collection, use the half-open range operator (..<) with endIndex. The ..< operator creates a range that doesn’t include the upper bound, so it’s always safe to use with endIndex.

    If the CircularBuffer is empty, endIndex is equal to startIndex.

    Declaration

    Swift

    @inlinable
public var endIndex: Index { get }
    Show on GitHub

  • Returns the distance between two indices.

    Unless the collection conforms to the BidirectionalCollection protocol, start must be less than or equal to end.

    Complexity

    O(1) if the collection conforms to RandomAccessCollection; otherwise, O(k), where k is the resulting distance.

    Declaration

    Swift

    @inlinable
public func distance(from start: CircularBuffer<Element>.Index, to end: CircularBuffer<Element>.Index) -> Int

    Parameters

    start

    A valid index of the collection.
    end

    Another valid index of the collection. If end is equal to start, the result is zero.

    Return Value

    The distance between start and end. The result can be negative only if the collection conforms to the BidirectionalCollection protocol.

    Show on GitHub

RandomAccessCollection implementation

  • Returns the index offset by distance from index.

    The following example obtains an index advanced four positions from a string’s starting index and then prints the character at that position.

    let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"

    The value passed as distance must not offset i beyond the bounds of the collection.

    Complexity

    O(1) if the collection conforms to RandomAccessCollection; otherwise, O(k), where k is the absolute value of distance.

    Declaration

    Swift

    @inlinable
public func index(_ i: Index, offsetBy distance: Int) -> Index

    Parameters

    i

    A valid index of the collection.
    distance

    The distance to offset i. distance must not be negative unless the collection conforms to the BidirectionalCollection protocol.

    Return Value

    An index offset by distance from the index i. If distance is positive, this is the same value as the result of distance calls to index(after:). If distance is negative, this is the same value as the result of abs(distance) calls to index(before:).

    Show on GitHub

  • Declaration

    Swift

    @inlinable
public subscript(bounds: Range<Index>) -> SubSequence { get set }
    Show on GitHub

  • Allocates a buffer that can hold up to initialCapacity elements and initialise an empty ring backed by the buffer. When the ring grows to more than initialCapacity elements the buffer will be expanded.

    Declaration

    Swift

    @inlinable
public init(initialCapacity: Int)
    Show on GitHub

  • Allocates an empty buffer.

    Declaration

    Swift

    @inlinable
public init()
    Show on GitHub

  • Append an element to the end of the ring buffer.

    Amortized O(1)

    Declaration

    Swift

    @inlinable
public mutating func append(_ value: Element)
    Show on GitHub

  • Prepend an element to the front of the ring buffer.

    Amortized O(1)

    Declaration

    Swift

    @inlinable
public mutating func prepend(_ value: Element)
    Show on GitHub

  • Return element offset from first element.

    O(1)

    Declaration

    Swift

    @inlinable
public subscript(offset offset: Int) -> Element { get set }
    Show on GitHub

  • Returns whether the ring is empty.

    Declaration

    Swift

    @inlinable
public var isEmpty: Bool { get }
    Show on GitHub

  • Returns the number of element in the ring.

    Declaration

    Swift

    @inlinable
public var count: Int { get }
    Show on GitHub

  • The total number of elements that the ring can contain without allocating new storage.

    Declaration

    Swift

    @inlinable
public var capacity: Int { get }
    Show on GitHub

  • Removes all members from the circular buffer whist keeping the capacity.

    Declaration

    Swift

    @inlinable
public mutating func removeAll(keepingCapacity: Bool = false)
    Show on GitHub

  • Modify the element at index.

    This function exists to provide a method of modifying the element in its underlying backing storage, instead of copying it out, modifying it, and copying it back in. This emulates the behaviour of the _modify accessor that is part of the generalized accessors work. That accessor is currently underscored and not safe to use, so this is the next best thing.

    Note that this function is not guaranteed to be fast. In particular, as it is both generic and accepts a closure it is possible that it will be slower than using the get/modify/set path that occurs with the subscript. If you are interested in using this function for performance you must test and verify that the optimisation applies correctly in your situation.

    Declaration

    Swift

    @inlinable
public mutating func modify<Result>(_ index: Index, _ modifyFunc: (inout Element) throws -> Result) rethrows -> Result

    Parameters

    index

    The index of the object that should be modified. If this index is invalid this function will trap.
    modifyFunc

    The function to apply to the modified object.
    Show on GitHub

CustomStringConvertible implementation

  • Returns a human readable description of the ring.

    Declaration

    Swift

    public var description: String { get }
    Show on GitHub

RangeReplaceableCollection

  • Removes and returns the first element of the CircularBuffer.

    Calling this method may invalidate all saved indices of this CircularBuffer. Do not rely on a previously stored index value after altering a CircularBuffer with any operation that can change its length.

    Complexity

    O(1)

    Declaration

    Swift

    @inlinable
public mutating func popFirst() -> Element?

    Return Value

    The first element of the CircularBuffer if the CircularBuffer is not empty; otherwise, nil.

    Show on GitHub

  • Removes and returns the last element of the CircularBuffer.

    Calling this method may invalidate all saved indices of this CircularBuffer. Do not rely on a previously stored index value after altering a CircularBuffer with any operation that can change its length.

    Complexity

    O(1)

    Declaration

    Swift

    @inlinable
public mutating func popLast() -> Element?

    Return Value

    The last element of the CircularBuffer if the CircularBuffer is not empty; otherwise, nil.

    Show on GitHub

  • Removes the specified number of elements from the end of the CircularBuffer.

    Attempting to remove more elements than exist in the CircularBuffer triggers a runtime error.

    Calling this method may invalidate all saved indices of this CircularBuffer. Do not rely on a previously stored index value after altering a CircularBuffer with any operation that can change its length.

    Complexity

    O(k), where k is the specified number of elements.

    Declaration

    Swift

    @inlinable
public mutating func removeLast(_ k: Int)

    Parameters

    k

    The number of elements to remove from the CircularBuffer. k must be greater than or equal to zero and must not exceed the number of elements in the CircularBuffer.
    Show on GitHub

  • Removes the specified number of elements from the beginning of the CircularBuffer.

    Calling this method may invalidate any existing indices for use with this CircularBuffer.

    Complexity

    O(k), where k is the specified number of elements.

    Declaration

    Swift

    @inlinable
public mutating func removeFirst(_ k: Int)

    Parameters

    k

    The number of elements to remove. k must be greater than or equal to zero and must not exceed the number of elements in the CircularBuffer.
    Show on GitHub

  • Removes and returns the first element of the CircularBuffer.

    The CircularBuffer must not be empty.

    Calling this method may invalidate any existing indices for use with this CircularBuffer.

    Complexity

    O(1)

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func removeFirst() -> Element

    Return Value

    The removed element.

    Show on GitHub

  • Removes and returns the last element of the CircularBuffer.

    The CircularBuffer must not be empty.

    Calling this method may invalidate all saved indices of this CircularBuffer. Do not rely on a previously stored index value after altering the CircularBuffer with any operation that can change its length.

    Complexity

    O(1)

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func removeLast() -> Element

    Return Value

    The last element of the CircularBuffer.

    Show on GitHub

  • Replaces the specified subrange of elements with the given CircularBuffer.

    O(n) where n is the length of the new elements collection if the subrange equals to n

    O(m) where m is the combined length of the collection and newElements

    Declaration

    Swift

    @inlinable
public mutating func replaceSubrange<C>(_ subrange: Range<Index>, with newElements: C) where Element == C.Element, C : Collection

    Parameters

    subrange

    The subrange of the collection to replace. The bounds of the range must be valid indices of the CircularBuffer.
    newElements

    The new elements to add to the CircularBuffer.
    Show on GitHub

  • Removes the elements in the specified subrange from the circular buffer.

    Declaration

    Swift

    @inlinable
public mutating func removeSubrange(_ bounds: Range<Index>)

    Parameters

    bounds

    The range of the circular buffer to be removed. The bounds of the range must be valid indices of the collection.
    Show on GitHub

  • Removes & returns the item at position from the buffer

    O(1) if the position is headIdx or tailIdx. otherwise O(n) where n is the number of elements between position and tailIdx.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func remove(at position: Index) -> Element

    Parameters

    position

    The index of the item to be removed from the buffer.
    Show on GitHub

  • The first Element of the CircularBuffer (or nil if empty).

    Declaration

    Swift

    @inlinable
public var first: Element? { get }
    Show on GitHub

  • Prepares the CircularBuffer to store the specified number of elements.

    Declaration

    Swift

    @inlinable
public mutating func reserveCapacity(_ minimumCapacity: Int)
    Show on GitHub

  • Declaration

    Swift

    public init(arrayLiteral elements: Element...)
    Show on GitHub

Available where Element: Equatable

  • Declaration

    Swift

    public static func == (lhs: CircularBuffer, rhs: CircularBuffer) -> Bool
    Show on GitHub

Available where Element: Hashable