ByteBuffer

public struct ByteBuffer
extension ByteBuffer: CustomStringConvertible
extension ByteBuffer: Equatable
extension ByteBuffer: Hashable

ByteBuffer stores contiguously allocated raw bytes. It is a random and sequential accessible sequence of zero or more bytes (octets).

Allocation

Use allocator.buffer(capacity: desiredCapacity) to allocate a new ByteBuffer.

Supported types

A variety of types can be read/written from/to a ByteBuffer. Using Swift’s extension mechanism you can easily create ByteBuffer support for your own data types. Out of the box, ByteBuffer supports for example the following types (non-exhaustive list):

  • String/StaticString
  • Swift’s various (unsigned) integer types
  • Foundation‘s Data
  • [UInt8] and generally any Collection of UInt8

Random Access

For every supported type ByteBuffer usually contains two methods for random access:

  1. get<Type>(at: Int, length: Int) where <type> is for example String, Data, Bytes (for [UInt8])
  2. set<Type>(at: Int)

Example:

var buf = ...
buf.setString("Hello World", at: 0)
buf.moveWriterIndex(to: 11)
let helloWorld = buf.getString(at: 0, length: 11)

let written = buf.setInteger(17 as Int, at: 11)
buf.moveWriterIndex(forwardBy: written)
let seventeen: Int? = buf.getInteger(at: 11)

If needed, ByteBuffer will automatically resize its storage to accommodate your set request.

Sequential Access

ByteBuffer provides two properties which are indices into the ByteBuffer to support sequential access:

  • readerIndex, the index of the next readable byte
  • writerIndex, the index of the next byte to write

For every supported type ByteBuffer usually contains two methods for sequential access:

  1. read<Type>(length: Int) to read length bytes from the current readerIndex (and then advance the reader index by length bytes)
  2. write<Type>(Type) to write, advancing the writerIndex by the appropriate amount

Example:

 var buf = ...
 buf.writeString("Hello World")
 buf.writeInteger(17 as Int)
 let helloWorld = buf.readString(length: 11)
 let seventeen: Int = buf.readInteger()

Layout

+-------------------+------------------+------------------+
| discardable bytes |  readable bytes  |  writable bytes  |
|                   |     (CONTENT)    |                  |
+-------------------+------------------+------------------+
|                   |                  |                  |
0      <=      readerIndex   <=   writerIndex    <=    capacity

The 'discardable bytes’ are usually bytes that have already been read, they can however still be accessed using the random access methods. ‘Readable bytes’ are the bytes currently available to be read using the sequential access interface (read<Type>/write<Type>). Getting writableBytes (bytes beyond the writer index) is undefined behaviour and might yield arbitrary bytes (not 0 initialised).

Slicing

ByteBuffer supports slicing a ByteBuffer without copying the underlying storage.

Example:

var buf = ...
let dataBytes: [UInt8] = [0xca, 0xfe, 0xba, 0xbe]
let dataBytesLength = UInt32(dataBytes.count)
buf.writeInteger(dataBytesLength) /* the header */
buf.writeBytes(dataBytes) /* the data */
let bufDataBytesOnly = buf.getSlice(at: 4, length: dataBytes.count)
/* `bufDataByteOnly` and `buf` will share their storage */

Notes

All ByteBuffer methods that don’t contain the word ‘unsafe’ will only allow you to access the ‘readable bytes’.

Show on GitHub

