Add string getters and setters to new collections

sources/Data/Collections/ArrayList.uc

@@ -730,6 +730,74 @@ public final function ArrayList SetFloat(
     return self;
 }
 
+/**
+ *  Returns `string` item at `index`. If index is invalid or
+ *  stores a non-`Text`/`MutableText` value, returns `defaultValue`.
+ *
+ *  Referred value must be stored as `Text` or `MutableText`
+ *  (or one of their sub-classes) for this method to work.
+ *
+ *  @param  index           Index of a `string` item that `ArrayList`
+ *      has to return.
+ *  @param  defaultValue    Value to return if there is either no item recorded
+ *      at `index` or it has a wrong type.
+ *  @return `string` value at `index` in the caller `ArrayList`.
+ *      `defaultValue` if passed `index` is invalid or non-`Text`/`MutableText`
+ *      value is stored there.
+ */
+public final function string GetString(int index, optional string defaultValue)
+{
+    local AcediaObject  result;
+    local Text          asText;
+    local MutableText   asMutableText;
+
+    result = BorrowItem(index);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = Text(result);
+    if (asText != none) {
+        return asText.ToString();
+    }
+    asMutableText = MutableText(result);
+    if (asMutableText != none) {
+        return asMutableText.ToString();
+    }
+    return defaultValue;
+}
+
+/**
+ *  Changes `ArrayList`'s value at `index` to `value` that will be recorded
+ *  as either `Text` or `MutableText`, depending of `asMutable` optional
+ *  parameter.
+ *
+ *  @param  index       Index, at which to change the value. If `ArrayList` is
+ *      not long enough to hold it, it will be automatically expanded.
+ *      If passed index is negative - method will do nothing.
+ *  @param  value       Value to be set at a given index.
+ *  @param  asMutable   Given `string` value will be recorded as immutable
+ *      `Text` by default (`asMutable == false`). Setting this parameter to
+ *      `true` will make this method record it as a mutable `MutableText`.
+ *  @return Reference to the caller `ArrayList` to allow for method chaining.
+ */
+public final function ArrayList SetString(
+    int             index,
+    string          value,
+    optional bool   asMutable)
+{
+    local AcediaObject newValue;
+
+    if (asMutable) {
+        newValue = _.text.FromStringM(value);
+    }
+    else {
+        newValue = _.text.FromString(value);
+    }
+    SetItem(index, newValue);
+    newValue.FreeSelf();
+    return self;
+}
+
 /**
  *  Returns `BaseText` item at `index`. If index is invalid or
  *  stores a non-`BaseText` value, returns `none`.

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 - 2021 Anton Tarasenko
+ *      Copyright 2020 - 2022 Anton Tarasenko
  *------------------------------------------------------------------------------
  * This file is part of Acedia.
  *
@@ -331,6 +331,44 @@ public final function float GetFloatBy(
     return defaultValue;
 }
 
+/**
+ *  Returns a `string` value stored (in the caller `Collection` or
+ *  one of it's sub-collections) pointed by
+ *  [JSON pointer](https://tools.ietf.org/html/rfc6901).
+ *  See `GetItemBy()` for more information.
+ *
+ *  Referred value must be stored as `Text` or `MutableText`
+ *  (or one of their sub-classes) for this method to work.
+ *
+ *  @param  jsonPointerAsText   Description of a path to the `string` value.
+ *  @param  defaultValue        Value to return in case `jsonPointerAsText`
+ *      does not point at any existing value or if that value does not have
+ *      appropriate type.
+ *  @return `string` value, stored at `jsonPointerAsText` or `defaultValue` if
+ *      it is missing or has a different type.
+ */
+public final function string GetStringBy(
+    BaseText        jsonPointerAsText,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local Text          asText;
+    local MutableText   asMutableText;
+    result = GetItemBy(jsonPointerAsText);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = Text(result);
+    if (asText != none) {
+        return asText.ToString();
+    }
+    asMutableText = MutableText(result);
+    if (asMutableText != none) {
+        return asMutableText.ToString();
+    }
+    return defaultValue;
+}
+
 /**
  *  Returns a `Text` value stored (in the caller `Collection` or
  *  one of it's sub-collections) pointed by
@@ -573,6 +611,43 @@ public final function float GetFloatByJSON(
     return defaultValue;
 }
 
+/**
+ *  Returns a `string` value stored (in the caller `Collection` or
+ *  one of it's sub-collections) pointed by JSON pointer.
+ *  See `GetItemByJSON()` for more information.
+ *
+ *  Referred value must be stored as `Text` or `MutableText`
+ *  (or one of their sub-classes) for this method to work.
+ *
+ *  @param  jsonPointer     JSON path to the `string` value.
+ *  @param  defaultValue    Value to return in case `jsonPointer`
+ *      does not point at any existing value or if that value does not have
+ *      appropriate type.
+ *  @return `string` value, stored at `jsonPointerAsText` or `defaultValue` if
+ *      it is missing or has a different type.
+ */
+public final function string GetStringByJSON(
+    JSONPointer     jsonPointer,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local Text          asText;
+    local MutableText   asMutableText;
+    result = GetItemByJSON(jsonPointer);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = Text(result);
+    if (asText != none) {
+        return asText.ToString();
+    }
+    asMutableText = MutableText(result);
+    if (asMutableText != none) {
+        return asMutableText.ToString();
+    }
+    return defaultValue;
+}
+
 /**
  *  Returns a `Text` value stored (in the caller `Collection` or
  *  one of it's sub-collections) pointed by JSON pointer.

sources/Data/Collections/HashTable.uc

@@ -943,6 +943,77 @@ public final function HashTable SetFloat(
     return self;
 }
 
+/**
+ *  Returns `string` item at key `key`. If key is invalid or
+ *  stores a non-`Text`/`MutableText` value, returns `defaultValue`.
+ *
+ *  Referred value must be stored as `Text` or `MutableText`
+ *  (or one of their sub-classes) for this method to work.
+ *
+ *  @param  key             Key of a `string` item that `HashTable` has to
+ *      return.
+ *  @param  defaultValue    Value to return if there is either no item recorded
+ *      at `key` or it has a wrong type.
+ *  @return `string` value at `key` in the caller `HashTable`.
+ *      `defaultValue` if passed `key` is invalid or non-`Text`/`MutableText`
+ *      value is stored with it.
+ */
+public final function string GetString(
+    AcediaObject    key,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local Text          asText;
+    local MutableText   asMutableText;
+
+    result = BorrowItem(key);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = Text(result);
+    if (asText != none) {
+        return asText.ToString();
+    }
+    asMutableText = MutableText(result);
+    if (asMutableText != none) {
+        return asMutableText.ToString();
+    }
+    return defaultValue;
+}
+
+/**
+ *  Changes `HashTable`'s value at key `key` to `value` that will be
+ *  recorded as either `Text` or `MutableText`, depending of `asMutable`
+ *  optional parameter.
+ *
+ *  @param  key         Key, at which to change the value. If `DynamicArray` is
+ *      not long enough to hold it, it will be automatically expanded.
+ *      If passed key is negative - method will do nothing.
+ *  @param  value       Value to be set at a given key.
+ *  @param  asMutable   Given `float` value will be recorded as immutable
+ *      `Text` by default (`asMutable == false`). Setting this parameter to
+ *      `true` will make this method record it as a mutable `MutableText`.
+ *  @return Reference to the caller `HashTable` to allow for
+ *      method chaining.
+ */
+public final function HashTable SetString(
+    AcediaObject    key,
+    string          value,
+    optional bool   asMutable)
+{
+    local AcediaObject newValue;
+
+    if (asMutable) {
+        newValue = _.text.FromStringM(value);
+    }
+    else {
+        newValue = _.text.FromString(value);
+    }
+    SetItem(key, newValue);
+    newValue.FreeSelf();
+    return self;
+}
+
 /**
  *  Returns `Text` item stored at key `key`. If key is invalid or
  *  stores a non-`Text` value, returns `none`.