Kotlin Sequence single Function

The single function in Kotlin is used to return the single element in a sequence that matches a given predicate. It is part of the Kotlin standard library and provides a way to find and retrieve the only element that satisfies a condition, or to check that there is exactly one element in the sequence.

Table of Contents

1. Introduction
2. single Function Syntax
3. Understanding single
4. Examples
   • Basic Usage
   • Finding a Single Element in a Sequence of Strings
   • Using single with Custom Objects
   • Chaining single with Other Functions
5. Real-World Use Case
6. Conclusion

Introduction

The single function allows you to find and retrieve the only element in a sequence that matches a given predicate. This is useful for scenarios where you need to ensure that there is exactly one element that satisfies a specific condition.

single Function Syntax

The syntax for the single function is as follows:

fun <T> Sequence<T>.single(): T
fun <T> Sequence<T>.single(predicate: (T) -> Boolean): T

Parameters:

• predicate: (Optional) A lambda function that defines the condition each element in the sequence must satisfy.

Returns:

• The single element that matches the given predicate, or the single element of the sequence if no predicate is provided.

Throws:

• NoSuchElementException if no element matches the predicate or if the sequence is empty and no predicate is provided.
• IllegalArgumentException if more than one element matches the predicate or if the sequence contains more than one element and no predicate is provided.

Understanding single

The single function works by iterating through the sequence and applying the predicate (if provided) to each element. It ensures that exactly one element satisfies the predicate. If no predicate is provided, it ensures that the sequence contains exactly one element.

Examples

Basic Usage

To demonstrate the basic usage of single, we will create a sequence of integers with a single element and retrieve that element.

Example

fun main() {
    val numbers = sequenceOf(42)
    val singleNumber = numbers.single()
    println(singleNumber) // Output: 42
}

Output:

42

Finding a Single Element in a Sequence of Strings

This example shows how to find the single string in a sequence that has exactly 5 characters.

Example

fun main() {
    val names = sequenceOf("Arjun", "Bhaskar", "Chitra", "Deepak", "Esha")
    val singleName = names.single { it.length == 5 }
    println(singleName) // Output: Arjun
}

Output:

Arjun

Using single with Custom Objects

You can use the single function to find the single element of custom objects that satisfies a specific condition.

Example

data class Person(val name: String, val age: Int)

fun main() {
    val people = sequenceOf(
        Person("Arjun", 25),
        Person("Bhaskar", 30),
        Person("Chitra", 22),
        Person("Deepak", 28),
        Person("Esha", 26)
    )
    val singlePerson = people.single { it.age == 30 }
    println(singlePerson) // Output: Person(name=Bhaskar, age=30)
}

Output:

Person(name=Bhaskar, age=30)

Chaining single with Other Functions

The single function can be chained with other sequence functions to perform more complex operations before retrieving the single element.

Example

fun main() {
    val numbers = sequenceOf(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
    val singleEvenNumberGreaterThanFive = numbers.filter { it > 5 }
                                                 .single { it % 2 == 0 }
    println(singleEvenNumberGreaterThanFive) // Output: 6
}

Output:

6

Real-World Use Case

Finding a Unique Product

In real-world applications, the single function can be used to find the unique product from a sequence of products based on a specific property.

Example

data class Product(val name: String, val id: Int)

fun main() {
    val products = sequenceOf(
        Product("Laptop", 1),
        Product("Smartphone", 2),
        Product("Tablet", 3),
        Product("Headphones", 4)
    )

    val singleProduct = products.single { it.id == 2 }
    println(singleProduct) // Output: Product(name=Smartphone, id=2)
}

Output:

Product(name=Smartphone, id=2)

Conclusion

The single function in Kotlin provides used for finding and retrieving the only element in a sequence that matches a given predicate. By understanding and using the single function, you can efficiently manage and process data in your Kotlin applications, ensuring that you can locate and use the unique elements that satisfy specific conditions according to your requirements.