Java HashMap putIfAbsent()

In this guide, you will learn about the HashMap putIfAbsent() method in Java programming and how to use it with an example.

1. HashMap putIfAbsent() Method Overview


The putIfAbsent() method of the HashMap class in Java is used to insert a specific key-value pair into the map only if the specified key is not already associated with a value (or the key is associated with null). If the map already contains the key, the existing value is retained and not replaced by the new value. The method returns the current (existing or computed) value associated with the key, or null if absent.


public V putIfAbsent(K key, V value)


- key: The key with which the specified value is to be associated.

- value: The value to be associated with the specified key.

Key Points:

- The putIfAbsent() method will insert the key-value pair only if the key is not already present in the map, or is associated with null.

- If the key is already present, the method will not modify the map and will return the current value associated with the key.

- If the key is not present, the method will add the key-value pair to the map and return null.

- The method allows storing null values and null keys in the HashMap.

2. HashMap putIfAbsent() Method Example

import java.util.HashMap;

public class HashMapPutIfAbsentExample {

    public static void main(String[] args) {
        HashMap<String, String> capitalMap = new HashMap<>();

        // Putting some key-value pairs in the HashMap
        capitalMap.put("USA", "Washington DC");
        capitalMap.put("Germany", "Berlin");

        // Printing the original HashMap
        System.out.println("Original HashMap: " + capitalMap);

        // Using putIfAbsent() - Key already exists
        String returnedValue1 = capitalMap.putIfAbsent("USA", "New York");
        System.out.println("Returned Value (USA): " + returnedValue1);

        // Using putIfAbsent() - Key does not exist
        String returnedValue2 = capitalMap.putIfAbsent("France", "Paris");
        System.out.println("Returned Value (France): " + returnedValue2);

        // Printing the updated HashMap
        System.out.println("Updated HashMap: " + capitalMap);


Original HashMap: {USA=Washington DC, Germany=Berlin}
Returned Value (USA): Washington DC
Returned Value (France): null
Updated HashMap: {USA=Washington DC, Germany=Berlin, France=Paris}


In this example, we initially have a HashMap with some key-value pairs. 

We then use the putIfAbsent() method with a key that already exists in the map ("USA") and with a key that does not exist in the map ("France"). When the key already exists, the method returns the current value associated with the key and does not modify the map. When the key does not exist, the method inserts the new key-value pair and returns null

The output demonstrates the state of the HashMap before and after using the putIfAbsent() method, and the values returned by the method.