Class KeyRecordDictionary.StringSpecialized

Namespace

BelNytheraSeiche.TrieDictionary

Assembly

BelNytheraSeiche.TrieDictionary.dll

Provides a string-specialized wrapper around an KeyRecordDictionary.IKeyAccess instance, simplifying operations by handling string-to-byte encoding and decoding.

public sealed class KeyRecordDictionary.StringSpecialized

Inheritance

object

KeyRecordDictionary.StringSpecialized

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Dictionary

Gets the underlying KeyRecordDictionary.IKeyAccess dictionary.

public KeyRecordDictionary.IKeyAccess Dictionary { get; }

Property Value

KeyRecordDictionary.IKeyAccess

Encoding

Gets the Encoding used for string conversions.

public Encoding Encoding { get; }

Property Value

Encoding

Methods

Add(string)

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

public int Add(string key)

Parameters

key string

The string key to add.

Returns

int

The identifier for the added or existing key.

Exceptions

ArgumentNullException

key is null.

ArgumentException

key is empty.

Contains(string)

Determines whether the dictionary contains the specified key.

public bool Contains(string key)

Parameters

key string

The string key to locate.

Returns

bool

true if the key is found; otherwise, false.

Exceptions

ArgumentNullException

key is null.

EnumerateAll(bool)

Enumerates all keys in the dictionary as strings.

public IEnumerable<(int, string)> EnumerateAll(bool reverse = false)

Parameters

reverse bool

If true, returns keys in reverse order.

Returns

IEnumerable<(int, string)>

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

FindFirst(out int, out string)

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

public bool FindFirst(out int identifier, out string key)

Parameters

identifier int

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

key string

When this method returns, the first key as a string.

Returns

bool

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

FindLast(out int, out string)

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

public bool FindLast(out int identifier, out string key)

Parameters

identifier int

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

key string

When this method returns, the last key as a string.

Returns

bool

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

FindNext(int, out int, out string)

Finds the next key in sequence after the specified identifier.

public bool FindNext(int currentIdentifier, out int foundIdentifier, out string foundKey)

Parameters

currentIdentifier int

The identifier to start the search from.

foundIdentifier int

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

foundKey string

When this method returns, the next key as a string.

Returns

bool

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

FindNext(string, out int, out string)

Finds the next key in sequence after the specified key.

public bool FindNext(string currentKey, out int foundIdentifier, out string foundKey)

Parameters

currentKey string

The string key to start the search from.

foundIdentifier int

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

foundKey string

When this method returns, the next key as a string.

Returns

bool

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

Exceptions

ArgumentNullException

currentKey is null.

FindPrevious(int, out int, out string)

Finds the previous key in sequence before the specified identifier.

public bool FindPrevious(int currentIdentifier, out int foundIdentifier, out string foundKey)

Parameters

currentIdentifier int

The identifier to start the search from.

foundIdentifier int

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

foundKey string

When this method returns, the previous key as a string.

Returns

bool

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

FindPrevious(string, out int, out string)

Finds the previous key in sequence before the specified key.

public bool FindPrevious(string currentKey, out int foundIdentifier, out string foundKey)

Parameters

currentKey string

The string key to start the search from.

foundIdentifier int

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

foundKey string

When this method returns, the previous key as a string.

Returns

bool

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

Exceptions

ArgumentNullException

currentKey is null.

GetKey(int)

Gets the key associated with the specified identifier.

public string GetKey(int identifier)

Parameters

identifier int

The identifier of the key to get.

Returns

string

The key as a string.

GetRecordAccess(int, bool)

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

public 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(string)

Removes a key from the dictionary.

public bool Remove(string key)

Parameters

key string

The string key to remove.

Returns

bool

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

Exceptions

ArgumentNullException

key is null.

SearchByPrefix(string, bool)

Finds all keys that start with the given prefix.

public IEnumerable<(int, string)> SearchByPrefix(string text, bool reverse = false)

Parameters

text string

The prefix to search for.

reverse bool

If true, returns results in reverse order.

Returns

IEnumerable<(int, string)>

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

Remarks

This is the string-specialized version of this method. For detailed behavior and examples, see SearchByPrefix(ReadOnlySpan<byte>, bool).