Public Core API

  • The number of bytes writable until ByteBuffer will need to grow its underlying storage which will likely trigger a copy of the bytes.

    Declaration

    Swift

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

  • The number of bytes readable (readableBytes = writerIndex - readerIndex).

    Declaration

    Swift

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

  • The current capacity of the storage of this ByteBuffer, this is not constant and does not signify the number of bytes that have been written to this ByteBuffer.

    Declaration

    Swift

    public var capacity: Int { get }
    Show on GitHub

  • The current capacity of the underlying storage of this ByteBuffer. A COW slice of the buffer (e.g. readSlice(length: x)) will posses the same storageCapacity as the original buffer until new data is written.

    Declaration

    Swift

    public var storageCapacity: Int { get }
    Show on GitHub

  • Reserves enough space to store the specified number of bytes.

    This method will ensure that the buffer has space for at least as many bytes as requested. This includes any bytes already stored, and completely disregards the reader/writer indices. If the buffer already has space to store the requested number of bytes, this method will be a no-op.

    Declaration

    Swift

    public mutating func reserveCapacity(_ minimumCapacity: Int)

    Parameters

    minimumCapacity

    The minimum number of bytes this buffer must be able to store.
    Show on GitHub

  • Reserves enough space to write at least the specified number of bytes.

    This method will ensure that the buffer has enough writable space for at least as many bytes as requested. If the buffer already has space to write the requested number of bytes, this method will be a no-op.

    Declaration

    Swift

    public mutating func reserveCapacity(minimumWritableBytes: Int)

    Parameters

    minimumWritableBytes

    The minimum number of writable bytes this buffer must have.
    Show on GitHub

  • Yields a mutable buffer pointer containing this ByteBuffer‘s readable bytes. You may modify those bytes.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public mutating func withUnsafeMutableReadableBytes<T>(_ body: (UnsafeMutableRawBufferPointer) throws -> T) rethrows -> T

    Parameters

    body

    The closure that will accept the yielded bytes.

    Return Value

    The value returned by body.

    Show on GitHub

  • Yields the bytes currently writable (bytesWritable = capacity - writerIndex). Before reading those bytes you must first write to them otherwise you will trigger undefined behaviour. The writer index will remain unchanged.

    Note

    In almost all cases you should use writeWithUnsafeMutableBytes which will move the write pointer instead of this method

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public mutating func withUnsafeMutableWritableBytes<T>(_ body: (UnsafeMutableRawBufferPointer) throws -> T) rethrows -> T

    Parameters

    body

    The closure that will accept the yielded bytes and return the number of bytes written.

    Return Value

    The number of bytes written.

    Show on GitHub

  • This vends a pointer of the ByteBuffer at the writerIndex after ensuring that the buffer has at least minimumWritableBytes of writable bytes available.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func writeWithUnsafeMutableBytes(minimumWritableBytes: Int, _ body: (UnsafeMutableRawBufferPointer) throws -> Int) rethrows -> Int

    Parameters

    minimumWritableBytes

    The number of writable bytes to reserve capacity for before vending the ByteBuffer pointer to body.
    body

    The closure that will accept the yielded bytes and return the number of bytes written.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Undocumented

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func writeWithUnsafeMutableBytes(_ body: (UnsafeMutableRawBufferPointer) throws -> Int) rethrows -> Int
    Show on GitHub

  • This vends a pointer to the storage of the ByteBuffer. It’s marked as very unsafe because it might contain uninitialised memory and it’s undefined behaviour to read it. In most cases you should use withUnsafeReadableBytes.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public func withVeryUnsafeBytes<T>(_ body: (UnsafeRawBufferPointer) throws -> T) rethrows -> T
    Show on GitHub

  • This vends a pointer to the storage of the ByteBuffer. It’s marked as very unsafe because it might contain uninitialised memory and it’s undefined behaviour to read it. In most cases you should use withUnsafeMutableWritableBytes.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public mutating func withVeryUnsafeMutableBytes<T>(_ body: (UnsafeMutableRawBufferPointer) throws -> T) rethrows -> T
    Show on GitHub

  • Yields a buffer pointer containing this ByteBuffer‘s readable bytes.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public func withUnsafeReadableBytes<T>(_ body: (UnsafeRawBufferPointer) throws -> T) rethrows -> T

    Parameters

    body

    The closure that will accept the yielded bytes.

    Return Value

    The value returned by body.

    Show on GitHub

  • Yields a buffer pointer containing this ByteBuffer‘s readable bytes. You may hold a pointer to those bytes even after the closure returned iff you model the lifetime of those bytes correctly using the Unmanaged instance. If you don’t require the pointer after the closure returns, use withUnsafeReadableBytes.

    If you escape the pointer from the closure, you must call storageManagement.retain() to get ownership to the bytes and you also must call storageManagement.release() if you no longer require those bytes. Calls to retain and release must be balanced.

    Declaration

    Swift

    @inlinable
public func withUnsafeReadableBytesWithStorageManagement<T>(_ body: (UnsafeRawBufferPointer, Unmanaged<AnyObject>) throws -> T) rethrows -> T

    Parameters

    body

    The closure that will accept the yielded bytes and the storageManagement.

    Return Value

    The value returned by body.

    Show on GitHub

  • See withUnsafeReadableBytesWithStorageManagement and withVeryUnsafeBytes.

    Declaration

    Swift

    @inlinable
