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.
\n\nTwo things to internalize first: (1) a
\nSliceis 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.
| \n | Slice.Nil | \nSlice.Empty | \n
|---|---|---|
| backing array | \nnone (null-like) | \na zero-length array | \n
IsNull | \ntrue | \nfalse | \n
IsEmpty | \nfalse | \ntrue | \n
IsNullOrEmpty | \ntrue | \ntrue | \n
IsPresent | \nfalse | \ntrue | \n
GetBytes() | \nreturns null | \nreturns an empty array | \n
ToStringUtf8() | \nreturns null | \nreturns \"\" | \n
== | \nNil != Empty | \ndistinct | \n
CompareTo | \nNil and Empty compare equal (both sort first) | \n\n |
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);\nif (v.IsNull) { /* key does not exist */ }\nConstructing 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 = ...;\nvar view = buf.AsSlice(); // shares buf — buf[i] = x is visible through view\nbyte[] mine = view.ToArray(); // defensive copy\nbuf[0] = 0xFF; // changes `view`, not `mine`\n// from arrays / spans\nbyte[] b = ...;\nb.AsSlice(); b.AsSlice(offset, count);\nnew ArraySegment<byte>(b, o, n).AsSlice();\nSlice.FromBytes(\"abc\"u8); // copies a ReadOnlySpan<byte>\n\n// from text\nSlice.FromStringUtf8(\"héllo\"); Slice.FromString(\"héllo\"); // UTF-8\nSlice.FromStringAscii(\"ABC\"); // ASCII only — lossy/throws on chars > 0x7F\n\n// well-known\nSlice.Empty; Slice.Nil; Slice.Zero(16); // 16 zero bytes\n\n// guids / uuids / hex\nSlice.FromGuid(g); Slice.FromUuid128(u); Slice.FromHexString(\"00ff1234\");\nThis is a classic source of bugs. They are not interchangeable:
\n| Factory | \nEncoding | \nSize (int32) | \nRead back with | \n
|---|---|---|---|
Slice.FromInt32(v) | \nminimal little-endian (leading zero bytes dropped) | \n1–4 bytes | \nslice.ToInt32() | \n
Slice.FromFixed32(v) | \nfixed little-endian | \nalways 4 bytes | \nslice.ToInt32() | \n
Slice.FromVarint32(v) | \n7-bit LEB128 varint | \n1–5 bytes | \n(via SliceReader.ReadVarInt32) | \n
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).
\n\n⚠️ Naming differs between
\nSliceand 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.)
slice.ToInt64(); slice.ToInt32BE(); slice.ToGuid(); slice.ToUuid128();\nslice.ToStringUtf8(); // Nil -> null, Empty -> \"\"\nslice.ToArray(); // defensive copy to byte[]\nslice.ToHexString();\n\n// zero-copy access to the bytes\nReadOnlySpan<byte> span = slice.Span;\nReadOnlyMemory<byte> mem = slice.Memory;\n\n// slicing (negative indices count from the end)\nslice.Substring(7, 6); slice[2..5]; slice[^1..];\nSlice 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, StartsWith, EndsWith, IndexOf. For dictionaries/sorted sets, use Slice.Comparer.Default (an IComparer<Slice> + IEqualityComparer<Slice>).
a.CompareTo(b) < 0; // a sorts before b\nkey.StartsWith(prefix); // prefix match\nvar set = new SortedSet<Slice>(Slice.Comparer.Default);\nSliceWriter is a mutable, growable builder (struct, IBufferWriter<byte>, IDisposable). Start from default(SliceWriter) (heap-backed, grows as needed) or new SliceWriter(pool) (rents from an ArrayPool<byte>):
var w = new SliceWriter();\nw.WriteInt32(42); // fixed 4 bytes LE (self-delimiting)\nw.WriteVarInt32(1000); // LEB128 (self-delimiting)\nw.WriteVarString(\"hello\"); // length-prefixed UTF-8\nw.WriteStringUtf8(\"raw\"); // raw UTF-8, NO length prefix\nw.WriteBytes(payload); // append bytes\nSlice result = w.ToSlice(); // the written region (a view into the writer's buffer)\nWriteInt32/WriteInt64/…, WriteVarInt*, WriteVarString) for anything you'll parse back sequentially. A raw WriteStringUtf8/WriteBytes has no length, so the reader must already know the length.Position, Reset(), Rewind(), Skip(n), Allocate(n)/AllocateSpan(n) (reserve space to fill in place).ArrayPool<byte>, you must either Dispose() the writer or hand the buffer off with ToSliceOwner() — otherwise the rented array is never returned. ToSlice() returns a view into the writer's buffer; if the writer (or its pooled buffer) is disposed/reused, that view becomes invalid — ToArray() or ToSliceOwner() it to keep it.SliceReader is a forward cursor over a Slice. Pair each read with the matching write:
var r = result.ToSliceReader();\nint n = r.ReadInt32(); // <-> WriteInt32 (fixed 4 bytes)\nuint k = r.ReadVarInt32(); // <-> WriteVarInt32\nstring s = r.ReadVarString(); // <-> WriteVarString\n// raw / fixed-length string written without a prefix: read the known number of bytes\nstring raw = r.ReadBytes(3).ToStringUtf8();\nSlice rest = r.ReadToEnd();\nRemaining, HasMore, Head (bytes already read), Tail (bytes not yet read), and non-advancing PeekByte()/PeekBytes(n) round out the API. There is no ReadStringUtf8(n) — use ReadBytes(n).ToStringUtf8().
SliceOwner is a rented Slice that returns its buffer to an ArrayPool<byte> on Dispose — the allocation-free analogue of IMemoryOwner<byte>. The contract: you MUST Dispose it, and MUST NOT use its data afterward.
using (var owner = Slice.FromBytes(payload, ArrayPool<byte>.Shared))\n{\n Slice data = owner.Data; // valid only inside the using\n Use(data.Span);\n} // buffer returned to the pool here\nowner.IsValid, owner.Count, owner.Span, owner.Pool; SliceOwner.Wrap/Create/Copy and writer.ToSliceOwner() produce them. Don't let an owner's Data escape the using.
ISpanEncodableSlice interops freely with the modern primitives: slice.Span (ReadOnlySpan<byte>), slice.Memory (ReadOnlyMemory<byte>), byte[].AsSlice(). Many hot types (keys, values, the writers) implement ISpanEncodable so they can be rendered into a caller's buffer with no intermediate Slice allocation — TryGetSpan(out span) / TryGetSizeHint(out size) / TryEncode(dest, out written). That interface is how subspace.Key(...)/FdbValue.* write themselves into pooled buffers at the last moment.
For working directly over Span<byte> (a caller-owned, fixed buffer) instead of Slice, use SpanReader/SpanWriter — see references/span-readers-writers.md.
// build\nvar w = new SliceWriter();\nw.WriteInt32(order.Id);\nw.WriteVarString(order.Customer);\nw.WriteVarInt64(order.Total);\nSlice packed = w.ToSlice();\n\n// parse\nvar r = packed.ToSliceReader();\nint id = r.ReadInt32();\nstring cust = r.ReadVarString();\nlong total = (long) r.ReadVarInt64();\nIsNull/IsNullOrEmpty (not == Slice.Empty) to test for a missing value?Slice as a view — copying with ToArray()/ToSliceOwner() before mutating shared arrays or outliving a pooled buffer?Fixed*/*BE for sortable keys; VarInt*/Fixed* for self-delimiting stream fields; FromInt32 only for standalone whole-slice values)?SliceWriter writes and SliceReader reads pair up (WriteInt32↔ReadInt32, VarInt↔VarInt, VarString↔VarString)?ArrayPool (SliceWriter(pool) / SliceOwner), did I Dispose/ToSliceOwner() so the buffer returns to the pool — and not use the data after disposal?