Interface IScyllaTrie<TValue>

Contract for a trie (prefix tree) that maps strings to values of type TValue with efficient prefix lookup and lexicographic enumeration. This is the map variant: each key is associated with exactly one value. For the key-only set variant see IScyllaTrie.

Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public interface IScyllaTrie<TValue> : IScyllaCollection
Type Parameters
Name Description
TValue

The type of value associated with each key. May be any type including reference types, value types, and null-able types. When a key is removed or the trie is cleared, stored values are reset to default(TValue) to release object references and avoid memory leaks.
Remarks

Primary use cases: in-game console command lookup by name, mapping command strings to handler delegates or metadata objects, and prefix-based autocomplete that also retrieves associated data for each match.

Prefix semantics: an empty string is a valid prefix that matches all stored keys. Passing an empty string to CopyMatches(string, Span<string>) or CopyMatches(string, Span<KeyValuePair<string, TValue>>) copies every entry, equivalent to CopyKeysTo(Span<string>) and CopyKeyValuePairsTo(Span<KeyValuePair<string, TValue>>) respectively.

Empty-key storage: an empty string is a valid key and may be stored with an associated value. After a successful TryAdd("", value), the root node becomes terminal.

Case sensitivity: implementations may optionally normalise characters to upper-case (invariant culture) during traversal. When case-insensitive mode is active, keys are stored with their original casing but looked up without regard to case. Check the concrete implementation's IgnoreCase property for the active setting.

Lexicographic order: all CopyKeysTo, CopyKeyValuePairsTo, and CopyMatches methods emit entries in ascending lexicographic order determined by the normalised character values stored in the trie's sorted edge lists.

Thread safety: core implementations are unsynchronized. Use AsSynchronized() on the concrete type to obtain a lock-protected wrapper, then check ThreadSafety and SyncRoot as needed.

Methods

ContainsKey(string)

Determines whether the trie contains the specified key as an exact, complete match.

Declaration
bool ContainsKey(string key)
Parameters
Type Name Description
string key

The key to search for. Must not be null. An empty string is a valid key and returns true only if an empty string was previously added with TryAdd(string, TValue).
Returns
Type Description
bool

true if the trie contains a terminal node reached by traversing every character of key; false otherwise.
Exceptions
Type Condition
ArgumentNullException

Thrown when key is null.

ContainsPrefix(string)

Determines whether the trie contains at least one key whose characters begin with the characters of prefix.

Declaration
bool ContainsPrefix(string prefix)
Parameters
Type Name Description
string prefix

The prefix to test. Must not be null. An empty string always returns true when the trie contains any key at all, because every key trivially starts with the empty string.
Returns
Type Description
bool

true if any stored key starts with prefix; false when no such key exists or the trie is empty.
Exceptions
Type Condition
ArgumentNullException

Thrown when prefix is null.

CopyKeyValuePairsTo(Span<KeyValuePair<string, TValue>>)

Copies all stored key/value pairs in ascending lexicographic order (by key) into the provided destination span, stopping when the span is full or all pairs have been written.

Declaration
int CopyKeyValuePairsTo(Span<KeyValuePair<string, TValue>> destination)
Parameters
Type Name Description
Span<KeyValuePair<string, TValue>> destination

The target span of KeyValuePair<TKey, TValue> to write into. If the span length is smaller than Count, only the first destination.Length pairs (in lexicographic key order) are written.
Returns
Type Description
int

The number of pairs written into destination. Returns 0 if the trie is empty or the span has length zero.

CopyKeysTo(Span<string>)

Copies all stored keys in ascending lexicographic order into the provided destination span, stopping when the span is full or all keys have been written.

Declaration
int CopyKeysTo(Span<string> destination)
Parameters
Type Name Description
Span<string> destination

The target span to write keys into. If the span length is smaller than Count, only the first destination.Length keys (in lexicographic order) are written.
Returns
Type Description
int

The number of keys written into destination. Returns 0 if the trie is empty or the span has length zero.

CopyKeysTo(string[], int)

Copies all stored keys in ascending lexicographic order into the provided destination array starting at destinationIndex, stopping when the remaining array space is exhausted or all keys have been written.

Declaration
int CopyKeysTo(string[] destination, int destinationIndex)
Parameters
Type Name Description
string[] destination

The target array to write keys into. Must not be null.
int destinationIndex

The zero-based index in destination at which writing begins. Must be in the range [0, destination.Length].
Returns
Type Description
int

The number of keys written into destination. Returns 0 if the trie is empty or no space is available starting at destinationIndex.
Exceptions
Type Condition
ArgumentNullException

