Java String contains - Case-Sensitive Payment Filter Fail

contains() is in the top 20 Java String methods by frequency of use. It's also in the top 10 sources of NullPointerException in production Java code. Understanding the null contract and the case-sensitivity behaviour up front prevents the bugs I see repeatedly in code review.

How Java String.contains() Really Works — And Why It's Case-Sensitive

Java's String.contains(CharSequence s) returns true if and only if this string contains the specified sequence of char values. Under the hood, it delegates to String.indexOf(String) — a naive O(n*m) search in the worst case, though the JVM may intrinsify it for performance. There is no locale, no pattern, no flag: it's a straight character-by-character match.

Key properties: it's case-sensitive, null-hostile (throws NullPointerException if the argument is null), and operates on char values, not code points. That means supplementary characters (e.g., emoji) are represented as two surrogate chars — contains() will match them, but only if you pass the exact surrogate pair. The method does not normalize or fold case; 'A' and 'a' are distinct.

Use contains() when you need a simple, fast substring check and you control both the source and the search term — e.g., verifying an order ID prefix, checking a log level tag, or filtering a known set of tokens. Do not use it for user-facing search, natural language processing, or any scenario where case-insensitivity or locale-aware matching is required. In production payment systems, a case-sensitive filter on transaction codes has directly caused failed captures and duplicate charges.

contains() Usage, Case-Insensitive Variant, and Null Safety

String.contains() takes a CharSequence (which String implements) and returns true if the argument appears anywhere within the string. The check is case-sensitive. For case-insensitive contains, convert both strings to the same case first — but use Locale.ROOT or Locale.ENGLISH to avoid locale-specific case conversion bugs (the Turkish 'i' problem).

package io.thecodeforge.strings;

import java.util.Objects;

public class StringContainsExample {

    public static void main(String[] args) {
        String serviceName = "io.thecodeforge.payment.PaymentRetryService";

        // Basic contains — case-sensitive
        System.out.println(serviceName.contains("payment"));  // false — capital P
        System.out.println(serviceName.contains("Payment"));  // true
        System.out.println(serviceName.contains("Retry"));    // true

        // Case-insensitive contains
        String query = "PaymentRetry";
        boolean caseInsensitive =
            serviceName.toLowerCase(java.util.Locale.ROOT)
                       .contains(query.toLowerCase(java.util.Locale.ROOT));
        System.out.println("Case-insensitive: " + caseInsensitive); // true

        // Null safety — contains() throws NPE if called on null OR passed null
        String nullString = null;

        // Safe null check pattern
        boolean safeCheck = nullString != null && nullString.contains("Payment");
        System.out.println("Safe null check: " + safeCheck); // false, no NPE

        // Or use Objects utility
        boolean objectsCheck = Objects.toString(nullString, "").contains("Payment");
        System.out.println("Objects check: " + objectsCheck); // false

        // contains() vs indexOf() — when you need the position
        int position = serviceName.indexOf("PaymentRetry");
        System.out.println("Position: " + position); // 33 (0-indexed)
        // contains() returns true/false only; use indexOf() when you need index

        // Check if string contains any of multiple substrings
        String log = "ERROR: NullPointerException in PaymentService";
        boolean isError = log.contains("ERROR") || log.contains("FATAL");
        System.out.println("Is error: " + isError); // true
    }
}

Performance of contains() and Alternatives When Speed Matters

contains() internally calls indexOf(), which uses a naive O(nm) algorithm. For most one-off checks on small to medium strings, it's fast enough. But in tight loops over large strings (e.g., processing a 100K-character log line a thousand times), that O(nm) adds up. If you're checking for multiple patterns repeatedly, consider using Aho-Corasick or building a trie. For a single pattern, you can use indexOf() with a starting offset to search incrementally.

If you need to check the same large string for many substrings, cache the result after the first check or convert to a hash-based approach. Never assume contains() is cheap on a gigabyte-sized string.

