Add get/setMultipleIntegers on ByteBuffer (#3606)

`ByteBuffer` exposes `read`, `write`, and (since the peek work landed)
`peek`
variants of `MultipleIntegers`, but not the absolute-index `get`/`set`
pair that
every other integer accessor on `ByteBuffer` has. This fills that gap,
which is
what #2736 originally asked for.

The thread on #2736 settled on adding `peek*` first so that the common
"look without consuming" use case has a non-mutating, index-free
spelling, and
that is now in place. `get`/`set` remain useful for the niche cases that
genuinely need to address an arbitrary index, so this completes the set
of four
for `MultipleIntegers` to match `getInteger`/`setInteger`.

Both methods are generated from `dev/generate-bytebuffer-multi-int.sh`,
the same
script that produces the read/write/peek variants, so they stay in
lockstep with
the rest of the file across all arities (2 through 15):

- `getMultipleIntegers(at:endianness:as:)` reads at an explicit index
without
moving the reader index and returns `nil` when the requested bytes are
not
  readable, exactly like `getInteger(at:)`.
- `setMultipleIntegers(_:at:endianness:as:)` writes at an explicit index
without
moving the writer index and returns the number of bytes written, exactly
like
  `setInteger(_:at:)`.

The new tests mirror the existing read/write and peek tests: a
round-trip across
both endiannesses, a check that the bytes written by `set` are
byte-for-byte
identical to `writeMultipleIntegers`, coverage of every arity, a check
that
neither method moves the reader or writer index, and the out-of-bounds /
before-reader-index cases that must return `nil`.

Resolves #2736
This commit is contained in:
Aditya Singh authored and GitHub committed 2026-05-29 12:30:55 +00:00
1 parent 4e370dc4d7
commit 9ebe69d269
3 files changed
+1906 -864

No files matched your search

File diff suppressed because it is too large. Load diff
+147
View File
@@ -3955,6 +3955,153 @@ extension ByteBufferTest {
XCTAssertEqual(0, self.buf.readableBytes, "Buffer should be fully consumed after all reads.")
}
func testGetAndSetMultipleIntegers() {
// This test mirrors 'testReadAndWriteMultipleIntegers' but uses set/getMultipleIntegers.
for endianness in [Endianness.little, .big] {
let v1: UInt8 = .random(in: .min ... .max)
let v2: UInt16 = .random(in: .min ... .max)
let v3: UInt32 = .random(in: .min ... .max)
let v4: UInt64 = .random(in: .min ... .max)
let v5: UInt64 = .random(in: .min ... .max)
let v6: UInt32 = .random(in: .min ... .max)
let v7: UInt16 = .random(in: .min ... .max)
let v8: UInt8 = .random(in: .min ... .max)
let v9: UInt16 = .random(in: .min ... .max)
let v10: UInt32 = .random(in: .min ... .max)
// Reserve some readable bytes in front so the integers don't start at the reader index.
self.buf.clear()
self.buf.writeRepeatingByte(0, count: 7)
let index = self.buf.writerIndex
self.buf.writeRepeatingByte(0, count: 256)
let startReaderIndex = self.buf.readerIndex
let startWriterIndex = self.buf.writerIndex
let written = self.buf.setMultipleIntegers(
v1,
v2,
v3,
v4,
v5,
v6,
v7,
v8,
v9,
v10,
at: index,
endianness: endianness,
as: (UInt8, UInt16, UInt32, UInt64, UInt64, UInt32, UInt16, UInt8, UInt16, UInt32).self
)
// set does not move either index.
XCTAssertEqual(startReaderIndex, self.buf.readerIndex, "endianness: \(endianness)")
XCTAssertEqual(startWriterIndex, self.buf.writerIndex, "endianness: \(endianness)")
let result = self.buf.getMultipleIntegers(
at: index,
endianness: endianness,
as: (UInt8, UInt16, UInt32, UInt64, UInt64, UInt32, UInt16, UInt8, UInt16, UInt32).self
)
// get does not move either index.
XCTAssertEqual(startReaderIndex, self.buf.readerIndex, "endianness: \(endianness)")
XCTAssertEqual(startWriterIndex, self.buf.writerIndex, "endianness: \(endianness)")
XCTAssertNotNil(result, "endianness: \(endianness)")
XCTAssertEqual(v1, result?.0, "endianness: \(endianness)")
XCTAssertEqual(v2, result?.1, "endianness: \(endianness)")
XCTAssertEqual(v3, result?.2, "endianness: \(endianness)")
XCTAssertEqual(v4, result?.3, "endianness: \(endianness)")
XCTAssertEqual(v5, result?.4, "endianness: \(endianness)")
XCTAssertEqual(v6, result?.5, "endianness: \(endianness)")
XCTAssertEqual(v7, result?.6, "endianness: \(endianness)")
XCTAssertEqual(v8, result?.7, "endianness: \(endianness)")
XCTAssertEqual(v9, result?.8, "endianness: \(endianness)")
XCTAssertEqual(v10, result?.9, "endianness: \(endianness)")
// The bytes we set must be byte-for-byte identical to those produced by writeMultipleIntegers.
var expected = ByteBufferAllocator().buffer(capacity: written)
expected.writeMultipleIntegers(
v1,
v2,
v3,
v4,
v5,
v6,
v7,
v8,
v9,
v10,
endianness: endianness,
as: (UInt8, UInt16, UInt32, UInt64, UInt64, UInt32, UInt16, UInt8, UInt16, UInt32).self
)
XCTAssertEqual(
self.buf.getSlice(at: index, length: written).map { Array($0.readableBytesView) },
Array(expected.readableBytesView),
"endianness: \(endianness)"
)
}
}
func testGetMultipleIntegersReturnsNilWhenOutOfBounds() {
self.buf.clear()
self.buf.writeRepeatingByte(0, count: 8)
// Move the reader index forward so we can also test indices that precede it.
self.buf.moveReaderIndex(forwardBy: 4)
let index = self.buf.readerIndex
// Asking for 4 bytes when only 4 are readable from `index` must return nil if we ask for more.
XCTAssertNil(self.buf.getMultipleIntegers(at: index, as: (UInt32, UInt8).self))
// Asking for an index before the reader index must return nil, even though those bytes exist.
XCTAssertNil(self.buf.getMultipleIntegers(at: index - 1, as: (UInt8, UInt8).self))
// A request that just fits must succeed.
XCTAssertNotNil(self.buf.getMultipleIntegers(at: index, as: (UInt16, UInt16).self))
}
func testAllByteBufferMultiByteVersionsGetSet() {
// This test mirrors 'testAllByteBufferMultiByteVersions' but using set/getMultipleIntegers.
let i = UInt8(86)
var index = self.buf.writerIndex
index += self.buf.setMultipleIntegers(i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, i, i, i, i, i, at: index)
index += self.buf.setMultipleIntegers(i, i, i, i, i, i, i, i, i, i, i, i, i, i, i, at: index)
// setMultipleIntegers does not move the writer index (just like setInteger), so expose the
// bytes we just wrote before reading them back.
XCTAssertEqual(0, self.buf.writerIndex)
self.buf.moveWriterIndex(to: index)
XCTAssertEqual(Array(repeating: UInt8(86), count: 119), Array(self.buf.readableBytesView))
var readIndex = self.buf.readerIndex
var values2 = self.buf.getMultipleIntegers(at: readIndex, as: (UInt8, UInt8).self)!
readIndex += MemoryLayout<UInt8>.size * 2
var values3 = self.buf.getMultipleIntegers(at: readIndex, as: (UInt8, UInt8, UInt8).self)!
readIndex += MemoryLayout<UInt8>.size * 3
var values4 = self.buf.getMultipleIntegers(at: readIndex, as: (UInt8, UInt8, UInt8, UInt8).self)!
readIndex += MemoryLayout<UInt8>.size * 4
var values5 = self.buf.getMultipleIntegers(at: readIndex, as: (UInt8, UInt8, UInt8, UInt8, UInt8).self)!
readIndex += MemoryLayout<UInt8>.size * 5
XCTAssertEqual([i, i], withUnsafeBytes(of: &values2, { Array($0) }))
XCTAssertEqual([i, i, i], withUnsafeBytes(of: &values3, { Array($0) }))
XCTAssertEqual([i, i, i, i], withUnsafeBytes(of: &values4, { Array($0) }))
XCTAssertEqual([i, i, i, i, i], withUnsafeBytes(of: &values5, { Array($0) }))
// get must not have consumed anything.
XCTAssertEqual(self.buf.readerIndex, 0)
XCTAssertEqual(Array(repeating: UInt8(86), count: 119), Array(self.buf.readableBytesView))
}
func testByteBufferEncode() throws {
let encoder = JSONEncoder()
let hello = "Hello, world!"
+100 -47
View File
@@ -41,41 +41,15 @@ function gen() {
echo -n ", T$n"
done
echo ")? {"
echo " guard let result = self.getMultipleIntegers(at: self.readerIndex, endianness: endianness, as: \`as\`) else {"
echo " return nil"
echo " }"
echo " var bytesRequired: Int = MemoryLayout<T1>.size"
for n in $(seq 2 "$how_many"); do
echo " bytesRequired &+= MemoryLayout<T$n>.size"
done
echo
echo " guard self.readableBytes >= bytesRequired else {"
echo " return nil"
echo " }"
echo
for n in $(seq 1 "$how_many"); do
echo " var v$n: T$n = 0"
done
echo " var offset = 0"
echo " self.readWithUnsafeReadableBytes { ptr -> Int in"
echo " assert(ptr.count >= bytesRequired)"
echo " let basePtr = ptr.baseAddress! // safe, ptr is non-empty"
for n in $(seq 1 "$how_many"); do
echo " withUnsafeMutableBytes(of: &v$n) { destPtr in"
echo " destPtr.baseAddress!.copyMemory(from: basePtr + offset, byteCount: MemoryLayout<T$n>.size)"
echo " }"
echo " offset = offset &+ MemoryLayout<T$n>.size"
done
echo " assert(offset == bytesRequired)"
echo " return offset"
echo " }"
echo " switch endianness {"
for endianness in big little; do
echo " case .$endianness:"
echo -n " return (T1(${endianness}Endian: v1)"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n(${endianness}Endian: v$n)"
done
echo ")"
done
echo " }"
echo " self._moveReaderIndex(forwardBy: bytesRequired)"
echo " return result"
echo " }"
echo
@@ -100,8 +74,65 @@ function gen() {
echo -n ", T$n"
done
echo ")? {"
echo " var copy = self"
echo " return copy.readMultipleIntegers(endianness: endianness, as: \`as\`)"
echo " self.getMultipleIntegers(at: self.readerIndex, endianness: endianness, as: \`as\`)"
echo " }"
echo
# GET
echo " @inlinable"
echo " @_alwaysEmitIntoClient"
echo -n " public func getMultipleIntegers<T1: FixedWidthInteger"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n: FixedWidthInteger"
done
echo -n ">("
echo -n "at index: Int, endianness: Endianness = .big, as: (T1"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n"
done
echo -n ").Type = (T1"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n"
done
echo -n ").self) -> (T1"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n"
done
echo ")? {"
echo " var bytesRequired: Int = MemoryLayout<T1>.size"
for n in $(seq 2 "$how_many"); do
echo " bytesRequired &+= MemoryLayout<T$n>.size"
done
echo
echo " guard let range = self.rangeWithinReadableBytes(index: index, length: bytesRequired) else {"
echo " return nil"
echo " }"
echo
for n in $(seq 1 "$how_many"); do
echo " var v$n: T$n = 0"
done
echo " var offset = range.lowerBound"
echo " self.withUnsafeReadableBytes { ptr in"
echo " assert(ptr.count >= range.lowerBound + bytesRequired)"
echo " let basePtr = ptr.baseAddress! // safe, ptr is non-empty"
for n in $(seq 1 "$how_many"); do
echo " withUnsafeMutableBytes(of: &v$n) { destPtr in"
echo " destPtr.baseAddress!.copyMemory(from: basePtr + offset, byteCount: MemoryLayout<T$n>.size)"
echo " }"
echo " offset = offset &+ MemoryLayout<T$n>.size"
done
echo " assert(offset == range.upperBound)"
echo " }"
echo " switch endianness {"
for endianness in big little; do
echo " case .$endianness:"
echo -n " return (T1(${endianness}Endian: v1)"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n(${endianness}Endian: v$n)"
done
echo ")"
done
echo " }"
echo " }"
echo
@@ -126,6 +157,37 @@ function gen() {
echo -n ", T$n"
done
echo ").self) -> Int {"
echo -n " let bytesWritten = self.setMultipleIntegers(value1"
for n in $(seq 2 "$how_many"); do
echo -n ", value$n"
done
echo ", at: self.writerIndex, endianness: endianness, as: \`as\`)"
echo " self._moveWriterIndex(forwardBy: bytesWritten)"
echo " return bytesWritten"
echo " }"
echo
# SET
echo " @inlinable"
echo " @_alwaysEmitIntoClient"
echo " @discardableResult"
echo -n " public mutating func setMultipleIntegers<T1: FixedWidthInteger"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n: FixedWidthInteger"
done
echo -n ">(_ value1: T1"
for n in $(seq 2 "$how_many"); do
echo -n ", _ value$n: T$n"
done
echo -n ", at index: Int, endianness: Endianness = .big, as: (T1"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n"
done
echo -n ").Type = (T1"
for n in $(seq 2 "$how_many"); do
echo -n ", T$n"
done
echo ").self) -> Int {"
for n in $(seq 1 "$how_many"); do
echo " var v$n: T$n"
done
@@ -138,22 +200,13 @@ function gen() {
done
echo " }"
echo
echo " var spaceNeeded: Int = MemoryLayout<T1>.size"
for n in $(seq 2 "$how_many"); do
echo " spaceNeeded &+= MemoryLayout<T$n>.size"
done
echo
echo " return self.writeWithUnsafeMutableBytes(minimumWritableBytes: spaceNeeded) { ptr -> Int in"
echo " assert(ptr.count >= spaceNeeded)"
echo " var offset = 0"
echo " let basePtr = ptr.baseAddress! // safe: pointer is non zero length"
echo " var offset = index"
echo " var bytesWritten = 0"
for n in $(seq 1 "$how_many"); do
echo " (basePtr + offset).copyMemory(from: &v$n, byteCount: MemoryLayout<T$n>.size)"
echo " offset = offset &+ MemoryLayout<T$n>.size"
echo " bytesWritten &+= Swift.withUnsafeBytes(of: &v$n) { self.setBytes(\$0, at: offset) }"
echo " offset = offset &+ MemoryLayout<T$n>.size"
done
echo " assert(offset == spaceNeeded)"
echo " return offset"
echo " }"
echo " return bytesWritten"
echo " }"
echo
}