Thrown when destination is null.
ArgumentOutOfRangeException

Thrown when destinationIndex is negative or greater than destination.Length.

CopyMatches(string, Span<KeyValuePair<string, TValue>>)

Copies into destinationPairs all key/value pairs whose key starts with prefix, in ascending lexicographic order (by key), stopping when the span is full or all matching pairs have been written. Use this overload when both the key name and the associated value are needed for each autocomplete result.

Declaration
int CopyMatches(string prefix, Span<KeyValuePair<string, TValue>> destinationPairs)
Parameters
Type Name Description
string prefix

The prefix to filter by. Must not be null. An empty string matches all stored pairs and is equivalent to calling CopyKeyValuePairsTo(Span<KeyValuePair<string, TValue>>).
Span<KeyValuePair<string, TValue>> destinationPairs

The target span of KeyValuePair<TKey, TValue> to write matching pairs into. If shorter than the number of matching entries, only the first destinationPairs.Length matches are written.
Returns
Type Description
int

The number of pairs written into destinationPairs. Returns 0 if no key matches the prefix, the trie is empty, or the span has length zero.
Exceptions
Type Condition
ArgumentNullException

Thrown when prefix is null.

CopyMatches(string, Span<string>)

Copies into destinationKeys all keys that start with prefix, in ascending lexicographic order, stopping when the span is full or all matching keys have been written. This is the primary method for implementing autocomplete / tab-completion when only the key names are needed.

Declaration
int CopyMatches(string prefix, Span<string> destinationKeys)
Parameters
Type Name Description
string prefix

The prefix to filter by. Must not be null. An empty string matches all stored keys and is equivalent to calling CopyKeysTo(Span<string>).
Span<string> destinationKeys

The target span to write matching keys into. If shorter than the number of matching keys, only the first destinationKeys.Length matches are written.
Returns
Type Description
int

The number of keys written into destinationKeys. Returns 0 if no key matches the prefix, the trie is empty, or the span has length zero.
Exceptions
Type Condition
ArgumentNullException

Thrown when prefix is null.

TryAdd(string, TValue)

Attempts to insert a new key/value pair into the trie. Does not modify an existing entry; use TrySet(string, TValue) to update a value.

Declaration
bool TryAdd(string key, TValue value)
Parameters
Type Name Description
string key

The key to add. Must not be null. An empty string is a valid key; it makes the trie root terminal. If the trie is case-insensitive, the key is stored with its original casing but matched in a case-insensitive manner.
TValue value

The value to associate with key. May be any value valid for TValue, including null for reference types.
Returns
Type Description
bool

true if the key/value pair was successfully inserted. false if the key already exists in the trie, or if the trie is operating in fixed-capacity mode and inserting the key would require more nodes or edges than are currently available.
Exceptions
Type Condition
ArgumentNullException

Thrown when key is null.

TryGetValue(string, out TValue)

Attempts to retrieve the value associated with the specified key.

Declaration
bool TryGetValue(string key, out TValue value)
Parameters
Type Name Description
string key

The key to look up. Must not be null. An empty string is a valid key; it succeeds only if an empty string was previously inserted.
TValue value

When this method returns true, contains the value associated with key. When this method returns false, contains default(TValue).
Returns
Type Description
bool

true if the key was found and value was set; false otherwise.
Exceptions
Type Condition
ArgumentNullException

Thrown when key is null.

TryRemove(string)

Attempts to remove the specified key and its associated value from the trie. After a successful removal, any internal nodes or edges that are no longer reachable by any stored key are pruned and their slots returned to the free list for reuse.

Declaration
bool TryRemove(string key)
Parameters
Type Name Description
string key

The key to remove. Must not be null. An empty string is a valid key and clears the terminal flag on the root node when present.
Returns
Type Description
bool

true if the key was found and removed; false if the key does not exist in the trie.
Exceptions
Type Condition
ArgumentNullException

Thrown when key is null.

TrySet(string, TValue)

Attempts to update the value associated with an existing key. Does not insert a new entry; use TryAdd(string, TValue) to add a key that does not yet exist.

Declaration
bool TrySet(string key, TValue value)
Parameters
Type Name Description
string key

The key whose value should be updated. Must not be null.
TValue value

The new value to associate with key. May be any value valid for TValue, including null for reference types.
Returns
Type Description
bool

true if the key was found and its value was updated; false if the key does not exist in the trie.
Exceptions
Type Condition
ArgumentNullException

Thrown when key is null.

Extension Methods

See Also

ScyllaTrie<TValue>