KeyRange

Namespace: FoundationDB.Client · struct

Implements: IEquatable<KeyRange>, IComparable<KeyRange>, IEquatable<(Slice, Slice)>, IComparable<(Slice, Slice)>, IFormattable

Represents a pair of keys defining the range 'Begin <= key > End'

Constructors

KeyRange

KeyRange(Slice begin, Slice end)

Creates a new range of keys

• begin — Start of range (usually included)
• end — End of range (usually excluded)

Properties

All

static KeyRange All { get; }

Returns a range that contains all the keys in the database

Methods

CompareTo

int CompareTo(KeyRange other)

int CompareTo((Slice, Slice) other)

Contains

bool Contains(Slice key)

Returns true, if the key is contained in the range

Create

static KeyRange Create(Slice a, Slice b)

Deconstruct

void Deconstruct(out Slice begin, out Slice end)

Deconstructs this key range

• begin — Receives the Begin key
• end — Receives the End key

Disjoint

bool Disjoint(in KeyRange other)

Checks whether the current and the specified range are disjoint (i.e: there exists at least one key between both ranges)

Note that ranges [0, 1) and [1, 2) are not disjoint because, even though they do not intersect, they are both contiguous.

Equals

bool Equals(object obj)

bool Equals(KeyRange other)

bool Equals((Slice, Slice) other)

FromKey

static KeyRange FromKey(Slice key)

Creates a range that will only return key itself: key <= k < key.'\0'

• key — Key that will be returned by the range

Returns: Range that only return the specified key.

KeyRange.FromKey(Slice.FromString("hello")) => (hello, hello\0)

GetHashCode

int GetHashCode()

Head

static KeyRange Head(Slice prefix, Slice cursor, bool included = false)

Returns a range that will select all the keys that start with the specified prefix, up until a specific cursor

• prefix — Common prefix of the keys that must be read (usually the containing subspace)
• cursor — Value of the cursor, that is appended to prefix. The caller wants to read or clear any keys that are before this point
• included — Specifies whether the cursor is included (true) or excluded (false, default)

Returns: Range that will read any keys with the specified prefix, up to the specified cursor (included or excluded)

This is a common usage pattern when clearing the consumed portion of a stream or log or records that are indexed by a VersionStamp (or any other monotonic counter).

For example in a CLEAR_RANGE operation, cursor may represent the oldest entry to keep, in which case included should be false; or it could represent the last entry to delete, in which case included should be true.

KeyRange.Head(Slice.FromString("ABC"), Slice.FromString("def")) => (`ABC\0`, `ABCdef`)

KeyRange.Head(Slice.FromString("ABC"), Slice.FromString("def"), included: true) => (`ABC\0`, `ABCdeg`)

Intersects

bool Intersects(in KeyRange other)

Checks whether the current and the specified range are intersecting (i.e: there exists at least one key that belongs to both ranges)

• other — Range that is being checked for interaction

Returns: True if the other range intersects the current range.

Note that ranges [0, 1) and [1, 2) do not intersect, since the end is exclusive by default

Merge

KeyRange Merge(in KeyRange other)

Combine another range with the current range, to produce a range that includes both (and all keys in between it the ranges are disjoint)

• other — Range to merge with the current range

Returns: New range where the Begin key is the smallest bound and the End key is the largest bound of both ranges.

If both range are disjoint, then the resulting range will also contain the keys in between.

PrefixedBy

static KeyRange PrefixedBy(Slice prefix)

Creates a range that selects all keys starting with prefix, but not the prefix itself: prefix.'\0' <= k < increment(prefix)

• prefix — Key prefix (that will be excluded from the range)

Returns: Range including all keys with the specified prefix.

KeyRange.PrefixedBy(Slice.FromString("hello")) => (hello\x00, hellp)

StartsWith

static KeyRange StartsWith(Slice prefix)

Creates a range that will return all keys starting with prefix: prefix <= k < increment(prefix)

• prefix — Key prefix (that will be included in the range)

Returns: Range including all keys that start with the specified prefix.

KeyRange.StartsWith(Slice.FromString("hello")) => (hello, hellp)

Tail

static KeyRange Tail(Slice prefix, Slice cursor, bool included = false)

Returns a range that will only return the keys that start with the specified prefix, and that are after a specific cursor

• prefix — Common prefix of the keys that must be read (usually the containing subspace)
• cursor — Value of the cursor, that is appended to prefix. The caller has already read any keys that are before this point, and wants to resume reading past this point
• included — Specifies whether the cursor is included (true) or excluded (false, default)

Returns: Range that will read any keys with the specified prefix, starting from the specified cursor (or its successor)

This is a common usage pattern when consuming a stream of logs or records that are indexed by a VersionStamp or a counter.

Depending on the algorithm used, cursor may represent the last read entry, in which case included should be false; or it could represent the next expected entry, in which case included should be true.

KeyRange.Tail(Slice.FromString("ABC"), Slice.FromString("def")) => (`ABCdef\0`, `ABD`)

KeyRange.Tail(Slice.FromString("ABC"), Slice.FromString("def"), included: true) => (`ABCdef`, `ABD`)

Test

int Test(Slice key, bool endIncluded = false)

Test if key is contained inside the range

• key — Key that will be compared with the range's bounds
• endIncluded — If true, the End bound is inclusive, otherwise it is exclusive

Returns: -1 if key is less than the lower bound of the range (key < Begin), +1 if the key is greater or equal to the higher bound of the range (key >= End) or 0 if it is inside the range (Begin <= key < End)

ToRange

static KeyRange ToRange(Slice prefix)

Creates a range that selects all keys starting with prefix generated using the Tuple Encoding, excluding the prefix itself: prefix.`\x00` <= k < prefix.`\xff`

• prefix — Key prefix (that will be excluded from the range)

Returns: Range including all keys with the specified prefix, and that are valid encodings of tuples.

KeyRange.PrefixedBy(TuPack.EncodeKey("hello", 42)) => (\x02hello\x00\x15\x2A\x00, \x02hello\x00\x15\x2A\xFF)

ToString

string ToString()

Returns a printable version of the range

string ToString(string format, IFormatProvider formatProvider = null)

Returns a printable version of the range

TryFormat

bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = null, IFormatProvider provider = null)

Returns a printable version of the range

Fields

Begin

readonly Slice Begin

Start of the range (usually included)

Empty

static readonly KeyRange Empty

Returns an empty pair of keys

End

readonly Slice End

End of the range (usually excluded)