Java String contentEquals() Method

What You’ll Learn

The contentEquals() method compares a String with any CharSequence—such as another String, a StringBuilder, or a StringBuffer—by character content rather than object identity. It returns true or false.

Definition and Usage

In Java, contentEquals(CharSequence cs) is defined on java.lang.String. It walks both sequences character by character and returns true only when every character and the total length match.

This method shines when you accumulate text in a StringBuilder or StringBuffer and need to verify it matches an expected String. You can compare directly without calling builder.toString() first.

📝 Syntax

The contentEquals() method is declared in the String class:

public boolean contentEquals(CharSequence cs)

Parameters

• cs — the character sequence to compare against. Must not be null.

Return Value

Returns true if both sequences contain the same characters in the same order and have the same length; otherwise false.

Exceptions

Throws NullPointerException if cs is null.

Examples Gallery

These programs run in Java 8+. They show matching content with StringBuilder, failed comparisons, case rules, StringBuffer, and how contentEquals() differs from equals().

public class ContentEqualsExample {
    public static void main(String[] args) {
        String str = "Hello, World!";
        StringBuilder builder = new StringBuilder("Hello, World!");

        boolean result = str.contentEquals(builder);

        if (result) {
            System.out.println("The contents are equal.");
        } else {
            System.out.println("The contents are not equal.");
        }
    }
}

The contents are equal.

public class NotEqualDemo {
    public static void main(String[] args) {
        String expected = "Java Programming";
        StringBuilder actual = new StringBuilder("Java Program");

        System.out.println("Match? " + expected.contentEquals(actual));
    }
}

Match? false

public class CaseSensitiveContent {
    public static void main(String[] args) {
        String label = "Learn Java Today";

        System.out.println("Equals 'Java'?  " + label.contentEquals("Java"));
        System.out.println("Equals 'java'?  " + label.contentEquals("java"));
    }
}

Equals 'Java'?  false
Equals 'java'?  false

public class BufferCompare {
    public static void main(String[] args) {
        String target = "codetofun";
        StringBuffer buffer = new StringBuffer();
        buffer.append("code").append("to").append("fun");

        System.out.println("contentEquals: " + target.contentEquals(buffer));
    }
}

contentEquals: true

public class ContentEqualsVsEquals {
    public static void main(String[] args) {
        String str = "Hello";
        StringBuilder builder = new StringBuilder("Hello");

        System.out.println("equals():         " + str.equals(builder));
        System.out.println("contentEquals():  " + str.contentEquals(builder));
        System.out.println("equals(toString): " + str.equals(builder.toString()));
    }
}

equals():         false
contentEquals():  true
equals(toString): true

🚀 Common Use Cases

• StringBuilder validation — confirm assembled output matches an expected constant or template.
• Parsing pipelines — compare a token read into a buffer against a known keyword.
• Test assertions — verify builder-based code produces the correct final text.
• Legacy StringBuffer code — compare thread-safe buffers without extra conversions.
• Protocol or config checks — match a built header or message against a required value.

📝 Notes

• contentEquals() compares full sequence content, not object references.
• It is case-sensitive. Normalize case or use equalsIgnoreCase() when both sides are String objects.
• It requires an exact match of the entire sequence—unlike contains(), which searches for a substring.
• The parameter type is CharSequence, so String, StringBuilder, and StringBuffer all work.
• Passing null throws NullPointerException—unlike some utility methods that accept null safely.

⚡ Optimization

contentEquals() is optimized for direct character-sequence comparison and avoids creating a temporary String from a StringBuilder when you would otherwise call builder.toString() only for comparison. For repeated checks in a hot loop, cache the boolean result. When both operands are already String instances, equals() is equally appropriate and idiomatic.

💡 Best Practices