From 113a50851f21a73dfe696c68dbed1f4b27f34367 Mon Sep 17 00:00:00 2001
From: Anton Tarasenko <dkanus@gmail.com>
Date: Tue, 13 Jul 2021 05:18:51 +0700
Subject: [PATCH] Add new convenience methods in `TextAPI`

Add method for checking whether certain `Text` is empty (`none` or has
zero recorded characters).

Add methods for converting and deallocation (in the same action) passed
`Text` value into the `string`.
---
 sources/Text/TextAPI.uc | 82 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/sources/Text/TextAPI.uc b/sources/Text/TextAPI.uc
index b489dad..8512ea1 100644
--- a/sources/Text/TextAPI.uc
+++ b/sources/Text/TextAPI.uc
@@ -265,6 +265,88 @@ public final function Text.Character GetCharacter(
     return result;
 }
 
+/**
+ *  Auxiliary method for checking whether `Text` object defines an "empty"
+ *  `string`. That is, if it's either `none` or has empty contents.
+ *
+ *  It is added, since it allows to replace two common checks
+ *  `text == none || text.IsEmpty()` with a nicer looking one:
+ *  `_.text.IsEmpty(text)`.
+ *
+ *  @param  text    `Text` to check for emptiness.
+ *  @return `true` iff either passed `text == none` or `text.IsEmpty()`.
+ */
+public final function bool IsEmpty(Text text)
+{
+    return (text == none || text.IsEmpty());
+}
+
+/**
+ *  Converts given `Text` into a plain `string`, returns it's value and
+ *  deallocates passed `Text`.
+ *
+ *  Method introduced to simplify a common use-case of converting returned copy
+ *  of `Text` into a `string`, which required additional variable to store and
+ *  later deallocate `Text` reference.
+ *
+ *  @param  toConvert   `Text` to convert.
+ *  @return `string` representation of passed `Text` as a plain `string`.
+ *      Empty `string`, if `toConvert == none`.
+ */
+public final function string ToString(Text toConvert)
+{
+    local string result;
+    if (toConvert != none) {
+        result = toConvert.ToPlainString();
+    }
+    _.memory.Free(toConvert);
+    return result;
+}
+
+/**
+ *  Converts given `Text` into a colored `string`, returns it's value and
+ *  deallocates passed `Text`.
+ *
+ *  Method introduced to simplify a common use-case of converting returned copy
+ *  of `Text` into a `string`, which required additional variable to store and
+ *  later deallocate `Text` reference.
+ *
+ *  @param  toConvert   `Text` to convert.
+ *  @return `string` representation of passed `Text` as a colored `string`.
+ *      Empty `string`, if `toConvert == none`.
+ */
+public final function string ToColoredString(Text toConvert)
+{
+    local string result;
+    if (toConvert != none) {
+        result = toConvert.ToColoredString();
+    }
+    _.memory.Free(toConvert);
+    return result;
+}
+
+/**
+ *  Converts given `Text` into a formatted `string`, returns it's value and
+ *  deallocates passed `Text`.
+ *
+ *  Method introduced to simplify a common use-case of converting returned copy
+ *  of `Text` into a `string`, which required additional variable to store and
+ *  later deallocate `Text` reference.
+ *
+ *  @param  toConvert   `Text` to convert.
+ *  @return `string` representation of passed `Text` as a formatted `string`.
+ *      Empty `string`, if `toConvert == none`.
+ */
+public final function string ToFormattedString(Text toConvert)
+{
+    local string result;
+    if (toConvert != none) {
+        result = toConvert.ToFormattedString();
+    }
+    _.memory.Free(toConvert);
+    return result;
+}
+
 /**
  *  Creates a `string` that consists only of a given character.
  *