public func withVeryUnsafeBytesWithStorageManagement<T>(_ body: (UnsafeRawBufferPointer, Unmanaged<AnyObject>) throws -> T) rethrows -> T
    Show on GitHub

  • Returns a slice of size length bytes, starting at index. The ByteBuffer this is invoked on and the ByteBuffer returned will share the same underlying storage. However, the byte at index in this ByteBuffer will correspond to index 0 in the returned ByteBuffer. The readerIndex of the returned ByteBuffer will be 0, the writerIndex will be length.

    The selected bytes must be readable or else nil will be returned.

    Declaration

    Swift

    public func getSlice(at index: Int, length: Int) -> ByteBuffer?

    Parameters

    index

    The index the requested slice starts at.
    length

    The length of the requested slice.

    Return Value

    A ByteBuffer containing the selected bytes as readable bytes or nil if the selected bytes were not readable in the initial ByteBuffer.

    Show on GitHub

  • Discard the bytes before the reader index. The byte at index readerIndex before calling this method will be at index 0 after the call returns.

    Declaration

    Swift

    @discardableResult
public mutating func discardReadBytes() -> Bool

    Return Value

    true if one or more bytes have been discarded, false if there are no bytes to discard.

    Show on GitHub

  • The reader index or the number of bytes previously read from this ByteBuffer. readerIndex is 0 for a newly allocated ByteBuffer.

    Declaration

    Swift

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

  • The write index or the number of bytes previously written to this ByteBuffer. writerIndex is 0 for a newly allocated ByteBuffer.

    Declaration

    Swift

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

  • Set both reader index and writer index to 0. This will reset the state of this ByteBuffer to the state of a freshly allocated one, if possible without allocations. This is the cheapest way to recycle a ByteBuffer for a new use-case.

    Note

    This method will allocate if the underlying storage is referenced by another ByteBuffer. Even if an allocation is necessary this will be cheaper as the copy of the storage is elided.

    Declaration

    Swift

    public mutating func clear()
    Show on GitHub

  • Set both reader index and writer index to 0. This will reset the state of this ByteBuffer to the state of a freshly allocated one, if possible without allocations. This is the cheapest way to recycle a ByteBuffer for a new use-case.

    Note

    This method will allocate if the underlying storage is referenced by another ByteBuffer. Even if an allocation is necessary this will be cheaper as the copy of the storage is elided.

    Declaration

    Swift

    @available(*, deprecated, message: "Use an `Int` as the argument")
public mutating func clear(minimumCapacity: UInt32)

    Parameters

    minimumCapacity

    The minimum capacity that will be (re)allocated for this buffer
    Show on GitHub

  • Set both reader index and writer index to 0. This will reset the state of this ByteBuffer to the state of a freshly allocated one, if possible without allocations. This is the cheapest way to recycle a ByteBuffer for a new use-case.

    Note

    This method will allocate if the underlying storage is referenced by another ByteBuffer. Even if an allocation is necessary this will be cheaper as the copy of the storage is elided.

    Declaration

    Swift

    public mutating func clear(minimumCapacity: Int)

    Parameters

    minimumCapacity

    The minimum capacity that will be (re)allocated for this buffer
    Show on GitHub

Bytes ([UInt8]) APIs

  • Get length bytes starting at index and return the result as [UInt8]. This will not change the reader index. The selected bytes must be readable or else nil will be returned.

    Declaration

    Swift

    public func getBytes(at index: Int, length: Int) -> [UInt8]?

    Parameters

    index

    The starting index of the bytes of interest into the ByteBuffer.
    length

    The number of bytes of interest.

    Return Value

    A [UInt8] value containing the bytes of interest or nil if the bytes ByteBuffer are not readable.

    Show on GitHub

  • Read length bytes off this ByteBuffer, move the reader index forward by length bytes and return the result as [UInt8].

    Declaration

    Swift

    public mutating func readBytes(length: Int) -> [UInt8]?

    Parameters

    length

    The number of bytes to be read from this ByteBuffer.

    Return Value

    A [UInt8] value containing length bytes or nil if there aren’t at least length bytes readable.

    Show on GitHub

StaticString APIs

  • Write the static string into this ByteBuffer using UTF-8 encoding, moving the writer index forward appropriately.

    Declaration

    Swift

    @discardableResult
