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
- Java SE 21 API — String(String original)
- Java SE 21 API — String.intern()
- Java SE 21 API — String.length()
- Java SE 21 API — String.equals(Object)
- Java Language Specification, Java SE 21 — §3.10.5 String Literals
- Java Language Specification, Java SE 21 — §15.21.3 Reference Equality Operators == and !=
- JDK 21 — The java Command: Using Source-File Mode to Launch Single-File Source-Code Programs