snowbank-slices-and-buffers
How to correctly use the Slice type and its companions (SliceReader, SliceWriter, SliceOwner) for binary data in the FoundationDB .NET client / SnowBank.Core codebase. Slice is a readonly struct (namespace System) — the logical equivalent of a ReadOnlyMemory of bytes with many helpers. Use whenever code constructs or reads a Slice, converts between bytes and other types (Slice.FromBytes/FromStringUtf8/FromInt32/FromFixed64/ToInt64/ToStringUtf8/AsSlice/ToArray), builds or parses a binary buffer (SliceWriter/SliceReader), rents pooled buffers (SliceOwner/ArrayPool), or worries about Nil-vs-Empty, endianness, or which integer encoding to use. For the Span-of-byte (Span-first) equivalents and the low-level buffer/pool machinery, see the bundled reference files.
SnowBankSDK · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add SnowBankSDK/foundationdb-dotnet-client --skill snowbank-slices-and-buffers技能说明
name: snowbank-slices-and-buffers description: How to correctly use the Slice type and its companions (SliceReader, SliceWriter, SliceOwner) for binary data in the FoundationDB .NET client / SnowBank.Core codebase. Slice is a readonly struct (namespace System) — the logical equivalent of a ReadOnlyMemory of bytes with many helpers. Use whenever code constructs or reads a Slice, converts between bytes and other types (Slice.FromBytes/FromStringUtf8/FromInt32/FromFixed64/ToInt64/ToStringUtf8/AsSlice/ToArray), builds or parses a binary buffer (SliceWriter/SliceReader), rents pooled buffers (SliceOwner/ArrayPool), or worries about Nil-vs-Empty, endianness, or which integer encoding to use. For the Span-of-byte (Span-first) equivalents and the low-level buffer/pool machinery, see the bundled reference files.
Slice, SliceReader, SliceWriter & friends
Slice is the workhorse for binary data in this codebase. It is a readonly struct (in namespace System) that wraps a segment of a byte[] — its three fields are Array (the backing array, possibly null), Offset, and Count. It predates Span<T> and is the logical equivalent of ReadOnlyMemory<byte>, but with a large library of helpers for turning bytes into and out of real-world types. Keys and values in the FoundationDB binding are Slices.
Two things to internalize first: (1) a
Sliceis a view, not a copy — it shares the backing array. (2)Slice.Nil(no array) andSlice.Empty(zero-length array) are different and the distinction is load-bearing. Both are covered below.
For the Span-first equivalents (SpanReader/SpanWriter, ISpanEncodable) read references/span-readers-writers.md; for pooled buffer-building (ISliceBufferWriter, SlicePool, ValueBuffer<T>, allocators) read references/buffers-and-pooling.md.
1. Nil vs Empty — the #1 gotcha
Slice.Nil | Slice.Empty | |
|---|---|---|
| backing array | none (null-like) | a zero-length array |
IsNull | true | false |
IsEmpty | false | true |
IsNullOrEmpty | true | true |
IsPresent | false | true |
GetBytes() | returns null | returns an empty array |
ToStringUtf8() | returns null | returns "" |
== | Nil != Empty | distinct |
CompareTo | Nil and Empty compare equal (both sort first) |
tr.GetAsync(key) returns Slice.Nil for a missing key, so the canonical "does it exist?" check is value.IsNull (or IsNullOrEmpty if an empty value also counts as absent). Use Nil to mean absent and Empty to mean present but zero-length.
var v = await tr.GetAsync(key);
if (v.IsNull) { /* key does not exist */ }
2. Slice is a view — copy when you must own it
Constructing a Slice from a byte[] does not copy; the Slice references the array, so mutations to the array are visible through the slice (and its .Span). When you need an independent owner, copy:
byte[] buf = ...;
var view = buf.AsSlice(); // shares buf — buf[i] = x is visible through view
byte[] mine = view.ToArray(); // defensive copy
buf[0] = 0xFF; // changes `view`, not `mine`
3. Constructing a Slice
// from arrays / spans
byte[] b = ...;
b.AsSlice(); b.AsSlice(offset, count);
new ArraySegment<byte>(b, o, n).AsSlice();
Slice.FromBytes("abc"u8); // copies a ReadOnlySpan<byte>
// from text
Slice.FromStringUtf8("héllo"); Slice.FromString("héllo"); // UTF-8
Slice.FromStringAscii("ABC"); // ASCII only — lossy/throws on chars > 0x7F
// well-known
Slice.Empty; Slice.Nil; Slice.Zero(16); // 16 zero bytes
// guids / uuids / hex
Slice.FromGuid(g); Slice.FromUuid128(u); Slice.FromHexString("00ff1234");
Three integer encodings — pick deliberately
This is a classic source of bugs. They are not interchangeable:
| Factory | Encoding | Size (int32) | Read back with |
|---|---|---|---|
Slice.FromInt32(v) | minimal little-endian (leading zero bytes dropped) | 1–4 bytes | slice.ToInt32() |
Slice.FromFixed32(v) | fixed little-endian | always 4 bytes | slice.ToInt32() |
Slice.FromVarint32(v) | 7-bit LEB128 varint | 1–5 bytes | (via SliceReader.ReadVarInt32) |
Every variant has a big-endian twin (FromInt32BE, FromFixed32BE, …) and 16/24/64/128-bit widths, plus floats (FromSingle/FromDouble) and FromDecimal. Big-endian fixed encodings are what you want when a number must sort correctly as a key. The minimal FromInt32 is for standalone values you read whole with ToInt32() — it is not self-delimiting, so don't use it mid-stream (in a SliceWriter, use the fixed-width WriteInt32/WriteInt64 or WriteVarInt* there; see §6).
⚠️ Naming differs between
Sliceand the writer/reader. OnSlice(standalone),FromFixed32= 4 bytes andFromInt32= minimal. OnSliceWriter/SliceReader(streams), the fixed-width method is plainWriteInt32/ReadInt32(4 bytes LE;*BEfor big-endian), and the varint isWriteVarInt32/ReadVarInt32. (WriteFixed32/ReadFixed32exist but are[Obsolete]— useWriteInt32/ReadInt32.)
4. Reading values back
slice.ToInt64(); slice.ToInt32BE(); slice.ToGuid(); slice.ToUuid128();
slice.ToStringUtf8(); // Nil -> null, Empty -> ""
slice.ToArray(); // defensive copy to byte[]
slice.ToHexString();
// zero-copy access to the bytes
ReadOnlySpan<byte> span = slice.Span;
ReadOnlyMemory<byte> mem = slice.Memory;
// slicing (negative indices count from the end)
slice.Substring(7, 6); slice[2..5]; slice[^1..];
5. Comparison & equality
Slice compares lexicographically by raw bytes (the same order FoundationDB sorts keys), is offset/array-independent (equal content compares equal regardless of backing array or offset), and supports ==, <, >, CompareTo, `Star