Interface KeyRecordDictionary.IKeyAccess

Namespace

BelNytheraSeiche.TrieDictionary

Assembly

BelNytheraSeiche.TrieDictionary.dll

Defines the primary public contract for all key-based operations within the dictionary.

public interface KeyRecordDictionary.IKeyAccess

Methods

Add(ReadOnlySpan<byte>)

Adds a key to the dictionary. If the key already exists, its existing identifier is returned.

int Add(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The key to add.

Returns

int

The identifier for the added or existing key.

Exceptions

ArgumentException

key is empty.

AsStringSpecialized(Encoding?)

Returns a string-specialized wrapper for this key access interface.

KeyRecordDictionary.StringSpecialized AsStringSpecialized(Encoding? encoding = null)

Parameters

encoding Encoding

The encoding to use for string operations. Defaults to UTF-8.

Returns

KeyRecordDictionary.StringSpecialized

A new KeyRecordDictionary.StringSpecialized instance.

Contains(ReadOnlySpan<byte>)

Determines whether the dictionary contains the specified key.

bool Contains(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The key to locate.

Returns

bool

true if the key is found; otherwise, false.

EnumerateAll(bool)

Enumerates all keys in the dictionary.

IEnumerable<(int, byte[])> EnumerateAll(bool reverse = false)

Parameters

reverse bool

If true, returns keys in reverse lexicographical order.

Returns

IEnumerable<(int, byte[])>

An enumerable collection of all (identifier, key) tuples.

FindFirst(out int, out byte[])

Finds the first key in the dictionary according to the current sort order.

bool FindFirst(out int identifier, out byte[] key)

Parameters

identifier int

When this method returns, the identifier of the first key.

key byte[]

When this method returns, the first key.

Returns

bool

true if the dictionary is not empty; otherwise, false.

FindLast(out int, out byte[])

Finds the last key in the dictionary according to the current sort order.

bool FindLast(out int identifier, out byte[] key)

Parameters

identifier int

When this method returns, the identifier of the last key.

key byte[]

When this method returns, the last key.

Returns

bool

true if the dictionary is not empty; otherwise, false.

FindNext(int, out int, out byte[])

Finds the next key in sequence after the specified identifier.

bool FindNext(int currentIdentifier, out int foundIdentifier, out byte[] foundKey)

Parameters

currentIdentifier int

The identifier to start the search from.

foundIdentifier int

When this method returns, the identifier of the next key.

foundKey byte[]

When this method returns, the next key.

Returns

bool

true if a next key was found; otherwise, false.

FindNext(ReadOnlySpan<byte>, out int, out byte[])

Finds the next key in sequence after the specified key.

bool FindNext(ReadOnlySpan<byte> currentKey, out int foundIdentifier, out byte[] foundKey)

Parameters

currentKey ReadOnlySpan<byte>

The key to start the search from.

foundIdentifier int

When this method returns, the identifier of the next key.

foundKey byte[]

When this method returns, the next key.

Returns

bool

true if a next key was found; otherwise, false.

FindPrevious(int, out int, out byte[])

Finds the previous key in sequence before the specified identifier.

bool FindPrevious(int currentIdentifier, out int foundIdentifier, out byte[] foundKey)

Parameters

currentIdentifier int

The identifier to start the search from.

foundIdentifier int

When this method returns, the identifier of the previous key.

foundKey byte[]

When this method returns, the previous key.

Returns

bool

true if a previous key was found; otherwise, false.

FindPrevious(ReadOnlySpan<byte>, out int, out byte[])

Finds the previous key in sequence before the specified key.

bool FindPrevious(ReadOnlySpan<byte> currentKey, out int foundIdentifier, out byte[] foundKey)

Parameters

currentKey ReadOnlySpan<byte>

The key to start the search from.

foundIdentifier int

When this method returns, the identifier of the previous key.

foundKey byte[]

When this method returns, the previous key.

Returns

bool

true if a previous key was found; otherwise, false.

GetKey(int)

Gets the key associated with the specified identifier.

byte[] GetKey(int identifier)

Parameters

identifier int

The identifier of the key to get.

Returns

byte[]

The key as a byte array.

Exceptions

KeyNotFoundException

The specified identifier does not exist.

GetRecordAccess(int, bool)

Gets an accessor for the list of records associated with a given key identifier.

KeyRecordDictionary.IRecordAccess GetRecordAccess(int identifier, bool isTransient = false)

Parameters

identifier int

The identifier of the key whose records are to be accessed.

isTransient bool

If true, accesses the transient record store; otherwise, accesses the persistent record store.

Returns

KeyRecordDictionary.IRecordAccess

An KeyRecordDictionary.IRecordAccess handle for the specified record list.

Remove(int)

Removes a key from the dictionary using its identifier.

bool Remove(int identifier)

Parameters

identifier int

The identifier of the key to remove.

Returns

bool

true if the key was found and removed; otherwise, false.

Remove(ReadOnlySpan<byte>)

Removes a key from the dictionary.

bool Remove(ReadOnlySpan<byte> key)

Parameters

key ReadOnlySpan<byte>

The key to remove.

Returns

bool

true if the key was found and removed; otherwise, false.

SearchByPrefix(ReadOnlySpan<byte>, bool)

Finds all keys that start with the given prefix.

IEnumerable<(int, byte[])> SearchByPrefix(ReadOnlySpan<byte> sequence, bool reverse = false)

Parameters

sequence ReadOnlySpan<byte>

The prefix to search for.

reverse bool

If true, returns results in reverse lexicographical order.

Returns

IEnumerable<(int, byte[])>

An enumerable collection of (identifier, key) tuples for all keys starting with the prefix.

Examples

If the dictionary contains the keys "a", "app", and "apple", and the input sequence is "ap", this method will return two keys: "app" and "apple".

SearchCommonPrefix(ReadOnlySpan<byte>)

Finds all keys in the dictionary that are prefixes of the given sequence.

IEnumerable<(int, byte[])> SearchCommonPrefix(ReadOnlySpan<byte> sequence)

Parameters

sequence ReadOnlySpan<byte>

The sequence to search within.

Returns

IEnumerable<(int, byte[])>

An enumerable collection of (identifier, key) tuples for all matching prefixes.

Examples

If the dictionary contains the keys "a", "app", and "apple", and the input sequence is "applepie", this method will return all three keys: "a", "app", and "apple".

SearchExactly(ReadOnlySpan<byte>)

Searches for an exact match of the given sequence and returns its identifier.

int SearchExactly(ReadOnlySpan<byte> sequence)

Parameters

sequence ReadOnlySpan<byte>

The key to search for.

Returns

int

The identifier for the key if found; otherwise, a value indicating not found (typically 0 or -1).

Examples

If the dictionary contains the keys "a", "app", and "apple", and the input sequence is "apple", this method will return a key: "apple".

SearchLongestPrefix(ReadOnlySpan<byte>)

Finds the longest key in the dictionary that is a prefix of the given sequence.

(int, byte[]) SearchLongestPrefix(ReadOnlySpan<byte> sequence)

Parameters

sequence ReadOnlySpan<byte>

The sequence to search within.

Returns

(int, byte[])

A tuple containing the identifier and key of the longest matching prefix, or a default value if no match is found.

Examples

If the dictionary contains the keys "a", "app", and "apple", and the input sequence is "applepie", this method will return a key: "apple".

SearchWildcard(ReadOnlySpan<byte>, ReadOnlySpan<char>, bool)

Performs a wildcard search for keys matching a pattern.

IEnumerable<(int, byte[])> SearchWildcard(ReadOnlySpan<byte> sequence, ReadOnlySpan<char> cards, bool reverse = false)

Parameters

sequence ReadOnlySpan<byte>

The byte sequence of the pattern.

cards ReadOnlySpan<char>

A sequence of characters ('?' for single, '*' for multiple wildcards) corresponding to the pattern.

reverse bool

If true, returns results in reverse order.

Returns

IEnumerable<(int, byte[])>

An enumerable collection of matching (identifier, key) tuples.

Examples

If the dictionary contains the keys "a", "app", and "apple", and the input sequence is "a?p*", this method will return two keys: "app" and "apple". The search pattern is provided as two separate arguments (sequence and cards) to unambiguously support searching for any possible byte value (0-255). The sequence span contains the literal byte values for the pattern, while the cards span defines the role of each corresponding position. This design allows a search to include literal byte values that might otherwise be interpreted as wildcard characters (e.g., the byte value 63, which is the ASCII code for '?').

TryAdd(ReadOnlySpan<byte>, out int)

Tries to add a key to the dictionary.

bool TryAdd(ReadOnlySpan<byte> key, out int identifier)

Parameters

key ReadOnlySpan<byte>

The key to add.

identifier int

When this method returns, contains the identifier for the new key. If the key already existed, this will be the existing identifier.

Returns

bool

true if the key was newly added; false if the key already existed.

Exceptions

ArgumentException

key is empty.

TryGetKey(int, out byte[])

Tries to get the key associated with the specified identifier.

bool TryGetKey(int identifier, out byte[] key)

Parameters

identifier int

The identifier of the key to get.

key byte[]

When this method returns, contains the key associated with the identifier, if found; otherwise, an empty array.

Returns

bool

true if the key was found; otherwise, false.