From b8647154fd19f4358e6de96190558f7edd9270a4 Mon Sep 17 00:00:00 2001 From: Anton Tarasenko Date: Tue, 5 Jul 2022 01:47:05 +0700 Subject: [PATCH] Add more convenience `string` getters and setters --- sources/Data/Collections/ArrayList.uc | 182 +++++++++++++++++++++++-- sources/Data/Collections/Collection.uc | 95 ++++++++++--- sources/Data/Collections/HashTable.uc | 117 +++++++++++----- 3 files changed, 326 insertions(+), 68 deletions(-) diff --git a/sources/Data/Collections/ArrayList.uc b/sources/Data/Collections/ArrayList.uc index 3ad0f9e..5342059 100644 --- a/sources/Data/Collections/ArrayList.uc +++ b/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`. diff --git a/sources/Data/Collections/Collection.uc b/sources/Data/Collections/Collection.uc index 75bdd8e..8d18b5e 100644 --- a/sources/Data/Collections/Collection.uc +++ b/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; } diff --git a/sources/Data/Collections/HashTable.uc b/sources/Data/Collections/HashTable.uc index 4dfaf89..13be517 100644 --- a/sources/Data/Collections/HashTable.uc +++ b/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`.