Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

Java String.intern(): canonical strings, identity, and contents

Learn why two strings with the same contents can be different objects, how `intern()` selects a canonical object, and what `length()` actually counts.

Version: Java SE 21

Syntax

Java SE 21 — java.lang.String

Primary API signature:
public String intern()

Supporting API signatures:
public String(String original)
public int length()
public boolean equals(Object anObject)

Usage (s and t are non-null String references):
String copy = new String(s);
String canonical = copy.intern();
int units = copy.length();
boolean sameContent = s.equals(t);
boolean sameObject = s == t;
boolean sameCanonicalObject = s.intern() == t.intern();

In Java SE 21, new String(s) calls the String(String) constructor of java.lang.String and creates a distinct object with the same contents as s. Strings are immutable, so assigning the existing reference is usually enough. Passing null to this overload throws NullPointerException.

String.length() and String.equals(Object) answer different questions. length() counts UTF-16 code units (char values), not code points or user-perceived characters. Equal lengths do not imply equal contents. For a non-null s, s.equals(t) returns true only if t is a String with the identical case-sensitive sequence of code units; a null argument returns false. Calling an instance method on a null reference throws NullPointerException. By contrast, == compares references: it is true for the same object or two null references.

String.intern() is an instance method. If the pool already has an entry equal according to equals(Object), intern() returns that entry's reference. Otherwise it adds and returns the receiver itself. String literals and the values of string-valued constant expressions are interned automatically. For non-null strings s and t, s.intern() == t.intern() is true exactly when s.equals(t) is true. Use the returned reference: the call changes neither the string nor the reference stored in your variable.

Use equals(Object), not ==, for ordinary content comparisons. Interning is not guaranteed to save memory or improve speed. Do not assume a particular lifetime for pool entries; measure costs and benefits on your actual workload before using interning as an optimization.

Examples

public class Main {
    public static void main(String[] args) {
        String literal = "A\uD83D\uDE00";
        String copy = new String(literal);

        System.out.println("length: " + copy.length());
        System.out.println("same contents: " + copy.equals(literal));
        System.out.println("same object: " + (copy == literal));

        String canonical = copy.intern();
        System.out.println("canonical is literal: " + (canonical == literal));
        System.out.println("copy is canonical: " + (copy == canonical));
    }
}

Result

length: 3
same contents: true
same object: false
canonical is literal: true
copy is canonical: false

`length: 3` counts one UTF-16 code unit for `A` and two for the emoji. The copy has the same contents but a different identity. `intern()` returns the existing literal's reference, while `copy` still refers to the new object.

Related lessons

  • Java · Lesson 49 · Advanced · Version: 2

Sources