Exceptions

ArgumentNullException

text is null.

SearchCommonPrefix(string)

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

public IEnumerable<(int, string)> SearchCommonPrefix(string text)

Parameters

text string

The text to search within.

Returns

IEnumerable<(int, string)>

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

Remarks

This is the string-specialized version of this method. For detailed behavior and examples, see SearchCommonPrefix(ReadOnlySpan<byte>).

Exceptions

ArgumentNullException

text is null.

SearchExactly(string)

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

public int SearchExactly(string text)

Parameters

text string

The string key to search for.

Returns

int

The identifier for the key if found; otherwise, a value indicating not found.

Exceptions

ArgumentNullException

text is null.

SearchLongestPrefix(string)

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

public (int, string) SearchLongestPrefix(string text)

Parameters

text string

The text to search within.

Returns

(int, string)

A tuple containing the identifier and string key of the longest matching prefix, or (-1, "") if no match is found.

Remarks

This is the string-specialized version of this method. For detailed behavior and examples, see SearchLongestPrefix(ReadOnlySpan<byte>).

Exceptions

ArgumentNullException

text is null.

SearchWildcard(string, char, char, bool)

Performs a wildcard search using user-defined wildcard characters.

public IEnumerable<(int, string)> SearchWildcard(string pattern, char cardQ = '?', char cardA = '*', bool reverse = false)

Parameters

pattern string

The search pattern.

cardQ char

The character to be treated as a single-character wildcard ('?'), which matches any single character.

cardA char

The character to be treated as a multi-character wildcard ('*'), which matches any sequence of zero or more characters.

reverse bool

If true, returns results in reverse order.

Returns

IEnumerable<(int, string)>

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

Remarks

This is a convenience method that provides a simple way to perform wildcard searches. It internally translates the pattern for use by the more advanced SearchWildcard(string, string, bool) overload. A call like

SearchWildcard("Hell?*World")

is internally converted to an equivalent call:

SearchWildcard("Hell?*World", "....?*.....")

.

The second argument, "cards", specifies that '?' and '*' should be treated as wildcards, while '.' indicates a literal character match.

Encoding Limitation: The multi-character wildcard ('*') is only fully supported for single-byte encodings (codepage 1252, 20127 and 28591). The single-character wildcard ('?') is supported for some encodings (codepage 1200, 1201, 1252, 12000, 20127 and 28591).

Exceptions

ArgumentNullException

pattern is null.

NotSupportedException

The current encoding is not supported for wildcard searches.

SearchWildcard(string, string, bool)

Performs a wildcard search using a standardized wildcard pattern.

public IEnumerable<(int, string)> SearchWildcard(string text, string cards, bool reverse = false)

Parameters

text string

The search pattern as a string.

cards string

A string of the same length as text's byte representation, where '?' is a single wildcard, '*' is a multiple wildcard, and '.' is a literal match.

reverse bool

If true, returns results in reverse order.

Returns

IEnumerable<(int, string)>

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

Remarks

This is the string-specialized version of this method. For detailed behavior and examples, see SearchWildcard(ReadOnlySpan<byte>, ReadOnlySpan<char>, bool).

Encoding Limitation: The multi-character wildcard ('*') is only fully supported for single-byte encodings (codepage 1252, 20127 and 28591). The single-character wildcard ('?') is supported for some encodings (codepage 1200, 1201, 1252, 12000, 20127 and 28591).

Exceptions

ArgumentNullException

text is null.

ArgumentNullException

cards is null.

ArgumentException

cards and cards are different length.

NotSupportedException

The current encoding is not supported for wildcard searches.

TryAdd(string, out int)

Tries to add a key to the dictionary.

public bool TryAdd(string key, out int identifier)

Parameters

key string

The string 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

ArgumentNullException

key is null.

ArgumentException

key is empty.

TryGetKey(int, out string)

Tries to get the key associated with the specified identifier.

public bool TryGetKey(int identifier, out string key)

Parameters

identifier int

The identifier of the key to get.

key string

When this method returns, contains the key as a string, if found; otherwise, an empty string.

Returns

bool

true if the key was found; otherwise, false.