public mutating func writeStaticString(_ string: StaticString) -> Int

    Parameters

    string

    The string to write.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Write the static string into this ByteBuffer at index using UTF-8 encoding, moving the writer index forward appropriately.

    Declaration

    Swift

    public mutating func setStaticString(_ string: StaticString, at index: Int) -> Int

    Parameters

    string

    The string to write.
    index

    The index for the first serialized byte.

    Return Value

    The number of bytes written.

    Show on GitHub

String APIs

  • Write string into this ByteBuffer using UTF-8 encoding, moving the writer index forward appropriately.

    Declaration

    Swift

    @discardableResult
public mutating func writeString(_ string: String) -> Int

    Parameters

    string

    The string to write.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Write string into this ByteBuffer at index using UTF-8 encoding. Does not move the writer index.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func setString(_ string: String, at index: Int) -> Int

    Parameters

    string

    The string to write.
    index

    The index for the first serialized byte.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Get the string at index from this ByteBuffer decoding using the UTF-8 encoding. Does not move the reader index. The selected bytes must be readable or else nil will be returned.

    Declaration

    Swift

    public func getString(at index: Int, length: Int) -> String?

    Parameters

    index

    The starting index into ByteBuffer containing the string of interest.
    length

    The number of bytes making up the string.

    Return Value

    A String value containing the UTF-8 decoded selected bytes from this ByteBuffer or nil if the requested bytes are not readable.

    Show on GitHub

  • Read length bytes off this ByteBuffer, decoding it as String using the UTF-8 encoding. Move the reader index forward by length.

    Declaration

    Swift

    public mutating func readString(length: Int) -> String?

    Parameters

    length

    The number of bytes making up the string.

    Return Value

    A String value deserialized from this ByteBuffer or nil if there aren’t at least length bytes readable.

    Show on GitHub

Substring APIs

  • Write substring into this ByteBuffer using UTF-8 encoding, moving the writer index forward appropriately.

    Declaration

    Swift

    @discardableResult
public mutating func writeSubstring(_ substring: Substring) -> Int

    Parameters

    substring

    The substring to write.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Write substring into this ByteBuffer at index using UTF-8 encoding. Does not move the writer index.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func setSubstring(_ substring: Substring, at index: Int) -> Int

    Parameters

    substring

    The substring to write.
    index

    The index for the first serilized byte.

    Return Value

    The number of bytes written

    Show on GitHub

DispatchData APIs

  • Write dispatchData into this ByteBuffer, moving the writer index forward appropriately.

    Declaration

    Swift

    @discardableResult
public mutating func writeDispatchData(_ dispatchData: DispatchData) -> Int

    Parameters

    dispatchData

    The DispatchData instance to write to the ByteBuffer.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Write dispatchData into this ByteBuffer at index. Does not move the writer index.

    Declaration

    Swift

    @discardableResult
public mutating func setDispatchData(_ dispatchData: DispatchData, at index: Int) -> Int

    Parameters

    dispatchData

    The DispatchData to write.
    index

    The index for the first serialized byte.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Get the bytes at index from this ByteBuffer as a DispatchData. Does not move the reader index. The selected bytes must be readable or else nil will be returned.

    Declaration

    Swift

    public func getDispatchData(at index: Int, length: Int) -> DispatchData?

    Parameters

    index

    The starting index into ByteBuffer containing the string of interest.
    length

    The number of bytes.

    Return Value

    A DispatchData value deserialized from this ByteBuffer or nil if the requested bytes are not readable.

    Show on GitHub

  • Read length bytes off this ByteBuffer and return them as a DispatchData. Move the reader index forward by length.

    Declaration

    Swift

    public mutating func readDispatchData(length: Int) -> DispatchData?

    Parameters

    length

    The number of bytes.

    Return Value

    A DispatchData value containing the bytes from this ByteBuffer or nil if there aren’t at least length bytes readable.

    Show on GitHub

