Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java ArrayList contains: Usage, Performance, and Alternatives

Learn how Java ArrayList.contains works, its linear scan behavior, null handling, and when to switch to HashSet for faster lookups.

~4 min readJava
#ArrayList#Java Collections#contains#HashSet
Illustration of a magnifying glass scanning a list of elements, representing the linear search behavior of ArrayList contains.

The contains method on java.util.ArrayList tells you whether a list contains a specified element. It works by scanning the list from the first element to the last and comparing each element with the argument. The behavior is simple and predictable, but the linear scan has performance implications when the list is large or when membership checks happen frequently.

How ArrayList.contains Works

The contains(Object o) method is declared by the Collection interface and implemented in ArrayList by iterating over the internal array and comparing each element with the argument. For a non-null argument, the comparison calls argument.equals(element) for each element. For a null argument, it uses == to look for a null element. The method therefore depends on the equals contract of the elements stored in the list.

java
List<String> names = new ArrayList<>(); names.add("Alice"); names.add("Bob"); if (names.contains("Alice")) { System.out.println("Found Alice"); }

In this example, contains calls "Alice".equals("Alice") on the first element and returns true immediately. If the element is not found, the scan completes without a match and false is returned.

The Role of equals and hashCode

ArrayList.contains uses equals to determine equality and does not use hashCode. This is different from HashSet or HashMap, which rely on hashCode to locate buckets. For ArrayList, the key requirement is that the elements' equals method is implemented correctly. If you store custom objects, you must override equals (and ideally hashCode) to define meaningful equality.

java
class Product { String sku; Product(String sku) { this.sku = sku; } @Override public boolean equals(Object obj) { if (this == obj) return true; if (!(obj instanceof Product)) return false; Product other = (Product) obj; return sku.equals(other.sku); } @Override public int hashCode() { return sku.hashCode(); } }

Without overriding equals, two Product instances with the same sku are not considered equal because Object.equals compares references. In that case, contains only returns true for the exact same object instance, which is rarely the intended behavior.

Null Handling in contains

ArrayList allows null elements, and contains handles them correctly. When you call contains(null), the implementation checks for a null element using == rather than equals. This is consistent with the Objects.equals semantics.

java
List<String> list = new ArrayList<>(); list.add(null); System.out.println(list.contains(null)); // true

If the list contains null and you call contains with a non-null object, the scan still calls equals on the null element as object.equals(null). A well-behaved equals implementation should return false for a null argument, so the scan continues without treating null as a match. If a custom equals does not handle null, a NullPointerException can occur.

Time Complexity and Performance

ArrayList.contains runs in O(n) time because it may need to examine every element. For small lists, this overhead is negligible. But if you call contains repeatedly on a large list, the cumulative cost becomes significant. For example, checking membership for each of m elements against a list of size n results in O(m * n) time.

java
List<String> largeList = new ArrayList<>(); // populate largeList... for (String item : manyItems) { if (largeList.contains(item)) { // process match } }

In such scenarios, a HashSet provides O(1) average lookup time because it uses hashCode to locate the element directly. The tradeoff is that HashSet does not preserve insertion order and requires proper hashCode implementations.

Comparing ArrayList and HashSet for contains

Collectioncontains Time ComplexityOrderingNull ElementsRequires hashCode
ArrayListO(n)Insertion orderYesNo
HashSetO(1) averageNo guaranteed orderYes (one null)Yes

Use ArrayList when you need to preserve order and the list is small, or when contains is called rarely. Use HashSet when membership testing is a primary operation and the collection size is large. If you need both order and fast lookups, consider LinkedHashSet, which maintains insertion order while providing O(1) contains.

Using containsAll for Bulk Checks

ArrayList also provides the containsAll(Collection<?> c) method from the Collection interface. This method returns true if all elements of the specified collection are present in the list. It is implemented by iterating over the argument collection and calling contains for each element, so its time complexity is O(n * m) where n is the list size and m is the argument size.

java
List<String> required = Arrays.asList("A", "B"); List<String> actual = Arrays.asList("A", "B", "C"); boolean hasAll = actual.containsAll(required); // true

If you frequently need to check whether a list contains all elements of another collection, consider using a HashSet for the larger collection to reduce the overall cost.

When to Avoid ArrayList.contains

Avoid using ArrayList.contains in tight loops or with large datasets where membership checks dominate. A common pattern is deduplication: building a list of unique items by checking contains before adding. This is O(n^2) for n items. Instead, use a HashSet to track seen items and then optionally convert to a list if order matters.

java
List<String> unique = new ArrayList<>(); Set<String> seen = new HashSet<>(); for (String item : input) { if (seen.add(item)) { unique.add(item); } }

Here, HashSet.add returns false if the item already exists, providing O(1) membership testing. This approach scales much better than using ArrayList.contains in a loop.

Compatibility and Version Notes

The behavior of ArrayList.contains has been stable for many Java versions. The implementation relies on equals and does not depend on hashCode. This means that even if a class has a broken hashCode (for example, always returning 0), ArrayList.contains still works correctly as long as equals is correct. This is a subtle advantage over HashSet, which would degrade to O(n) behavior in such cases.

No special configuration is required to use contains; it is available on any ArrayList instance.

For most applications, the decision between ArrayList and HashSet for membership tests comes down to the tradeoff between order preservation and lookup speed. Measure your actual usage patterns rather than assuming one is always better. If you need to maintain order and the list is small, ArrayList.contains is perfectly acceptable. If you are building a lookup index or performing frequent membership checks on a large dataset, switch to a HashSet or LinkedHashSet.

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.