Como Verificar se uma String Java Contém uma Substring

Verificar se uma String aparece dentro de outra é uma das tarefas de texto mais comuns em Java. A ferramenta certa depende do que você realmente precisa: uma resposta simples de sim/não, a posição da correspondência, uma verificação ancorada no início ou no fim, ou um padrão flexível. Este capítulo percorre cada abordagem idiomática e quando utilizá-la.

O padrão: `String.contains`

Quando você precisa apenas de um boolean — "esse fragmento está aqui ou não?" — contains é a escolha mais clara:

String text = "The quick brown fox";
boolean hasFox = text.contains("fox");   // true
boolean hasCat = text.contains("cat");   // false

contains aceita qualquer CharSequence (como String, StringBuilder, etc.) e retorna true se o argumento ocorrer em qualquer posição da string. É case-sensitive: text.contains("FOX") é false. Um caso especial importante a lembrar — a string vazia está contida em toda string, portanto text.contains("") é sempre true.

Quando você precisa da posição: `indexOf`

contains é implementado internamente sobre indexOf. Se você precisa saber onde uma correspondência começa (ou quer varrer repetições), chame indexOf diretamente:

String text = "The quick brown fox";
int at = text.indexOf("brown");   // 10
int no = text.indexOf("bird");    // -1

indexOf retorna o índice baseado em zero da primeira correspondência, ou -1 quando a substring está ausente. O idioma clássico de pertencimento é text.indexOf("brown") >= 0, que é equivalente a contains, mas também fornece a posição gratuitamente. Há também lastIndexOf para buscar a partir do final, e uma sobrecarga que aceita um deslocamento inicial para encontrar correspondências subsequentes em um laço.

Verificações ancoradas: `startsWith` e `endsWith`

Se você se importa especificamente com o início ou o fim de uma string — extensões de arquivo, prefixos de URL, esquemas de protocolo — startsWith e endsWith expressam a intenção diretamente e ficam mais legíveis do que fatiar:

String file = "report.pdf";
boolean isPdf  = file.endsWith(".pdf");      // true
boolean isHttp = "https://w3docs.com".startsWith("https://"); // true

Esses métodos são mais rápidos e mais claros do que indexOf(prefix) == 0, pois param de comparar assim que um caractere difere e nunca varrem a string inteira.

Comparação sem diferenciação de maiúsculas e correspondência por padrão

contains não possui uma sobrecarga sem diferenciação de maiúsculas e minúsculas. A correção mais simples é normalizar os dois lados:

boolean ci = text.toLowerCase().contains("FOX".toLowerCase()); // true

Para mais do que um fragmento literal — alternativas, curingas, limites de palavras — use uma expressão regular. Pattern.compile(...).matcher(text).find() retorna true se o padrão corresponder em qualquer lugar, e CASE_INSENSITIVE lida com maiúsculas e minúsculas sem alocar cópias em minúsculas:

import java.util.regex.Pattern;
boolean found = Pattern.compile("fox", Pattern.CASE_INSENSITIVE)
                       .matcher(text).find();

Abordagem	Retorna	Use quando
`contains`	`boolean`	Pertencimento simples, texto literal
`indexOf`	`int` (posição, ou `-1`)	Você precisa saber onde está a correspondência
`startsWith` / `endsWith`	`boolean`	Ancorado no início ou no fim
`Pattern.find`	`boolean`	Padrões, alternativas, sem distinção de maiúsculas

Um exemplo prático

Este programa executa as quatro abordagens lado a lado em uma frase, incluindo o problema de sensibilidade a maiúsculas e o caso especial da string vazia.

java— editable, runs on the server

public class CheckSubstring {
  public static void main(String[] args) {
    String text = "The quick brown fox jumps over the lazy dog";

// contains(): the simplest yes/no membership test
    System.out.println("contains 'brown'   : " + text.contains("brown"));
    System.out.println("contains 'cat'     : " + text.contains("cat"));

// contains is case-sensitive
    System.out.println("contains 'FOX'     : " + text.contains("FOX"));

// case-insensitive: normalise both sides first
    boolean ci = text.toLowerCase().contains("FOX".toLowerCase());
    System.out.println("contains 'FOX' (ci): " + ci);

// indexOf(): position, or -1 when absent
    System.out.println("indexOf 'fox'      : " + text.indexOf("fox"));
    System.out.println("indexOf 'bird'     : " + text.indexOf("bird"));

// startsWith / endsWith: anchored checks
    System.out.println("startsWith 'The'   : " + text.startsWith("The"));
    System.out.println("endsWith 'dog'     : " + text.endsWith("dog"));

// empty string is always contained
    System.out.println("contains ''        : " + text.contains(""));
  }
}

O que aprender com a execução:

contains "brown" imprime true e contains "cat" imprime false — contains é o teste direto de pertencimento boolean para texto literal.
contains "FOX" imprime false mesmo que a palavra "fox" esteja presente, provando que contains é case-sensitive; a linha normalizada contains "FOX" (ci) imprime true.
indexOf "fox" imprime 16, a posição inicial baseada em zero da correspondência, enquanto indexOf "bird" imprime -1 para sinalizar "não encontrado" — esse -1 é o sentinela contra o qual você testa.
startsWith "The" e endsWith "dog" ambos imprimem true, mostrando as verificações ancoradas lendo o início e o fim da frase.
contains "" imprime true, o lembrete de que toda string contém a string vazia — proteja-se contra entradas vazias se isso puder ser um bug.

Tópicos relacionados

Java Strings — a base para todo método nesta página.
Java String Methods — a referência completa de contains, indexOf, startsWith e afins.
How to Compare Strings in Java — igualdade e ordenação, o próximo passo natural após o pertencimento.
Java Regex: Pattern and Matcher — aprofunde-se na abordagem baseada em padrões mostrada acima.

Prática

O que text.indexOf('bird') retorna quando 'bird' não está presente na string text?

-10nullLança uma StringIndexOutOfBoundsException

O padrão: String.contains

Quando você precisa da posição: indexOf

Verificações ancoradas: startsWith e endsWith