Other APIs

  • Yields an immutable buffer pointer containing this ByteBuffer‘s readable bytes. Will move the reader index by the number of bytes returned by body.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func readWithUnsafeReadableBytes(_ body: (UnsafeRawBufferPointer) throws -> Int) rethrows -> Int

    Parameters

    body

    The closure that will accept the yielded bytes and returns the number of bytes it processed.

    Return Value

    The number of bytes read.

    Show on GitHub

  • Yields an immutable buffer pointer containing this ByteBuffer‘s readable bytes. Will move the reader index by the number of bytes body returns in the first tuple component.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public mutating func readWithUnsafeReadableBytes<T>(_ body: (UnsafeRawBufferPointer) throws -> (Int, T)) rethrows -> T

    Parameters

    body

    The closure that will accept the yielded bytes and returns the number of bytes it processed along with some other value.

    Return Value

    The value body returned in the second tuple component.

    Show on GitHub

  • Yields a mutable buffer pointer containing this ByteBuffer‘s readable bytes. You may modify the yielded bytes. Will move the reader index by the number of bytes returned by body but leave writer index as it was.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func readWithUnsafeMutableReadableBytes(_ body: (UnsafeMutableRawBufferPointer) throws -> Int) rethrows -> Int

    Parameters

    body

    The closure that will accept the yielded bytes and returns the number of bytes it processed.

    Return Value

    The number of bytes read.

    Show on GitHub

  • Yields a mutable buffer pointer containing this ByteBuffer‘s readable bytes. You may modify the yielded bytes. Will move the reader index by the number of bytes body returns in the first tuple component but leave writer index as it was.

    Warning

    Do not escape the pointer from the closure for later use.

    Declaration

    Swift

    @inlinable
public mutating func readWithUnsafeMutableReadableBytes<T>(_ body: (UnsafeMutableRawBufferPointer) throws -> (Int, T)) rethrows -> T

    Parameters

    body

    The closure that will accept the yielded bytes and returns the number of bytes it processed along with some other value.

    Return Value

    The value body returned in the second tuple component.

    Show on GitHub

  • Copy buffer‘s readable bytes into this ByteBuffer starting at index. Does not move any of the reader or writer indices.

    Declaration

    Swift

    @available(*, deprecated, renamed: "setBuffer(_:at:﹚")
@discardableResult
public mutating func set(buffer: ByteBuffer, at index: Int) -> Int

    Parameters

    buffer

    The ByteBuffer to copy.
    index

    The index for the first byte.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Copy buffer‘s readable bytes into this ByteBuffer starting at index. Does not move any of the reader or writer indices.

    Declaration

    Swift

    @discardableResult
public mutating func setBuffer(_ buffer: ByteBuffer, at index: Int) -> Int

    Parameters

    buffer

    The ByteBuffer to copy.
    index

    The index for the first byte.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Write buffer‘s readable bytes into this ByteBuffer starting at writerIndex. This will move both this ByteBuffer’s writer index as well as buffer’s reader index by the number of bytes readable in buffer.

    Declaration

    Swift

    @discardableResult
public mutating func writeBuffer(_ buffer: inout ByteBuffer) -> Int

    Parameters

    buffer

    The ByteBuffer to write.

    Return Value

    The number of bytes written to this ByteBuffer which is equal to the number of bytes read from buffer.

    Show on GitHub

  • Write bytes, a Sequence of UInt8 into this ByteBuffer. Moves the writer index forward by the number of bytes written.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func writeBytes<Bytes>(_ bytes: Bytes) -> Int where Bytes : Sequence, Bytes.Element == UInt8

    Parameters

    bytes

    A Collection of UInt8 to be written.

    Return Value

    The number of bytes written or bytes.count.

    Show on GitHub

  • Write bytes into this ByteBuffer. Moves the writer index forward by the number of bytes written.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func writeBytes(_ bytes: UnsafeRawBufferPointer) -> Int

    Parameters

    bytes

    An UnsafeRawBufferPointer

    Return Value

    The number of bytes written or bytes.count.

    Show on GitHub

  • Writes byte count times. Moves the writer index forward by the number of bytes written.

    Declaration

    Swift

    @discardableResult
public mutating func writeRepeatingByte(_ byte: UInt8, count: Int) -> Int

    Parameters

    byte

    The UInt8 byte to repeat.
    count

    How many times to repeat the given byte

    Return Value

    How many bytes were written.

    Show on GitHub

  • Sets the given byte count times at the given index. Will reserve more memory if necessary. Does not move the writer index.

    Declaration

    Swift

    @discardableResult
