Kotlin Array.joinTo()

Kotlin Array.joinTo() function

In Kotlin, the Array.joinTo() function is used to create a single string by concatenating the elements of an array and appending the result to a given StringBuilder.

This function is similar to Array.joinToString(), but it allows you to specify the target StringBuilder where the result should be appended.

In this tutorial, we’ll explore the syntax of the joinTo() function and provide examples of its usage in Kotlin arrays.

Syntax

The syntax of the Array.joinTo() function is as follows:

fun <T, A : Appendable> Array<out T>.joinTo(
    buffer: A,
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = "",
    limit: Int = -1,
    truncated: CharSequence = "...",
    transform: ((T) -> CharSequence)? = null
): A

where

Parameter	Description
buffer	The target StringBuilder where the result will be appended.
separator	The separator between the elements. The default is “, “.
prefix	The string to be prefixed to the resulting string. The default is an empty string.
postfix	The string to be appended to the resulting string. The default is an empty string.
limit	The maximum number of elements to include in the result. If the number of elements exceeds this limit, the truncated string is appended. The default is -1, which means no limit.
truncated	The string to be appended if the number of elements exceeds the specified limit. The default is “…”.
transform	A function that transforms each element before joining. The default is null.

The joinTo() function appends the result to the specified StringBuilder and returns the same StringBuilder instance for further use if needed.

Examples for Array.joinTo() function

1. Basic Usage of Array.joinTo()

In this example, we’ll use joinTo() to concatenate the elements of an array into a StringBuilder with the default settings.

Kotlin Program

fun main() {
    val fruitsArray = arrayOf("apple", "banana", "kiwi", "mango")

    // Using joinTo() with default settings
    val resultBuilder = StringBuilder()
    fruitsArray.joinTo(resultBuilder)

    // Printing the original array and the result
    println("Fruits Array\n${fruitsArray.contentToString()}\n")
    println("Joined StringBuilder\n$resultBuilder")
}

Output

Fruits Array
[apple, banana, kiwi, mango]

Joined StringBuilder
apple, banana, kiwi, mango

2. Customizing Separator, Prefix, and Postfix

In this example, we’ll customize the separator, prefix, and postfix used in the joined StringBuilder.

Kotlin Program

fun main() {
    val fruitsArray = arrayOf("apple", "banana", "kiwi", "mango")

    // Using joinTo() with custom separator, prefix, and postfix
    val resultBuilder = StringBuilder()
    fruitsArray.joinTo(
        buffer = resultBuilder,
        separator = " | ",
        prefix = "[",
        postfix = "]"
    )

    // Printing the original array and the result
    println("Fruits Array\n${fruitsArray.contentToString()}\n")
    println("Joined StringBuilder\n$resultBuilder")
}

Output

Fruits Array
[apple, banana, kiwi, mango]

Joined StringBuilder
[apple | banana | kiwi | mango]

3. Limiting the Number of Elements

In this example, we’ll use joinTo() to limit the number of elements included in the result StringBuilder.

Kotlin Program

fun main() {
    val fruitsArray = arrayOf("apple", "banana", "kiwi", "mango")

    // Using joinTo() with a limit
    val resultBuilder = StringBuilder()
    fruitsArray.joinTo(
        buffer = resultBuilder,
        separator = ", ",
        limit = 2,
        truncated = "..."
    )

    // Printing the original array and the result
    println("Fruits Array\n${fruitsArray.contentToString()}\n")
    println("Joined StringBuilder\n$resultBuilder")
}

Output

Fruits Array
[apple, banana, kiwi, mango]

Joined StringBuilder
apple, banana, ...

4. Transforming Elements Before Joining

In this example, we’ll use joinTo() with a transformation function to uppercase each element before appending to the result StringBuilder.

Kotlin Program

fun main() {
    val fruitsArray = arrayOf("apple", "banana", "kiwi", "mango")

    // Using joinTo() with element transformation
    val resultBuilder = StringBuilder()
    fruitsArray.joinTo(
        buffer = resultBuilder,
        transform = { it.uppercase() }
    )

    // Printing the original array and the result
    println("Fruits Array\n${fruitsArray.contentToString()}\n")
    println("Joined StringBuilder\n$resultBuilder")
}

Output

Fruits Array
[apple, banana, kiwi, mango]

Joined StringBuilder
APPLE, BANANA, KIWI, MANGO

Summary

In this tutorial, we’ve covered the joinTo() function in Kotlin arrays, its syntax, and how to use it for creating customized string representations. Whether you need a simple concatenation or more complex formatting, joinTo() provides flexibility for joining array elements and appending the result to a specified StringBuilder.