package io.thecodeforge.performance;

public class ContainsPerformance {
    public static void main(String[] args) {
        String largeText = "abc".repeat(100_000); // 300K characters
        long start = System.nanoTime();
        // Repeated checks – don't do this in production
        for (int i = 0; i < 1000; i++) {
            boolean found = largeText.contains("xyz");
        }
        long end = System.nanoTime();
        System.out.println("1000 contains() calls: " + (end - start) / 1_000_000 + " ms");

        // Better: use indexOf to scan once and cache position, then check
        start = System.nanoTime();
        int position = largeText.indexOf("xyz");
        for (int i = 0; i < 1000; i++) {
            boolean found = position >= 0;
        }
        end = System.nanoTime();
        System.out.println("Cached indexOf check: " + (end - start) / 1_000_000 + " ms");
    }
}

contains() vs matches() vs indexOf() – Choosing the Right Tool

contains() treats its argument as a literal substring. If you need regex pattern matching, use String.matches() or Pattern.compile(). The matches() method checks if the entire string matches the pattern, not just a substring — so you'll need .* around the pattern for a containment check. indexOf() returns the index of the first occurrence, or -1 if not found; use it when you need the position.

Remember: contains() cannot handle regex metacharacters. If you pass "\\d+" to contains(), it looks for the literal backslash-d-plus, not a digit pattern. That's a common trap.

package io.thecodeforge.strings;

import java.util.regex.Pattern;

public class StringMethodComparison {
    public static void main(String[] args) {
        String data = "Order#12345 processed";

        // contains – literal substring
        System.out.println(data.contains("12345")); // true
        System.out.println(data.contains("\\d+")); // false (literal backslash)

        // matches – requires full string match
        System.out.println(data.matches(".*12345.*")); // true
        System.out.println(data.matches(".*\\\\d+.*")); // false – wrong pattern

        // Using Pattern for partial regex
        Pattern digitPattern = Pattern.compile("\\d+");
        System.out.println(digitPattern.matcher(data).find()); // true

        // indexOf – returns position
        int idx = data.indexOf("processed");
        System.out.println("Index of 'processed': " + idx); // 15
    }
}

Using contains() with CharSequence and StringBuilder

The parameter of contains() is CharSequence, not String. This means you can pass StringBuilder, StringBuffer, or any other CharSequence implementation directly – no need to call toString(). That saves an allocation and speeds things up when you're working with mutable strings.

However, note that the object on which you call contains() must be a CharSequence as well (usually a String). If you have a StringBuilder and want to check if it contains something, you must call contains() on the StringBuilder? Actually StringBuilder does not have a contains() method – it's only on String. So you'd need to convert the StringBuilder to a String first, or use indexOf() on the StringBuilder (StringBuilder has indexOf). But if you have a String and want to check if it contains a substring from a StringBuilder, you can pass the StringBuilder directly.

package io.thecodeforge.strings;

public class CharSequenceContains {
    public static void main(String[] args) {
        String source = "Hello World";
        StringBuilder sb = new StringBuilder("World");

        // You can pass a StringBuilder to contains()
        System.out.println(source.contains(sb)); // true

        // But StringBuilder itself does NOT have a contains() method
        // So you cannot do: sb.contains("World"); // compilation error
        // Use indexOf on StringBuilder instead
        int idx = sb.indexOf("World");
        System.out.println("StringBuilder.indexOf: " + idx); // 0
    }
}

contains() in Stream and Lambda Pipelines

contains() is commonly used in stream filters to keep only elements that contain a certain substring. It works naturally with lambdas: list.stream().filter(s -> s.contains("keyword")). But watch out — if any element in the stream is null, you'll get an NPE before the filter even processes the keyword. Always check for nulls first with filter(Objects::nonNull).

Also, remember that contains() is case-sensitive in streams too. If you need case-insensitive, chain toLowerCase(Locale.ROOT) on the element before calling contains().

