RingBuffer

public struct RingBuffer

An implementation of a Circular Buffer.

The ring buffer is agnostic about the data type it stores, and deals directly with bytes.

Note

The buffer internally rounds up capacity to the nearest page size. To determine the actual capacity of the buffer, check the return value of capacity after initialization.

Note

This class is thread-safe.

Seealso

Circular Buffer on Wikipedia

Public Properties

  • The capacity of the buffer

    Declaration

    Swift

    public var capacity: Int
    Show on GitHub

  • The number of bytes currently stored in the buffer

    Declaration

    Swift

    public var count: Int
    Show on GitHub

  • The start position of the buffer

    Declaration

    Swift

    public private(set) var start: Int = 0
    Show on GitHub
  • end

    The end position of the buffer

    Declaration

    Swift

    public private(set) var end: Int = 0
    Show on GitHub

  • The number (in bytes) of data that is available in this buffer

    Declaration

    Swift

    public var availableData: Int
    Show on GitHub

  • The number (in bytes) of space that is available in this buffer

    Declaration

    Swift

    public var availableSpace: Int
    Show on GitHub

  • Returns true if the buffer is full

    Declaration

    Swift

    public var isFull: Bool
    Show on GitHub

  • Returns true if the buffer is empty, or if it contains 1 NULL byte

    Declaration

    Swift

    public var isEmpty: Bool
    Show on GitHub

  • The base address of the buffer

    Declaration

    Swift

    public var elementPointer: UnsafeMutablePointer<UInt8>
    Show on GitHub

Initializers

Public Functions

  • Append bytes to the buffer.

    Precondition

    count > 0 && count <= self.availableSpace

    Warning

    This method does not do any bounds checking, so be sure that count does not exceed availableSpace

    Declaration

    Swift

    public mutating func append(_ bytes: UnsafeRawPointer, count: Int)

    Parameters

    bytes

    A pointer to the bytes to copy into the data.
    count

    The number of bytes to copy.
    Show on GitHub

  • Append a buffer to the buffer.

    Precondition

    buffer.count <= self.availableSpace

    Warning

    This method does not do any bounds checking, so be sure that buffer.count does not exceed self.availableSpace

    Declaration

    Swift

    public mutating func append<SourceType>(_ buffer: UnsafeBufferPointer<SourceType>)

    Parameters

    buffer

    The buffer of bytes to append. The size is calculated from SourceType and buffer.count.
    Show on GitHub

  • Append a sequence of bytes to the ring buffer.

    Precondition

    count > 0 && count <= self.availableSpace

    Warning

    This method does not do any bounds checking, so be sure that contigous.count does not exceed self.availableSpace

    Declaration

    Swift

    public mutating func append<SourceType>(contentsOf contiguous: ContiguousArray<SourceType>)

    Parameters

    contiguous

    The sequence of bytes to add to the buffer. Internally, this method calls append<T>(_:UnsafeBufferPointer<T>).
    Show on GitHub

  • Append the contents of a Data structure to the buffer

    Warning

    This method does not do any bounds checking, so be sure that data.count does not exceed self.availableSpace

    Declaration

    Swift

    public mutating func append(_ data: Data)

    Parameters

    data

    The data structure to append to the buffer
    Show on GitHub

  • Write into the buffer, given pointer data and length

    Precondition

    count > 0

    Throws

    RingBufferError if an error was encountered

    Declaration

    Swift

    public mutating func write(from bytes: UnsafePointer<UInt8>, count: Int) throws -> Int

    Parameters

    from

    The bytes to write into the buffer
    count

    The number of bytes to write into the buffer

    Return Value

    The number of bytes read

    Show on GitHub

  • Write into the buffer, given pointer data and length

    Throws

    RingBufferError if an error was encountered

    Declaration

    Swift

    public mutating func write(from buffer: UnsafeBufferPointer<UInt8>) throws -> Int

    Parameters

    from

    The bytes to write into the buffer
    length

    The number of bytes to write into the buffer

    Return Value

    The number of bytes written into the buffer

    Show on GitHub

  • Write the contents of a string to the buffer

    Throws

    A RingBufferError if an error occured

    Declaration

    Swift

    public mutating func write(string: String) throws -> Int

    Parameters

    string

    The string to write to the buffer

    Return Value

    The number of bytes written to the buffer

    Show on GitHub

  • Write the contents of a Data object to the buffer

    Throws

    RingBufferError if an error occurs

    Declaration

    Swift

    public mutating func write(from data: Data) throws -> Int

    Parameters

    from

    The Data object that contains the data to write

    Return Value

    the number of bytes written

    Show on GitHub

  • Read count bytes from the buffer, into into

    Precondition

    count is greater than 0, and less than availableData

    Throws

    RingBufferError if an error was encountered

    Declaration

    Swift

    public mutating func read(into data: inout Data, count: Int) throws -> Int

    Parameters

    into

    A Data struct to write data into
    count

    The number of bytes to read

    Return Value

    The number of bytes read

    Show on GitHub

  • Get a string from the buffer

    Precondition

    amount is greater than 0

    Declaration

    Swift

    public mutating func gets(_ amount: Int) throws -> String

    Parameters

    amount

    The number of bytes to read
    Show on GitHub

  • Calls a closure with a pointer to the buffer’s contiguous storage.

    Often, the optimizer can eliminate bounds checks within an array algorithm, but when that fails, invoking the same algorithm on the buffer pointer passed into your closure lets you trade safety for speed.

    The following example shows how you can iterate over the contents of the buffer pointer:

    let numbers = [1, 2, 3, 4, 5]
