How to Use Stream Distinct in Java: Simple Guide

In Java, you can use the distinct() method on a stream to remove duplicate elements based on their equals() method. It returns a new stream with only unique elements, preserving the original order.

Syntax

The distinct() method is called on a Stream object and returns a new stream with duplicates removed.

• stream.distinct(): Returns a stream with unique elements.

This method uses the equals() and hashCode() methods of the objects to determine duplicates.

java

Stream<T> distinctStream = originalStream.distinct();

Example

This example shows how to use distinct() to remove duplicate integers from a list and print the unique values.

java

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;

public class DistinctExample {
    public static void main(String[] args) {
        List<Integer> numbers = Arrays.asList(1, 2, 2, 3, 4, 4, 5);
        List<Integer> uniqueNumbers = numbers.stream()
                                             .distinct()
                                             .collect(Collectors.toList());
        System.out.println(uniqueNumbers);
    }
}

Output

[1, 2, 3, 4, 5]

Common Pitfalls

One common mistake is expecting distinct() to work on objects without properly overriding equals() and hashCode(). Without these, duplicates may not be detected correctly.

Also, distinct() does not modify the original collection; it returns a new stream with unique elements.

java

import java.util.*;
import java.util.stream.*;

class Person {
    String name;
    Person(String name) { this.name = name; }
    // equals and hashCode NOT overridden here
}

public class DistinctPitfall {
    public static void main(String[] args) {
        List<Person> people = Arrays.asList(new Person("Alice"), new Person("Alice"));
        List<Person> uniquePeople = people.stream().distinct().collect(Collectors.toList());
        System.out.println("Size without equals/hashCode: " + uniquePeople.size());
    }
}

// Correct way with equals and hashCode
class PersonFixed {
    String name;
    PersonFixed(String name) { this.name = name; }
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof PersonFixed)) return false;
        PersonFixed p = (PersonFixed) o;
        return name.equals(p.name);
    }
    @Override
    public int hashCode() {
        return name.hashCode();
    }
}

class DistinctFixed {
    public static void main(String[] args) {
        List<PersonFixed> people = Arrays.asList(new PersonFixed("Alice"), new PersonFixed("Alice"));
        List<PersonFixed> uniquePeople = people.stream().distinct().collect(Collectors.toList());
        System.out.println("Size with equals/hashCode: " + uniquePeople.size());
    }
}

Output

Size without equals/hashCode: 2
Size with equals/hashCode: 1

Quick Reference

• distinct(): Removes duplicates from a stream.
• Uses equals() and hashCode() to check duplicates.
• Returns a new stream; original data is unchanged.
• Works on any stream type (objects, primitives with boxed types).

Key Takeaways

Use distinct() on streams to get unique elements easily.

Ensure your objects override equals() and hashCode() for correct duplicate detection.

distinct() returns a new stream and does not change the original collection.

It preserves the order of the first occurrence of elements.

Works with any stream, including lists of objects or primitive wrappers.