Kotlin ByteArray and UByteArray 'toChars' and 'toHexDigitsString' extension functions

(U)ByteArray extension functions.kt

```kotlin

const val HEX_LOWERCASE_DIGITS = "0123456789abcdef"
const val HEX_UPPERCASE_DIGITS = "0123456789ABCDEF"
const val HEX_DIGITS = "0123456789ABCDEFabcdef"


// ======================================================================================
// ByteArray and UByteArray 'toChars' extension functions
//


/**
 * returns a List<Char> representation of the given ByteArray,
 * where each Byte from the given [indices] range (both ends inclusive)
 * is treated as UByte and (via UShort) converted to Char
 */
@kotlin.ExperimentalUnsignedTypes
fun ByteArray.asUByteToChars(indices: IntRange): List<Char> {
    return this.sliceArray(indices)
        .asUByteArray()
        .map {
            Char(it.toUShort())
        }
}


/**
 * returns a List<Char> representation of the given ByteArray,
 * where each Byte from the given range (startIndex inclusive, endIndex exclusive)
 * is treated as UByte and (via UShort) converted to Char
 */
@kotlin.ExperimentalUnsignedTypes
fun ByteArray.asUByteToChars(startIndex: Int = 0, endIndex: Int = this.size): List<Char> {
    return this.asUByteToChars(startIndex until endIndex)
}


/**
 * returns a List<Char> representation of the given UByteArray,
 * where each UByte from the given [indices] range (both ends inclusive)
 * is (via UShort) converted to Char
 */
@kotlin.ExperimentalUnsignedTypes
fun UByteArray.toChars(indices: IntRange): List<Char> {
    return this.sliceArray(indices)
        .map {
            Char(it.toUShort())
        }
}


/**
 * returns a List<Char> representation of the given UByteArray,
 * where each UByte from the given range (startIndex inclusive, endIndex exclusive)
 * is (via UShort) converted to Char
 */
@kotlin.ExperimentalUnsignedTypes
fun UByteArray.toChars(startIndex: Int = 0, endIndex: Int = this.size): List<Char> {
    return this.toChars(startIndex until endIndex)
}



// ======================================================================================
// ByteArray and UByteArray 'toHexDigitsString' extension functions
//


/**
 * returns representation of the given ByteArray [indices] range (both ends inclusive)
 * as a String of 2-char substrings representing each Byte of the given ByteArray
 * as two hexadecimal digits (default lowercase)
 * all other parameters (along with their default values) except of 'indices'
 * are the same as in 'joinToString' function
 *
 * usage examples:
 * println(
 *      someByteArr.toHexDigitsString(
 *          separator=", 0x", prefix="(0x", postfix=")", transform=String::uppercase
 * ))
 * println(
 *      someByteArr.toHexDigitsString(
 *          separator="", prefix="|", postfix="|", transform=String::uppercase
 * ))
 */
@kotlin.ExperimentalUnsignedTypes
fun ByteArray.toHexDigitsString(
    indices: IntRange,
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = "",
    limit: Int = -1,
    truncated: CharSequence = "...",
    transform: ((String) -> CharSequence)? = null
): String {
    return this
        .asUByteArray()
        .toHexDigitsString(
            indices, separator, prefix, postfix, limit, truncated, transform
        )
}


/**
 * returns representation of the given ByteArray [indices] range (startIndex inclusive,
 * endIndex exclusive) as a String of 2-char substrings representing each Byte
 * of the given ByteArray as two hexadecimal digits (default lowercase)
 * all other parameters (along with their default values) except of 'startIndex'/'endIndex'
 * are the same as in 'joinToString' function
 *
 * usage examples:
 * println(
 *      someByteArr.toHexDigitsString(
 *          separator=", 0x", prefix="(0x", postfix=")", transform=String::uppercase
 *      )
 * )
 * println(
 *      someByteArr.toHexDigitsString(
 *          separator="~", prefix="|", postfix="|", transform=String::uppercase
 *      )
 * )
 */
@kotlin.ExperimentalUnsignedTypes
fun ByteArray.toHexDigitsString(
    startIndex: Int = 0,
    endIndex: Int = this.size,
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = "",
    limit: Int = -1,
    truncated: CharSequence = "...",
    transform: ((String) -> CharSequence)? = null
): String {
    return this.asUByteArray()
        .toHexDigitsString(
            startIndex until endIndex,
            separator, prefix, postfix, limit, truncated, transform
        )
}


/*
 * returns representation of the given UByteArray [indices] range (both ends inclusive)
 * as a String of 2-char substrings representing each UByte of the given UByteArray
 * as two hexadecimal digits (default lowercase)
 * all other parameters (along with their default values) except of 'indices'
 * are the same as in 'joinToString' function
 *
 * usage examples:
 * println(
 *      someUByteArr.toHexDigitsString(
 *          separator=", 0x", prefix="(0x", postfix=")", transform=String::uppercase
 * ))
 * println(
 *      someUByteArr.toHexDigitsString(
 *          separator="~", prefix="|", postfix="|", transform=String::uppercase
 * ))
 */
@kotlin.ExperimentalUnsignedTypes
fun UByteArray.toHexDigitsString(
    indices: IntRange,
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = "",
    limit: Int = -1,
    truncated: CharSequence = "...",
    transform: ((String) -> CharSequence)? = null
): String {
    return this.sliceArray(indices)
        .map {
            // the `"" +` part enforces the 'toString' conversion
            "" + HEX_LOWERCASE_DIGITS[((it and 0xF0u).toInt() ushr 4)] +
                    HEX_LOWERCASE_DIGITS[(it and 0x0Fu).toInt()]
        }
        .joinToString(separator, prefix, postfix, limit, truncated, transform)
}


/*
 * returns representation of the given UByteArray [indices] range (startIndex inclusive,
 * endIndex exclusive) as a String of 2-char substrings representing each UByte
 * of the given UByteArray as two hexadecimal digits (default lowercase)
 * all other parameters (along with their default values) except of 'startIndex'/'endIndex'
 * are the same as in 'joinToString' function
 *
 * usage examples:
 * println(
 *      someUByteArr.toHexDigitsString(
 *          separator=", 0x", prefix="(0x", postfix=")", transform=String::uppercase
 * ))
 * println(
 *      someUByteArr.toHexDigitsString(
 *          separator="~", prefix="|", postfix="|", transform=String::uppercase
 * ))
 */
@kotlin.ExperimentalUnsignedTypes
fun UByteArray.toHexDigitsString(
    startIndex: Int = 0,
    endIndex: Int = this.size,
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = "",
    limit: Int = -1,
    truncated: CharSequence = "...",
    transform: ((String) -> CharSequence)? = null
): String {
    return this.toHexDigitsString(
        startIndex until endIndex,
        separator, prefix, postfix, limit, truncated, transform
    )
}