Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

How to Use higherEntry() on a Java TreeMap

Learn how to use TreeMap.higherEntry() to find the next key-value entry in a sorted map, with practical Java examples, edge cases, and performance notes.

~6 min readJava
#TreeMap#SortedMap#Java Collections#NavigableMap
A Java TreeMap structure showing strict greater-than lookup with an arrow to the next entry.

Java's TreeMap.higherEntry() method returns the entry with the least key strictly greater than the key you provide. It is part of the NavigableMap interface and is useful for sorted lookups, scheduling, and range navigation. This article explains the method's syntax, behavior, edge cases, and performance compared with other lookup methods.

When you hold a TreeMap and need the first entry whose key is strictly greater than some given key, the higherEntry(K key) method is the direct tool. Unlike ceilingEntry, which includes an entry with an equal key, higherEntry skips equality and only returns a strictly greater entry. This distinction matters in scheduling, range queries, and any logic that depends on adjacency in a sorted key set.

Consider a typical scenario: you have a sorted map of timestamps to events, and you want to find the next scheduled event after a specific moment. Instead of iterating over entrySet() and filtering manually, higherEntry gives you the result in logarithmic time.

How higherEntry Works

higherEntry is defined on the NavigableMap interface, which TreeMap implements. The method signature is:

java
Map.Entry<K, V> higherEntry(K key)

It returns the key-value mapping associated with the least key strictly greater than the given key, or null if there is no such key. If the map is empty, it also returns null. The return type is Map.Entry<K, V>, which holds both the key and the value.

The time complexity is O(log n), because the map is based on a red-black tree. This means that even for maps with millions of entries, the lookup remains fast. For comparison, a linear scan through the entire map would be O(n) and becomes impractical for large datasets.

The method is read-only; it does not modify the map. If you only need the key, higherKey(K key) is a convenient alternative. If you need the value, use the returned entry's getValue() method or call get() on the map with that key.

Example: Finding the Next Entry

Let's look at a practical example. Suppose you manage a set of server nodes identified by integer IDs, and you want to find the next server with a higher ID than a given one.

java
import java.util.TreeMap; import java.util.Map; TreeMap<Integer, String> servers = new TreeMap<>(); servers.put(10, "alpha"); servers.put(20, "beta"); servers.put(30, "gamma"); Map.Entry<Integer, String> next = servers.higherEntry(15); if (next != null) { System.out.println("Next server: " + next.getKey() + " -> " + next.getValue()); } else { System.out.println("No higher entry"); }

In this code, higherEntry(15) returns the entry with key 20 and value "beta". If you query with 10, it returns 20 as well, because 10 is not considered greater than 10. If you query with 30, it returns null, since there is no key greater than 30.

The method is especially useful when you need to traverse the map in ascending order step by step. Instead of manually maintaining an iterator, you can start from a seed key and repeatedly call higherEntry with the previous key.

Comparing higherEntry, ceilingEntry, lowerEntry, and floorEntry

The NavigableMap interface provides four closely related lookup methods. Understanding their differences is essential for choosing the right one.

MethodKey conditionReturns
higherEntry(K)Key strictly greater than KEntry or null
ceilingEntry(K)Key greater than or equal to KEntry or null
lowerEntry(K)Key strictly less than KEntry or null
floorEntry(K)Key less than or equal to KEntry or null

For example, on the servers map above:

  • ceilingEntry(10) returns key 10.
  • higherEntry(10) returns key 20.
  • floorEntry(10) returns key 10.
  • lowerEntry(10) returns null, since no key is less than 10.

These methods are symmetric. If you need to find the predecessor or successor in a sorted collection, they give you direct access without manual iteration.

Handling Null and Missing Keys

If the key passed to higherEntry is null, the behavior depends on whether the map's comparator permits null keys. TreeMap by default uses natural ordering, which is not null-safe for most key types. If the map uses natural ordering and the key type is a standard class like Integer or String, passing null to higherEntry will throw a NullPointerException when the method compares the key.

If you are using a custom Comparator, it may accept null, but you must ensure the comparator handles null consistently. In practice, it is safer to avoid null keys and null lookup keys unless you have designed the comparator to support them.

Also note that the returned entry is a live entry from the map: calling setValue on it updates the value associated with that key in the map. For structural changes such as adding or removing keys, use the map's own methods.

Performance Characteristics and Alternatives

Because higherEntry runs in O(log n) time, it is appropriate for frequent lookups even on large maps. However, if you find yourself calling higherEntry repeatedly to iterate through all entries, consider using a NavigableMap's descending or ascending iteration methods instead. Those methods avoid repeated log-time lookups and are usually a better fit when processing many entries.

For example, to iterate from a starting key upward, you could use subMap(K fromKey, boolean, K toKey, boolean) or the Iterator from tailMap(). These approaches might be more efficient if you need to process many entries.

If the map is read-heavy and concurrent access is required, TreeMap is not thread-safe. You would need to wrap it with Collections.synchronizedSortedMap or use a ConcurrentSkipListMap, which also supports higherEntry because it implements NavigableMap. The concurrent version offers similar logarithmic performance with thread safety.

When Not to Use higherEntry

higherEntry is meant for single-step navigation, so it is not the best tool for returning several entries at once; a range view such as subMap or tailMap is more direct. It also only works on a sorted map. If you are starting from an unsorted Map, sort the keys or copy them into a sorted collection first.

Also, if your keys are floating-point values, remember that higherEntry uses the map's comparator or natural ordering. Choose a comparator whose notion of ordering matches your business logic; for example, Double.compare and Float.compare define specific handling for NaN and signed zero. The ordering should be consistent with equals whenever possible.

Edge Cases and Common Mistakes

One common mistake is assuming higherEntry includes the key itself. It does not. If you need to include the key, use ceilingEntry. In code that handles overlapping intervals or inclusive bounds, mixing these methods can lead to off-by-one errors.

Another mistake is forgetting to check for null return. When the given key is greater than or equal to the maximum key in the map, higherEntry returns null. Failing to check for null leads to NullPointerException when you try to call methods on the result.

Example of correct null handling:

java
Map.Entry<Integer, String> entry = servers.higherEntry(25); String value = (entry != null) ? entry.getValue() : "none";

If your application relies on higherEntry for critical scheduling, consider what happens when the map is empty. In that case, any key returns null. Your code should handle an empty map gracefully, perhaps by returning a default value or throwing a controlled exception.

Using a Custom Comparator with higherEntry

TreeMap accepts a Comparator in its constructor. If you use a comparator that reverses the natural order, higherEntry will still return the next key according to that comparator's definition. For a reverse-order map, the next entry is the one with a key that is considered greater according to the comparator, which might be a smaller numeric value.

Here is an example with a reverse-order comparator:

java
import java.util.Comparator; import java.util.TreeMap; TreeMap<Integer, String> reverseMap = new TreeMap<>(Comparator.reverseOrder()); reverseMap.put(1, "low"); reverseMap.put(5, "mid"); reverseMap.put(10, "high"); // Returns key 1, because 1 is higher in the reversed order than 5 System.out.println(reverseMap.higherEntry(5));

When you use a custom comparator, the keys must be compatible with that comparator's logic. The comparator must be consistent with equals; otherwise, the map's behavior becomes unpredictable. This is a general requirement for all SortedMap implementations.

higherEntry is a small but powerful method in the NavigableMap API. Used correctly, it lets you perform sorted lookups with little code, maintainable logic, and predictable performance. Its main caveats are null handling and the strictness of the comparison, both of which are easy to manage with a check for null and a clear understanding of which of the four navigation methods fits your bounds.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.