Java Collection retainAll() Method

In Java, the retainAll() method of Java Collection retains or keeps only those elements present inside the collection which is given as an argument to the function.

Syntax for retainAll() method:

boolean retainAll(Collection<?> c);

Parameters: c is the collection containing elements retained or kept by the calling collection.

Return Type:

It returns a boolean value. It returns true if the calling collection is modified(i.e. any of the elements is removed) and returns false if no elements were removed.

Exception:

• Null Pointer Exception: If this collection is null or it holds one or more elements as null and invoked collection does not allow null elements.

• UnsupportedOperationException: If the retainAll() method is not supported by the collection.

• ClassCastException: If the elements are not mutually comparable(i.e. you have a mix of different object types), this exception can occur when trying to compare the elements.

Examples of Collection retainAll() Method:

The retainAll() method modifies the calling collection and removes those elements that are not present inside the collection passed as an argument to the function. Essentially, it retains or keeps only those elements that are common between two collections.

Explanation:

1. For each element in the calling collection, it checks whether it exists in the collection c(collection passed as an argument).
2. If any element is found in collection c, then it retains the element in the collection.
3. If any element is not found in collection c, then it removes the element from the calling collection.
4. After the whole process is done, the calling collection remains with only those elements that are common between the two collection.
5. Lastly, if the calling collection is modified then it returns true otherwise it returns false.

Example of Java Collection retainAll()

Example 1:

Below is the implementation of the above method:

Java

import java.util.ArrayList;
import java.io.*;

class GFG {
    public static void main (String[] args) {
        ArrayList<Integer> list1 = new ArrayList<Integer>();
        list1.add(1);
        list1.add(2);
        list1.add(3);
        list1.add(4);

        ArrayList<Integer> list2 = new ArrayList<Integer>();
        list2.add(2);
        list2.add(4);

        System.out.println("Original List:" + list1);

        System.out.println("List containing elements to be retained by the calling collection:" + list2);

        // Retains(or keep) only those elements which are specified inside the collection
        boolean modified = list1.retainAll(list2);

        System.out.println("Calling Collection Modified: " + modified);
        System.out.println("Original List(Elements Retained):" + list1);

    }
}

Output:

Original List:[1, 2, 3, 4]
List containing elements to be retained by the calling collection:[2, 4]
Calling Collection Modified: true
Original List(Elements Retained):[2, 4]

Example 2:

Java

import java.util.HashSet;
import java.io.*;

class GFG {
    public static void main (String[] args) {
       HashSet<String> hs1 = new HashSet<String>();
        hs1.add("Pen");
        hs1.add("Paper");
        hs1.add("Pencil");
        hs1.add("Rubber");

        HashSet<String> hs2 = new HashSet<String>();
        hs2.add("Pen");
        hs2.add("Paper");

        System.out.println("Original HashSet Collection:" + hs1);

        System.out.println("HashSet containing elements to be retained by the calling collection:" + hs2);

        // Retains(or keep) only those elements which are specified inside the collection
        boolean modified = hs1.retainAll(hs2);

        System.out.println("Calling Collection Modified: " + modified);
        System.out.println("Original HashSet Collection(Elements Retained):" + hs1);
    }
}

Output:

Original HashSet Collection:[Pen, Paper, Pencil, Rubber]
HashSet containing elements to be retained by the calling collection:[Pen, Paper]
Calling Collection Modified: true
Original HashSet Collection(Elements Retained):[Pen, Paper]

Time Complexity of the above method:

Time Complexity of retainAll(): O(N)
where N is the size of the larger of the two collections as it needs to iterate through both of the collections and look for which element to retain and which to remove.