Add more convenience `string` getters and setters

sources/Data/Collections/ArrayList.uc

@@ -731,8 +731,8 @@ public final function ArrayList SetFloat(
 }
 
 /**
- *  Returns `string` item at `index`. If index is invalid or
- *  stores a non-`Text`/`MutableText` value, returns `defaultValue`.
+ *  Returns plain string item at `index`. If index is invalid or
+ *  stores a non-`BaseText` value, returns `defaultValue`.
  *
  *  Referred value must be stored as `Text` or `MutableText`
  *  (or one of their sub-classes) for this method to work.
@@ -741,35 +741,30 @@ public final function ArrayList SetFloat(
  *      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`
+ *  @return Plain string value at `index` in the caller `ArrayList`.
+ *      `defaultValue` if passed `index` is invalid or non-`BaseText`
  *      value is stored there.
  */
 public final function string GetString(int index, optional string defaultValue)
 {
     local AcediaObject  result;
-    local Text          asText;
-    local MutableText   asMutableText;
+    local BaseText      asText;
 
     result = BorrowItem(index);
     if (result == none) {
         return defaultValue;
     }
-    asText = Text(result);
+    asText = BaseText(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.
+ *  Changes `ArrayList`'s value at `index` to `value` (treated as a plain
+ *  string) 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.
@@ -798,6 +793,165 @@ public final function ArrayList SetString(
     return self;
 }
 
+/**
+ *  Returns formatted string item at `index`. If index is invalid or
+ *  stores a non-`BaseText` 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 Formatted string value at `index` in the caller `ArrayList`.
+ *      `defaultValue` if passed `index` is invalid or non-`BaseText`
+ *      value is stored there.
+ */
+public final function string GetFormattedString(
+    int             index,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local BaseText      asText;
+
+    result = BorrowItem(index);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = BaseText(result);
+    if (asText != none) {
+        return asText.ToFormattedString();
+    }
+    return defaultValue;
+}
+
+/**
+ *  Changes `ArrayList`'s value at `index` to `value` (treated as a formatted
+ *  string) 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 SetFormattedString(
+    int             index,
+    string          value,
+    optional bool   asMutable)
+{
+    local AcediaObject newValue;
+
+    if (asMutable) {
+        newValue = _.text.FromFormattedStringM(value);
+    }
+    else {
+        newValue = _.text.FromFormattedString(value);
+    }
+    SetItem(index, newValue);
+    newValue.FreeSelf();
+    return self;
+}
+
+/**
+ *      Adds given `bool` at the end of the `ArrayList`, expanding it by
+ *  one item.
+ *
+ *  @param  value   `bool` value to be added at the end of the `ArrayList`.
+ *  @param  asRef   Given `bool` value will be recorded as immutable `BoolBox`
+ *      by default (`asRef == false`). Setting this parameter to `true` will
+ *      make this method record it as a mutable `BoolRef`.
+ *  @return Reference to the caller `ArrayList` to allow for method chaining.
+ */
+public final function ArrayList AddBool(bool value, optional bool asRef)
+{
+    return SetBool(storedObjects.length, value, asRef);
+}
+
+/**
+ *      Adds given `byte` at the end of the `ArrayList`, expanding it by
+ *  one item.
+ *
+ *  @param  value   `byte` value to be added at the end of the `ArrayList`.
+ *  @param  asRef   Given `byte` value will be recorded as immutable `ByteBox`
+ *      by default (`asRef == false`). Setting this parameter to `true` will
+ *      make this method record it as a mutable `ByteRef`.
+ *  @return Reference to the caller `ArrayList` to allow for method chaining.
+ */
+public final function ArrayList AddByte(byte value, optional bool asRef)
+{
+    return SetByte(storedObjects.length, value, asRef);
+}
+
+/**
+ *      Adds given `int` at the end of the `ArrayList`, expanding it by
+ *  one item.
+ *
+ *  @param  value   `int` value to be added at the end of the `ArrayList`.
+ *  @param  asRef   Given `int` value will be recorded as immutable `IntBox`
+ *      by default (`asRef == false`). Setting this parameter to `true` will
+ *      make this method record it as a mutable `IntRef`.
+ *  @return Reference to the caller `ArrayList` to allow for method chaining.
+ */
+public final function ArrayList AddInt(int value, optional bool asRef)
+{
+    return SetInt(storedObjects.length, value, asRef);
+}
+
+/**
+ *      Adds given `float` at the end of the `ArrayList`, expanding it by
+ *  one item.
+ *
+ *  @param  value   `float` value to be added at the end of the `ArrayList`.
+ *  @param  asRef   Given `float` value will be recorded as immutable `FloatBox`
+ *      by default (`asRef == false`). Setting this parameter to `true` will
+ *      make this method record it as a mutable `FloatRef`.
+ *  @return Reference to the caller `ArrayList` to allow for method chaining.
+ */
+public final function ArrayList AddFloat(float value, optional bool asRef)
+{
+    return SetFloat(storedObjects.length, value, asRef);
+}
+
+/**
+ *      Adds given plain string at the end of the `ArrayList`, expanding it by
+ *  one item.
+ *
+ *  @param  value   Plain string value to be added at the end of
+ *      the `ArrayList`.
+ *  @param  asRef   Given plain string value will be recorded as immutable
+ *      `Text` by default (`asRef == 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 AddString(string value, optional bool asRef)
+{
+    return SetString(storedObjects.length, value, asRef);
+}
+
+/**
+ *      Adds given formatted string at the end of the `ArrayList`, expanding it
+ *  by one item.
+ *
+ *  @param  value   Formatted string value to be added at the end of
+ *      the `ArrayList`.
+ *  @param  asRef   Given formatted string value will be recorded as immutable
+ *      `Text` by default (`asRef == 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 AddFormattedString(
+    string          value,
+    optional bool   asRef)
+{
+    return SetFormattedString(storedObjects.length, value, asRef);
+}
+
 /**
  *  Returns `BaseText` item at `index`. If index is invalid or
  *  stores a non-`BaseText` value, returns `none`.

sources/Data/Collections/Collection.uc

@@ -332,39 +332,67 @@ public final function float GetFloatBy(
 }
 
 /**
- *  Returns a `string` value stored (in the caller `Collection` or
+ *  Returns a plain 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.
+ *  Referred value must be stored as `BaseText` (or one of its 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.
+ *  @return Plain 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;
+    local Basetext      asText;
     result = GetItemBy(jsonPointerAsText);
     if (result == none) {
         return defaultValue;
     }
-    asText = Text(result);
+    asText = BaseText(result);
     if (asText != none) {
         return asText.ToString();
     }
-    asMutableText = MutableText(result);
-    if (asMutableText != none) {
-        return asMutableText.ToString();
+    return defaultValue;
+}
+
+/**
+ *  Returns a formatted 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 `BaseText` (or one of its 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 Formatted string value, stored at `jsonPointerAsText` or
+ *      `defaultValue` if it is missing or has a different type.
+ */
+public final function string GetFormattedStringBy(
+    BaseText        jsonPointerAsText,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local Basetext      asText;
+    result = GetItemBy(jsonPointerAsText);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = BaseText(result);
+    if (asText != none) {
+        return asText.ToFormattedString();
     }
     return defaultValue;
 }
@@ -612,7 +640,7 @@ public final function float GetFloatByJSON(
 }
 
 /**
- *  Returns a `string` value stored (in the caller `Collection` or
+ *  Returns a plain string value stored (in the caller `Collection` or
  *  one of it's sub-collections) pointed by JSON pointer.
  *  See `GetItemByJSON()` for more information.
  *
@@ -623,27 +651,54 @@ public final function float GetFloatByJSON(
  *  @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.
+ *  @return Plain 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;
+    local BaseText      asText;
     result = GetItemByJSON(jsonPointer);
     if (result == none) {
         return defaultValue;
     }
-    asText = Text(result);
+    asText = BaseText(result);
     if (asText != none) {
         return asText.ToString();
     }
-    asMutableText = MutableText(result);
-    if (asMutableText != none) {
-        return asMutableText.ToString();
+    return defaultValue;
+}
+
+/**
+ *  Returns a formatted 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 `BaseText` (or one of its 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 Formatted string value, stored at `jsonPointerAsText` or
+ *      `defaultValue` if it is missing or has a different type.
+ */
+public final function string GetFormattedStringByJSON(
+    JSONPointer     jsonPointer,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local BaseText      asText;
+    result = GetItemByJSON(jsonPointer);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = BaseText(result);
+    if (asText != none) {
+        return asText.ToFormattedString();
     }
     return defaultValue;
 }

sources/Data/Collections/HashTable.uc

@@ -706,9 +706,7 @@ public final function bool GetBool(AcediaObject key, optional bool defaultValue)
  *  recorded as either `BoolBox` or `BoolRef`, depending of `asRef`
  *  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  key     Key, at which to change the value.
  *  @param  value   Value to be set at a given key.
  *  @param  asRef   Given `bool` value will be recorded as immutable `BoolBox`
  *      by default (`asRef == false`). Setting this parameter to `true` will
@@ -775,9 +773,7 @@ public final function byte GetByte(AcediaObject key, optional byte defaultValue)
  *  recorded as either `ByteBox` or `ByteBox`, depending of `asRef`
  *  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  key     Key, at which to change the value.
  *  @param  value   Value to be set at a given key.
  *  @param  asRef   Given `byte` value will be recorded as immutable `ByteBox`
  *      by default (`asRef == false`). Setting this parameter to `true` will
@@ -844,9 +840,7 @@ public final function int GetInt(AcediaObject key, optional int defaultValue)
  *  recorded as either `IntBox` or `IntRef`, depending of `asRef`
  *  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  key     Key, at which to change the value.
  *  @param  value   Value to be set at a given key.
  *  @param  asRef   Given `int` value will be recorded as immutable `IntBox`
  *      by default (`asRef == false`). Setting this parameter to `true` will
@@ -915,15 +909,12 @@ public final function float GetFloat(
  *  recorded as either `FloatBox` or `FloatRef`, depending of `asRef`
  *  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  key     Key, at which to change the value.
  *  @param  value   Value to be set at a given key.
  *  @param  asRef   Given `float` value will be recorded as immutable `FloatBox`
  *      by default (`asRef == false`). Setting this parameter to `true` will
  *      make this method record it as a mutable `FloatRef`.
- *  @return Reference to the caller `HashTable` to allow for
- *      method chaining.
+ *  @return Reference to the caller `HashTable` to allow for method chaining.
  */
 public final function HashTable SetFloat(
     AcediaObject    key,
@@ -944,53 +935,46 @@ public final function HashTable SetFloat(
 }
 
 /**
- *  Returns `string` item at key `key`. If key is invalid or
- *  stores a non-`Text`/`MutableText` value, returns `defaultValue`.
+ *  Returns plain string item at key `key`. If key is invalid or stores
+ *  a non-`BaseText` value, returns `defaultValue`.
  *
- *  Referred value must be stored as `Text` or `MutableText`
- *  (or one of their sub-classes) for this method to work.
+ *  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.
+ *  @return Plain string value at `key` in the caller `HashTable`.
+ *      `defaultValue` if passed `key` is invalid or non-`BaseText` value is
+ *      stored with it.
  */
 public final function string GetString(
     AcediaObject    key,
     optional string defaultValue)
 {
     local AcediaObject  result;
-    local Text          asText;
-    local MutableText   asMutableText;
+    local BaseText      asText;
 
     result = BorrowItem(key);
     if (result == none) {
         return defaultValue;
     }
-    asText = Text(result);
+    asText = BaseText(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`
+ *  Changes `HashTable`'s value at key `key` to plain string `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  key         Key, at which to change the value.
  *  @param  value       Value to be set at a given key.
- *  @param  asMutable   Given `float` value will be recorded as immutable
+ *  @param  asMutable   Given plain 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 `HashTable` to allow for
@@ -1014,6 +998,71 @@ public final function HashTable SetString(
     return self;
 }
 
+/**
+ *  Returns formatted string item at key `key`. If key is invalid or stores
+ *  a non-`BaseText` 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 Formatted string value at `key` in the caller `HashTable`.
+ *      `defaultValue` if passed `key` is invalid or non-`BaseText` value is
+ *      stored with it.
+ */
+public final function string GetFormattedString(
+    AcediaObject    key,
+    optional string defaultValue)
+{
+    local AcediaObject  result;
+    local BaseText      asText;
+
+    result = BorrowItem(key);
+    if (result == none) {
+        return defaultValue;
+    }
+    asText = BaseText(result);
+    if (asText != none) {
+        return asText.ToFormattedString();
+    }
+    return defaultValue;
+}
+
+/**
+ *  Changes `HashTable`'s value at key `key` to formatted string `value` that
+ *  will be recorded as either `Text` or `MutableText`, depending of `asMutable`
+ *  optional parameter.
+ *
+ *  @param  key         Key, at which to change the value.
+ *  @param  value       Value to be set at a given key.
+ *  @param  asMutable   Given formatted 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 `HashTable` to allow for
+ *      method chaining.
+ */
+public final function HashTable SetFormattedString(
+    AcediaObject    key,
+    string          value,
+    optional bool   asMutable)
+{
+    local AcediaObject newValue;
+
+    if (asMutable) {
+        newValue = _.text.FromFormattedStringM(value);
+    }
+    else {
+        newValue = _.text.FromFormattedString(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`.