public mutating func setRepeatingByte(_ byte: UInt8, count: Int, at index: Int) -> Int

    Parameters

    byte

    The UInt8 byte to repeat.
    count

    How many times to repeat the given byte

    Return Value

    How many bytes were written.

    Show on GitHub

  • Slice the readable bytes off this ByteBuffer without modifying the reader index. This method will return a ByteBuffer sharing the underlying storage with the ByteBuffer the method was invoked on. The returned ByteBuffer will contain the bytes in the range readerIndex..<writerIndex of the original ByteBuffer.

    Note

    Because ByteBuffer implements copy-on-write a copy of the storage will be automatically triggered when either of the ByteBuffers sharing storage is written to.

    Declaration

    Swift

    public func slice() -> ByteBuffer

    Return Value

    A ByteBuffer sharing storage containing the readable bytes only.

    Show on GitHub

  • Slice length bytes off this ByteBuffer and move the reader index forward by length. If enough bytes are readable the ByteBuffer returned by this method will share the underlying storage with the ByteBuffer the method was invoked on. The returned ByteBuffer will contain the bytes in the range readerIndex..<(readerIndex + length) of the original ByteBuffer. The readerIndex of the returned ByteBuffer will be 0, the writerIndex will be length.

    Note

    Because ByteBuffer implements copy-on-write a copy of the storage will be automatically triggered when either of the ByteBuffers sharing storage is written to.

    Declaration

    Swift

    public mutating func readSlice(length: Int) -> ByteBuffer?

    Parameters

    length

    The number of bytes to slice off.

    Return Value

    A ByteBuffer sharing storage containing length bytes or nil if the not enough bytes were readable.

    Show on GitHub

  • Undocumented

    Declaration

    Swift

    @discardableResult
public mutating func writeImmutableBuffer(_ buffer: ByteBuffer) -> Int
    Show on GitHub

  • Return an empty ByteBuffer allocated with ByteBufferAllocator().

    Calling this constructor will not allocate because it will return a ByteBuffer that wraps a shared storage object. As soon as you write to the constructed buffer however, you will incur an allocation because a copy-on-write will happen.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator it is recommended using channel.allocator.buffer(capacity: 0). This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    @inlinable