let sum = numbers.withUnsafeBufferPointer { buffer -> Int in
    var result = 0
    for i in stride(from: buffer.startIndex, to: buffer.endIndex, by: 2) {
        result += buffer[i]
    }
    return result
}
// 'sum' == 9

    Seealso

    withUnsafeMutableBufferPointer, UnsafeBufferPointer

    Declaration

    Swift

    public func withUnsafeBufferPointer<ContentType, ResultType>(
    _ body: (UnsafeBufferPointer<ContentType>) throws -> ResultType
  ) rethrows -> ResultType

    Parameters

    body

    A closure with an UnsafeBufferPointer parameter that points to the contiguous storage for the array. If body has a return value, it is used as the return value for the withUnsafeBufferPointer(_:) method. The pointer argument is valid only for the duration of the closure’s execution.

    Return Value

    The return value of the body closure parameter, if any.

    Show on GitHub

  • Calls the given closure with a pointer to the buffer’s mutable contiguous

    Often, the optimizer can eliminate bounds checks within an array algorithm, but when that fails, invoking the same algorithm on the buffer pointer passed into your closure lets you trade safety for speed.

    The following example shows modifying the contents of the UnsafeMutableBufferPointer argument to body alters the contents of the array:

    var numbers = [1, 2, 3, 4, 5]
numbers.withUnsafeMutableBufferPointer { buffer in
    for i in stride(from: buffer.startIndex, to: buffer.endIndex - 1, by: 2) {
        swap(&buffer[i], &buffer[i + 1])
    }
}
print(numbers)
// Prints "[2, 1, 4, 3, 5]"

    Warning

    Do not rely on anything about self (the buffer that is the target of this method) during the execution of the body closure: It may not appear to have its correct value. Instead, use only the UnsafeMutableBufferPointer argument to body.

    Seealso

    withUnsafeBufferPointer, UnsafeMutableBufferPointer

    Declaration

    Swift

    public func withUnsafeMutableBufferPointer<ContentType, ResultType>(
    _ body: (UnsafeMutableBufferPointer<ContentType>) throws -> ResultType
  ) rethrows -> ResultType

    Parameters

    body

    A closure with an UnsafeMutableBufferPointer parameter that points to the contiguous storage for the buffer. If body has a return value, it is used as the return value for the withUnsafeMutableBufferPointer(_:) method. The pointer argument is valid only for the duration of the closure’s execution.

    Return Value

    The return value of the body closure parameter, if any.

    Show on GitHub

  • Access the bytes in the data.

    Warning

    The byte pointer argument should not be stored and used outside of the lifetime of the call to the closure.

    Declaration

    Swift

    public func withUnsafeBytes<ContentType, ResultType>(
    _ body: (UnsafePointer<ContentType>) throws -> ResultType
  ) rethrows -> ResultType
    Show on GitHub

  • Clear the buffer of any stored data

    Declaration

    Swift

    public mutating func clear()
    Show on GitHub