What is the HashSet.retainAll() method in Java?

The HashSet.retainAll() method is present in the HashSet class inside the java.util package.

It is used to retain all the elements in a HashSet that are specified in the input collection.

Syntax

public boolean retainAll(Collection c)

This method throws NullPointerException if the input collection contains a null element and the HashSet does not permit null elements, or if the specified collection is null.

Example

Let’s understand with the help of some examples:

Suppose that a HashSet contains [1, 8, 5, 3, 0] and the input collection contains [0, 3, 1]. After using Hashset.retailAll(collection), the HashSet will only retain the elements of the collection. So, the HashSet contains [1, 0, 3].
Suppose that the HashSet contains [1, 6, 5, 9, 3, 2] and the collection is null. In this case, a NullPointerException is thrown.

Parameters

The HashSet.retainAll() method accepts one parameter:

Collection: This specifies the collection that needs to be retained within the HashSet.

Return value

The HashSet.retainAll() method returns true if the HashSet gets changed as a result of calling the method.

Code

Let’s have a look at the code.

import java.io.*;
import java.util.HashSet;
class Main 
{
  public static void main(String args[])
  {
    try 
    {
      HashSet<Integer> hash_set1 = new HashSet<Integer>();
      hash_set1.add(1);
      hash_set1.add(8);
      hash_set1.add(5);
      hash_set1.add(3);
      hash_set1.add(0);
      HashSet<Integer> hash_set2 = new HashSet<Integer>();
      hash_set2.add(8);
      hash_set2.add(0);
      hash_set2.add(3);
      hash_set2.add(5);
      System.out.println("hash_set1 before retainAll() implementation: "+hash_set1);
      System.out.println("Collection that needs to be retained: "+hash_set2);
      hash_set1.retainAll(hash_set2);
      System.out.println("hash_set1 after retainAll() implementation: "+hash_set1);
      System.out.println();
      HashSet<Integer> hash_set3 = null;
      System.out.println("hash_set2 before retainAll() implementation: "+hash_set2);
      System.out.println("Collection that needs to be retained: "+hash_set3);
      hash_set2.retainAll(hash_set3);
      System.out.println("hash_set2 after retainAll() implementation: "+hash_set2);
        
    } 
    catch(NullPointerException e) 
    {
      System.out.println("Exception thrown : " + e);
    } 
  }
}

Explanation:

In lines 1 and 2, we imported the required packages and classes.
In line 5, we created a Main class.
In line 7, we created a main() function.
In line 8, we created a try block.
In line 11, we declared a HashSet of Integer type, i.e., hash_set1.
From lines 11 to 15, we added the elements into the HashSet by using the HashSet.add() method.
In line 17, we declare a HashSet of Integer type, i.e., hash_set2.
From lines 18 to 21, we added the elements into the HashSet by using the HashSet.add() method.
In line 23, we displayed the HashSet before calling retainAll() with a message.
In line 24, we displayed the Collection that needs to be retained from HashSet with a message.
In line 26, we used the retainAll() function to retain the collection from the HashSet.
In line 27, we display the HashSet after calling retainAll() with a message.
In line 30, we declare a HashSet of Integer type, i.e., hash_set3, and assign it a null value.
In line 32, we display the HashSet before calling retainAll() with a message.
In line 33, we display the Collection that needs to be retained from HashSet with a message.
In line 35, we called the retainAll() function to retain the collection from the HashSet.
In line 36, we display the HashSet after calling retainAll() with a message.
In line 39, we made a catch block to encounter NullPointerException and display the exception when encountered in the try block.

This is how to use the HashSet.retainAll() function to retain all the elements in the HashSet specified in the collection from the HashSet.

Free Resources

License: Creative Commons-Attribution-ShareAlike 4.0 (CC-BY-SA 4.0)