public init()
    Show on GitHub

  • Create a fresh ByteBuffer containing the bytes of the string encoded as UTF-8.

    This will allocate a new ByteBuffer with enough space to fit string and potentially some extra space using the default allocator.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(string:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeString instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    public init(string: String)
    Show on GitHub

  • Create a fresh ByteBuffer containing the bytes of the string encoded as UTF-8.

    This will allocate a new ByteBuffer with enough space to fit string and potentially some extra space using the default allocator.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(substring:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeSubstring instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    public init(substring string: Substring)
    Show on GitHub

  • Create a fresh ByteBuffer containing the bytes of the string encoded as UTF-8.

    This will allocate a new ByteBuffer with enough space to fit string and potentially some extra space using the default allocator.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(staticString:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeStaticString instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    public init(staticString string: StaticString)
    Show on GitHub

  • Create a fresh ByteBuffer containing the bytes.

    This will allocate a new ByteBuffer with enough space to fit bytes and potentially some extra space using the default allocator.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(bytes:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeBytes instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    @inlinable
public init<Bytes>(bytes: Bytes) where Bytes : Sequence, Bytes.Element == UInt8
    Show on GitHub

  • Create a fresh ByteBuffer containing the bytes of the byte representation in the given endianness of integer.

    This will allocate a new ByteBuffer with enough space to fit integer and potentially some extra space using the default allocator.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(integer:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeInteger instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    @inlinable
public init<I>(integer: I, endianness: Endianness = .big, as: I.Type = I.self) where I : FixedWidthInteger
    Show on GitHub

  • Create a fresh ByteBuffer containing count repetitions of byte.

    This will allocate a new ByteBuffer with at least count bytes.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(repeating:count:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeRepeatingByte instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    public init(repeating byte: UInt8, count: Int)
    Show on GitHub

  • Create a fresh ByteBuffer containing the readable bytes of buffer.

    This may allocate a new ByteBuffer with enough space to fit buffer and potentially some extra space using the default allocator.

    Note

    Use this method only if you deliberately want to reallocate a potentially smaller ByteBuffer than the one you already have. Given that ByteBuffer is a value type, defensive copies are not necessary. If you have a ByteBuffer but would like the readerIndex to start at 0, consider readSlice instead.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(buffer:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeImmutableBuffer instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    public init(buffer: ByteBuffer)
    Show on GitHub

  • Create a fresh ByteBuffer containing the bytes contained in the given DispatchData.

    This will allocate a new ByteBuffer with enough space to fit the bytes of the DispatchData and potentially some extra space using the default allocator.

    • info: If you have access to a Channel, ChannelHandlerContext, or ByteBufferAllocator we recommend using channel.allocator.buffer(dispatchData:). Or if you want to write multiple items into the buffer use channel.allocator.buffer(capacity: ...) to allocate a ByteBuffer of the right size followed by a writeDispatchData instead of using this method. This allows SwiftNIO to do accounting and optimisations of resources acquired for operations on a given Channel in the future.

    Declaration

    Swift

    public init(dispatchData: DispatchData)
    Show on GitHub

  • A String describing this ByteBuffer. Example:

    ByteBuffer { readerIndex: 0, writerIndex: 4, readableBytes: 4, capacity: 512, storageCapacity: 1024, slice: 256..<768, storage: 0x0000000103001000 (1024 bytes)}

    The format of the description is not API.

    Declaration

    Swift

    public var description: String { get }

    Return Value

    A description of this ByteBuffer.

    Show on GitHub

  • A String describing this ByteBuffer with some portion of the readable bytes dumped too. Example:

    ByteBuffer { readerIndex: 0, writerIndex: 4, readableBytes: 4, capacity: 512, slice: 256..<768, storage: 0x0000000103001000 (1024 bytes)}
readable bytes (max 1k): [ 00 01 02 03 ]

    The format of the description is not API.

    Declaration

    Swift

    public var debugDescription: String { get }

    Return Value

    A description of this ByteBuffer useful for debugging.

    Show on GitHub

  • Copy the collection of bytes into the ByteBuffer at index. Does not move the writer index.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func setBytes<Bytes>(_ bytes: Bytes, at index: Int) -> Int where Bytes : Sequence, Bytes.Element == UInt8
    Show on GitHub

  • Copy bytes into the ByteBuffer at index. Does not move the writer index.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func setBytes(_ bytes: UnsafeRawBufferPointer, at index: Int) -> Int
    Show on GitHub

  • Move the reader index forward by offset bytes.

    Warning

    By contract the bytes between (including) readerIndex and (excluding) writerIndex must be initialised, ie. have been written before. Also the readerIndex must always be less than or equal to the writerIndex. Failing to meet either of these requirements leads to undefined behaviour.

    Declaration

    Swift

    public mutating func moveReaderIndex(forwardBy offset: Int)

    Parameters

    offset

    The number of bytes to move the reader index forward by.
    Show on GitHub

  • Set the reader index to offset.

    Warning

    By contract the bytes between (including) readerIndex and (excluding) writerIndex must be initialised, ie. have been written before. Also the readerIndex must always be less than or equal to the writerIndex. Failing to meet either of these requirements leads to undefined behaviour.

    Declaration

    Swift

    public mutating func moveReaderIndex(to offset: Int)

    Parameters

    offset

    The offset in bytes to set the reader index to.
    Show on GitHub

  • Move the writer index forward by offset bytes.

    Warning

    By contract the bytes between (including) readerIndex and (excluding) writerIndex must be initialised, ie. have been written before. Also the readerIndex must always be less than or equal to the writerIndex. Failing to meet either of these requirements leads to undefined behaviour.

    Declaration

    Swift

    public mutating func moveWriterIndex(forwardBy offset: Int)

    Parameters

    offset

    The number of bytes to move the writer index forward by.
    Show on GitHub

  • Set the writer index to offset.

    Warning

    By contract the bytes between (including) readerIndex and (excluding) writerIndex must be initialised, ie. have been written before. Also the readerIndex must always be less than or equal to the writerIndex. Failing to meet either of these requirements leads to undefined behaviour.

    Declaration

    Swift

    public mutating func moveWriterIndex(to offset: Int)

    Parameters

    offset

    The offset in bytes to set the reader index to.
    Show on GitHub

  • Copies length bytes starting at the fromIndex to toIndex. Does not move the writer index.

    Note

    Overlapping ranges, for example copyBytes(at: 1, to: 2, length: 5) are allowed.

    Precondition

    The range represented by fromIndex and length must be readable bytes, that is: fromIndex >= readerIndex and fromIndex + length <= writerIndex.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func copyBytes(at fromIndex: Int, to toIndex: Int, length: Int) throws -> Int

    Parameters

    fromIndex

    The index of the first byte to copy.
    toIndex

    The index into to which the first byte will be copied.
    length

    The number of bytes which should be copied.
    Show on GitHub

  • Errors thrown when calling copyBytes.

    See more

    Declaration

    Swift

    public struct CopyBytesError : Error
    extension ByteBuffer.CopyBytesError: Hashable
    extension ByteBuffer.CopyBytesError: CustomDebugStringConvertible
    Show on GitHub

  • Compare two ByteBuffer values. Two ByteBuffer values are considered equal if the readable bytes are equal.

    Declaration

    Swift

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

  • The hash value for the readable bytes.

    Declaration

    Swift

    public func hash(into hasher: inout Hasher)
    Show on GitHub

  • Modify this ByteBuffer if this ByteBuffer is known to uniquely own its storage.

    In some cases it is possible that code is holding a ByteBuffer that has been shared with other parts of the code, and may want to mutate that ByteBuffer. In some cases it may be worth modifying a ByteBuffer only if that ByteBuffer is guaranteed to not perform a copy-on-write operation to do so, for example when a different buffer could be used or more cheaply allocated instead.

    This function will execute the provided block only if it is guaranteed to be able to avoid a copy-on-write operation. If it cannot execute the block the returned value will be nil.

    Declaration

    Swift

    @inlinable
public mutating func modifyIfUniquelyOwned<T>(_ body: (inout ByteBuffer) throws -> T) rethrows -> T?

    Parameters

    body

    The modification operation to execute, with this ByteBuffer passed inout as an argument.

    Return Value

    The return value of body.

    Show on GitHub

  • Read an integer off this ByteBuffer, move the reader index forward by the integer’s byte size and return the result.

    Declaration

    Swift

    @inlinable
public mutating func readInteger<T>(endianness: Endianness = .big, as: T.Type = T.self) -> T? where T : FixedWidthInteger

    Parameters

    endianness

    The endianness of the integer in this ByteBuffer (defaults to big endian).
    as

    the desired FixedWidthInteger type (optional parameter)

    Return Value

    An integer value deserialized from this ByteBuffer or nil if there aren’t enough bytes readable.

    Show on GitHub

  • Get the integer at index from this ByteBuffer. Does not move the reader index. The selected bytes must be readable or else nil will be returned.

    Declaration

    Swift

    @inlinable
public func getInteger<T>(at index: Int, endianness: Endianness = Endianness.big, as: T.Type = T.self) -> T? where T : FixedWidthInteger

    Parameters

    index

    The starting index of the bytes for the integer into the ByteBuffer.
    endianness

    The endianness of the integer in this ByteBuffer (defaults to big endian).
    as

    the desired FixedWidthInteger type (optional parameter)

    Return Value

    An integer value deserialized from this ByteBuffer or nil if the bytes of interest are not readable.

    Show on GitHub

  • Write integer into this ByteBuffer, moving the writer index forward appropriately.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func writeInteger<T: FixedWidthInteger>(_ integer: T,
                                                        endianness: Endianness = .big,
                                                        as: T.Type = T.self) -> Int

    Parameters

    integer

    The integer to serialize.
    endianness

    The endianness to use, defaults to big endian.

    Return Value

    The number of bytes written.

    Show on GitHub

  • Write integer into this ByteBuffer starting at index. This does not alter the writer index.

    Declaration

    Swift

    @discardableResult
@inlinable
public mutating func setInteger<T>(_ integer: T, at index: Int, endianness: Endianness = .big, as: T.Type = T.self) -> Int where T : FixedWidthInteger

    Parameters

    integer

    The integer to serialize.
    index

    The index of the first byte to write.
    endianness

    The endianness to use, defaults to big endian.

    Return Value

    The number of bytes written.

    Show on GitHub

  • A view into the readable bytes of the ByteBuffer.

    Declaration

    Swift

    @inlinable
public var readableBytesView: ByteBufferView { get }
    Show on GitHub

  • Returns a view into some portion of the readable bytes of a ByteBuffer.

    Declaration

    Swift

    @inlinable
public func viewBytes(at index: Int, length: Int) -> ByteBufferView?

    Parameters

    index

    The index the view should start at
    length

    The length of the view (in bytes)

    Return Value

    A view into a portion of a ByteBuffer or nil if the requested bytes were not readable.

    Show on GitHub

  • Create a ByteBuffer from the given ByteBufferViews range.

    Declaration

    Swift

    @inlinable
public init(_ view: ByteBufferView)

    Parameters

    view

    The ByteBufferView which you want to get a ByteBuffer from.
    Show on GitHub