Verifique se um texto contém uma substring

Ele retorna um resultado booleano e a posição, iniciada em zero, da primeira ocorrência, ou -1 quando não existe correspondência. Você pode preservar a distinção exata entre maiúsculas e minúsculas ou ignorá-la. O resultado é determinístico, fácil de testar e útil sempre que um fluxo precisa de uma condição rápida de busca sem expressões regulares ou correspondência aproximada.

Verifique uma substring com um resultado inequívoco

Informe o valor completo em text e a sequência que deseja localizar em substring. A resposta inclui contains, que é true quando há correspondência, e position, que identifica onde começa a primeira ocorrência. As posições são iniciadas em zero; portanto, uma substring encontrada logo no início tem posição 0. Quando ela não existe, o retorno é false e a posição é -1, mantendo a ausência diferente de uma ocorrência no começo. Essa combinação facilita tanto a leitura humana quanto a aplicação de uma condição por software. A operação procura uma substring literal e contínua. Espaços, pontuação e caracteres repetidos são tratados como texto comum, e não como padrões, então não é preciso escapar símbolos de expressão regular. Se a mesma substring ocorrer várias vezes, apenas a primeira posição será informada. Esse comportamento é especialmente útil em validações cujo objetivo é saber se um marcador esperado aparece e onde uma análise posterior poderia começar. Uma substring vazia é rejeitada porque toda string tecnicamente a contém, o que produziria um resultado surpreendente e pouco útil.

Escolha se as letras maiúsculas devem fazer diferença

A opção case_sensitive usa true como padrão. Nesse modo, letras maiúsculas e minúsculas precisam coincidir exatamente: procurar “Ready” não encontra “ready”. A correspondência exata é adequada para identificadores, marcadores de protocolo, códigos de produto e conteúdos em que a capitalização tem significado. Defina a opção como false quando você quiser uma verificação textual prática que considere essas variantes equivalentes, como ao procurar uma palavra de status em observações digitadas por usuários ou conferir se um título contém uma frase. O modo sem distinção normaliza de maneira consistente o texto de origem e a substring antes de localizar a primeira ocorrência, enquanto a posição retornada continua se referindo ao texto original. A capacidade não remove espaços nas extremidades nem altera a pontuação, portanto esses elementos permanecem significativos. Ela também não faz equivalência de acentos, radicalização, transliteração, comparação aproximada ou detecção de palavra inteira. Por exemplo, a busca por “cat” pode encontrar as três primeiras letras de “catalog”. Regras restritas mantêm cada resultado reproduzível e evitam pressupostos linguísticos silenciosos.

Use a posição com segurança em fluxos de validação

Um fluxo típico envia um valor candidato, verifica contains e escolhe um caminho sem precisar interpretar o campo numérico. Quando existe correspondência, position pode apoiar diagnósticos, prévias ou uma etapa posterior de análise. Por exemplo, uma rotina de importação pode confirmar que um cabeçalho inclui um token obrigatório e registrar onde ele começa; um teste pode verificar se um texto gerado contém uma frase aprovada; ou uma ferramenta de suporte pode detectar um marcador conhecido em uma linha de log colada. Sempre trate a posição retornada como um índice de string do JavaScript, medido em unidades de código UTF-16. Em textos latinos comuns, isso corresponde à contagem habitual de caracteres, mas alguns emojis e símbolos Unicode menos frequentes ocupam duas unidades. A capacidade retorna deliberadamente o índice nativo da plataforma para manter navegador e API idênticos e permitir o uso direto com métodos de recorte do JavaScript. Esta é uma busca literal, não um higienizador de segurança nem um classificador de conteúdo. Valide a estrutura separadamente para formatos sensíveis e use um analisador específico quando limites, escapes ou múltiplas ocorrências forem importantes.