Add methods for checking value existence for `Collection`s

sources/Data/Collections/ArrayList.uc

@@ -456,7 +456,40 @@ public final function int Find(AcediaObject item)
     return -1;
 }
 
-protected function AcediaObject GetByText(BaseText key)
+/**
+ *  `ArrayList` only support `IntBox` and `IntRef` indices for this method.
+ */
+public function bool HasKey(AcediaObject key)
+{
+    if (key == none) {
+        return false;
+    }
+    else if (key.class == class'IntBox') {
+        return ValidateIndex(IntBox(key).Get());
+    }
+    else if (key.class == class'IntRef') {
+        return ValidateIndex(IntRef(key).Get());
+    }
+    return false;
+}
+
+public function bool HasKeyByText(Text key)
+{
+    local int       index, consumed;
+    local Parser    parser;
+
+    parser = _.text.Parse(key);
+    parser.MUnsignedInteger(index,,, consumed);
+    if (!parser.Ok())
+    {
+        parser.FreeSelf();
+        return false;
+    }
+    parser.FreeSelf();
+    return ValidateIndex(index);
+}
+
+public function AcediaObject GetByText(Text key)
 {
     local int       index, consumed;
     local Parser    parser;

sources/Data/Collections/Collection.uc

@@ -2,7 +2,7 @@
  *      Acedia provides a small set of collections for easier data storage.
  *      This is their base class that provides a simple interface for
  *  common methods.
- *      Copyright 2020 - 2022 Anton Tarasenko
+ *      Copyright 2020-2023 Anton Tarasenko
  *------------------------------------------------------------------------------
  * This file is part of Acedia.
  *
@@ -25,18 +25,46 @@ class Collection extends AcediaObject
 var protected class<CollectionIterator> iteratorClass;
 
 /**
- *  Method that must be overloaded for `GetItemByPointer()` to properly work.
+ *  Checks if caller `Collection` has value recorded with a given `key`.
  *
- *      This method must return an item that `key` refers to with it's
+ *  Not all collections must support all possible types of keys.
- *  textual content (not as an object itself).
+ *  Key equality is determined by `AcediaObject::IsEqual()` method.
+ *
+ *  @return `true` if caller `Collection` has value recorded with
+ *      a given `key` and `false` otherwise.
+ */
+public function bool HasKey(AcediaObject key);
+
+/**
+ *  Checks if caller `Collection` has value that a given `key` refers to with
+ *  its textual content (not as an object itself).
  *      For example, `ArrayList` parses it into unsigned number, while
  *  `HashTable` uses it as a key directly.
+ *      There is no requirement that all stored values must be reachable by
+ *  this method (i.e. `HashTable` only lets you access values with
+ *  `Text` keys).
  *
+ *  @return `true` if caller `Collection` has value recorded with
+ *      a given `key` (understood within its textual content) and `false`
+ *      otherwise.
+ */
+public function bool HasKeyByText(Text key);
+
+/**
+ *      This method must return an item that `key` refers to with its
+ *  textual content (not as an object itself).
+ *      For example, `ArrayList` parses it into unsigned number, while
+ *  `HashTable` uses it as a key directly.
  *      There is no requirement that all stored values must be reachable by
  *  this method (i.e. `HashTable` only lets you access values with
  *  `Text` keys).
+ *
+ *  To check whether such value even exists in the collection @see HasKeyByText.
+ *
+ *  @param  key Key that refers to the value to return.
+ *  @return Value that `key` refers to with its textual content.
  */
-protected function AcediaObject GetByText(BaseText key);
+public function AcediaObject GetByText(Text key);
 
 /**
  *  Creates an `Iterator` instance to iterate over stored items.
@@ -88,7 +116,7 @@ public function Empty() {}
  *  this method (i.e. `HashTable` only lets you access values with `Text` keys).
  *
  *  @param  jsonPointer Path, given by a JSON pointer.
- *  @return An item `jsonPointerAsText` is referring to (according to the above
+ *  @return An item `jsonPointer` is referring to (according to the above
  *      stated rules). `none` if such item does not exist.
  */
 public final function AcediaObject GetItemByJSON(JSONPointer jsonPointer)

sources/Data/Collections/HashTable.uc

@@ -234,19 +234,18 @@ public final function SetMinimalCapacity(int newMinimalCapacity)
     UpdateHashTableSize();
 }
 
-/**
+public function bool HasKey(AcediaObject key)
- *  Checks if caller `HashTable` has value recorded with a given `key`.
- *
- *  @return `true` if caller `HashTable` has value recorded with
- *      a given `key` and `false` otherwise.
- */
-public final function bool HasKey(AcediaObject key)
 {
     local int bucketIndex, entryIndex;
 
     return FindEntryIndices(key, bucketIndex, entryIndex);
 }
 
+public function bool HasKeyByText(Text key)
+{
+    return HasKey(key);
+}
+
 /**
  *  Returns borrowed value recorded by a given key `key` in the caller
  *  `HashTable`.
@@ -629,7 +628,7 @@ public final function AcediaObject GetKeyByIndex(Index index)
     return key.NewRef();
 }
 
-protected function AcediaObject GetByText(BaseText key)
+public function AcediaObject GetByText(Text key)
 {
     return GetItem(key);
 }