Add extensions to Any, Collection and Array

base/src/main/kotlin/de/staropensource/engine/base/extension/Any.kt

@@ -0,0 +1,71 @@
+/*
+ * STAROPENSOURCE ENGINE SOURCE FILE
+ * Copyright (c) 2024 The StarOpenSource Engine Authors
+ * Licensed under the GNU General Public License v3.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.staropensource.engine.base.extension
+
+/**
+ * Returns a string representation of this object.
+ *
+ * Respects edge cases and handles
+ * the following things nicely:
+ * - Enums (`some.package.EnumClass.ENUM_VALUE`)
+ * - Strings/CharSequences (`"some string"`, see argument `quoteStrings`)
+ * - Chars (`'a'`, see argument `quoteChar`)
+ * - Bytes (`0xFF`, including unsigned variant (see blow))
+ * - ByteArrays (`0x[ D6, 05, 32 ]`)
+ * - prefixes for unsigned numbers (`0xACu`, `6899u`, `1078518u`, `5818858186961UL`, `1.51f`)
+ *
+ * Everything else is simply returned using [toString].
+ *
+ * @param quoteStrings if to quote [CharSequence]s
+ * @param quoteChars   if to quote [Char]s
+ */
+@OptIn(ExperimentalStdlibApi::class)
+fun Any.toStringType(
+    quoteStrings: Boolean = true,
+    quoteChars: Boolean = true,
+): String {
+    // Enums
+    return if (this is Enum<*>)
+        "${this::class.qualifiedName ?: "<anonymous enum>"}.${name}"
+
+    // Strings and Chars
+    else if (this is CharSequence && quoteStrings)
+        "\"${this}\""
+    else if (this is Char && quoteChars)
+        "'${this}'"
+
+    // Bytes
+    else if (this is Byte)
+        "0x${this.toHexString(HexFormat.UpperCase)}"
+    else if (this is UByte)
+        "0x${this.toHexString(HexFormat.UpperCase)}u"
+    else if (this is ByteArray)
+        "0x[ ${this.toHexString(HexFormat.UpperCase)} ]"
+
+    // Numbers
+    else if (this is UShort || this is UInt)
+        "${this}u"
+    else if (this is ULong)
+        "${this}UL"
+    else if (this is Float)
+        "${this}f"
+    else
+        toString()
+}

base/src/main/kotlin/de/staropensource/engine/base/extension/CollectionArray.kt

@@ -0,0 +1,124 @@
+/*
+ * STAROPENSOURCE ENGINE SOURCE FILE
+ * Copyright (c) 2024 The StarOpenSource Engine Authors
+ * Licensed under the GNU General Public License v3.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.staropensource.engine.base.extension
+
+/**
+ * Formats this [Collection] into a nice listing.
+ *
+ * Here's an example:
+ * ```plain
+ * println(mutableListOf<Any?>( 69, "Hello World!", true, 'c' ).format())
+ * // Output: 69, "Hello World", true & 'c'
+ * ```
+ *
+ * @param itemSeparator  separator for items
+ * @param finalSeparator separator used instead of [itemSeparator] for the final two items
+ * @param quoteStrings   if to quote [String]s and [CharSequence]s in general using `""`
+ * @param quoteChars     if to quote [Char]s using `''`
+ * @since v1-alpha10
+ */
+fun Collection<*>.format(
+    itemSeparator: String = ", ",
+    finalSeparator: String = " & ",
+    quoteStrings: Boolean = true,
+    quoteChars: Boolean = true,
+): String = buildString {
+    // Don't do anything if collection
+    // is empty or only contains one item
+    if (this.isEmpty())
+        return@buildString
+    else if (this@format.size == 1) {
+        append(this@format.first())
+        return@buildString
+    }
+
+    // Iterate through items
+    var index: Int = 0
+    for (item: Any? in this@format) {
+        // Increase index
+        index++
+
+        // Append separator
+        if (!isEmpty())
+            append(if (index == this@format.size)
+                finalSeparator
+            else
+                itemSeparator
+            )
+
+        // Append item
+        append(item?.toStringType(
+            quoteStrings = quoteStrings,
+            quoteChars = quoteChars,
+        ))
+    }
+}
+
+/**
+ * Formats this [Array] into a nice listing.
+ *
+ * Here's an example:
+ * ```plain
+ * println(arrayOf<Any?>( 69, "Hello World!", true, 'c' ).format())
+ * // Output: 69, "Hello World", true & 'c'
+ * ```
+ *
+ * @param itemSeparator  separator for items
+ * @param finalSeparator separator used instead of [itemSeparator] for the final two items
+ * @param quoteStrings   if to quote [String]s and [CharSequence]s in general using `""`
+ * @param quoteChars     if to quote [Char]s using `''`
+ * @since v1-alpha10
+ */
+fun Array<*>.format(
+    itemSeparator: String = ", ",
+    finalSeparator: String = " & ",
+    quoteStrings: Boolean = true,
+    quoteChars: Boolean = true,
+): String = buildString {
+    // Don't do anything if collection
+    // is empty or only contains one item
+    if (this.isEmpty())
+        return@buildString
+    else if (this@format.size == 1) {
+        append(this@format.first())
+        return@buildString
+    }
+
+    // Iterate through items
+    var index: Int = 0
+    for (item: Any? in this@format) {
+        // Increase index
+        index++
+
+        // Append separator
+        if (!isEmpty())
+            append(if (index == this@format.size)
+                finalSeparator
+            else
+                itemSeparator
+            )
+
+        // Append item
+        append(item?.toStringType(
+            quoteStrings = quoteStrings,
+            quoteChars = quoteChars,
+        ))
+    }
+}

base/src/main/kotlin/de/staropensource/engine/base/extension/package-info.kt

@@ -0,0 +1,26 @@
+/*
+ * STAROPENSOURCE ENGINE SOURCE FILE
+ * Copyright (c) 2024 The StarOpenSource Engine Authors
+ * Licensed under the GNU General Public License v3.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Provides extension methods not found
+ * in the Kotlin standard library.
+ *
+ * @since v1-alpha10
+ */
+package de.staropensource.engine.base.extension