package io.thecodeforge.streams;

import java.util.List;
import java.util.Objects;
import java.util.Locale;

public class StreamContains {
    public static void main(String[] args) {
        List<String> messages = List.of("INFO: startup complete", null, "ERROR: connection failed");

        // This will throw NPE because of the null element
        // List<String> errors = messages.stream()
        //     .filter(s -> s.contains("ERROR"))
        //     .collect(Collectors.toList());

        // Safe version with null check
        List<String> errors = messages.stream()
            .filter(Objects::nonNull)
            .filter(s -> s.contains("ERROR"))
            .toList();

        System.out.println(errors); // [ERROR: connection failed]

        // Case-insensitive version
        List<String> caseInsensitive = messages.stream()
            .filter(Objects::nonNull)
            .filter(s -> s.toLowerCase(Locale.ROOT).contains("error"))
            .toList();
        System.out.println(caseInsensitive); // [ERROR: connection failed]
    }
}

Syntax of contains() – The Signature That Hides a Trap

The method signature is dead simple – and that simplicity has shipped more NullPointerExceptions into production than most devs want to admit. public boolean contains(CharSequence sequence). It takes a CharSequence, not a String. That's the first clue this method was designed for interfaces, not just strings. The return is boolean. True if the sequence exists, false if not. No index, no position, no context.

Why does the parameter type matter? Because you can pass a StringBuilder, StringBuffer, or any custom CharSequence implementation. But under the hood, contains() calls indexOf(sequence.toString()). That .toString() call is your hidden cost. If you're passing a massive StringBuilder that hasn't been trimmed, you're paying for a full string conversion before the search even starts.

And yes – passing null throws a NullPointerException. Not silently returns false. The Javadoc is clear, but every week someone refactors a method to return null and their contains() check explodes. Defensive check your input or use a utility that handles null gracefully.

// io.thecodeforge — java tutorial

public class NullCheckExplosion {
    public static void main(String[] args) {
        String message = null;
        String userInput = "admin";
        
        // This throws NullPointerException at runtime
        // System.out.println(message.contains(userInput));
        
        // Safe pattern:
        if (message != null && message.contains(userInput)) {
            System.out.println("Found: " + userInput);
        } else {
            System.out.println("Input null or not found");
        }
    }
}

Implementation of contains() – What the JDK Actually Does

Let's look under the hood. Open String.java in your JDK, and you'll find this: return indexOf(sequence.toString()) > -1;. That's it. contains() is syntactic sugar over indexOf(). Knowing this changes how you read and write search logic.

indexOf() uses a naive brute-force search for small patterns or falls back to an optimized loop for longer texts. No Boyer-Moore, no KMP – you're getting O(n*m) worst-case complexity. For most strings under 10K characters, this is fine. For high-throughput parsing or large logs, it's a bottleneck.

Why should you care? Because contains() creates a temporary string from the CharSequence parameter. If you're calling contains() in a hot loop, you're generating garbage. Every. Single. Time. A StringBuilder that gets passed to contains() is fully converted to a String before the search. That allocation pressure hits GC, and your latency graph shows it.

If you're writing performance-sensitive code – batch processing, stream parsing, real-time systems – skip contains() and use indexOf() directly on the raw string. Or better yet, write a custom search that works on CharSequence without conversion.

// io.thecodeforge — java tutorial

public class HotLoopBenchmark {
    public static void main(String[] args) {
        String logEntry = "ERROR: connection timeout for host 10.0.0.1";
        long start = System.nanoTime();
        
        for (int i = 0; i < 100_000; i++) {
            // Avoid: allocates temporary String from CharSequence
            if (logEntry.contains("timeout")) {
                // process
            }
            // Better: direct indexOf on the String
            // if (logEntry.indexOf("timeout") > -1) {
            //     // process
            // }
        }
        
        long duration = System.nanoTime() - start;
        System.out.println("Duration (ns): " + duration);
    }
}