diff --git a/sources/Data/Collections/ArrayList.uc b/sources/Data/Collections/ArrayList.uc index b98875e..3ad0f9e 100644 --- a/sources/Data/Collections/ArrayList.uc +++ b/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`. diff --git a/sources/Data/Collections/Collection.uc b/sources/Data/Collections/Collection.uc index 4d63993..75bdd8e 100644 --- a/sources/Data/Collections/Collection.uc +++ b/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. diff --git a/sources/Data/Collections/HashTable.uc b/sources/Data/Collections/HashTable.uc index 40d4b5c..4dfaf89 100644 --- a/sources/Data/Collections/HashTable.uc +++ b/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`.