Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C++

std::basic_string::find — pesquisa de subcadeias e separadores obrigatórios

Encontra a primeira ocorrência a partir de uma posição, verifica `npos` e indica o comprimento do padrão se o buffer puder conter caracteres nulos no seu interior.

Versão: ISO C++23; implementation support may vary

Sintaxe

// ISO C++23; member declarations of std::basic_string<CharT, Traits, Allocator> in <string>
constexpr size_type find(const basic_string& str, size_type pos = 0) const noexcept;
constexpr size_type find(const CharT* s, size_type pos, size_type count) const;
constexpr size_type find(const CharT* s, size_type pos = 0) const;
constexpr size_type find(CharT ch, size_type pos = 0) const noexcept;
template<class T>
constexpr size_type find(const T& t, size_type pos = 0) const
    noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>);
// The template participates only if const T& is implicitly convertible to
// std::basic_string_view<CharT, Traits> but not to const CharT*.

std::basic_string::find é uma função membro const de <string>, também disponível em std::string. Devolve um índice do tipo size_type, contado a partir de zero: a primeira posição a partir de pos (0 por omissão) onde o padrão cabe e coincide na íntegra. Compara os elementos com Traits::eq. Em UTF-8 guardado num std::string, o índice conta bytes, não caracteres visíveis para o utilizador.

Se não houver correspondência, devolve npos, o maior valor de size_type, em vez de lançar uma exceção. Um padrão vazio coincide em pos se e só se pos <= size(); um padrão não vazio não pode coincidir se pos >= size(). Se o separador for obrigatório, verifica npos antes de indexar, extrair uma subcadeia ou calcular um deslocamento. O índice 0 é um resultado válido.

find(ch, pos) procura um único elemento CharT; find(str, pos) usa o comprimento total de um basic_string. find(p, pos) exige uma sequência terminada por um carácter nulo: Traits::length para no primeiro carácter nulo. find(p, pos, count) usa exatamente count elementos do padrão, incluindo os caracteres nulos internos. O segundo argumento é a posição inicial, não um comprimento; count não limita a cadeia onde se procura. Um intervalo de ponteiro inválido causa comportamento indefinido: verifica que count não excede o número de elementos que podem ser lidos a partir de p.

Desde C++17, a sobrecarga de template aceita const T& se for implicitamente convertível em std::basic_string_view<CharT, Traits>, mas não em const CharT*. Uma vista conserva o seu comprimento, mas não é proprietária dos dados. Os dados referenciados por uma vista ou por um ponteiro têm de permanecer válidos durante toda a chamada. Num buffer std::vector<char>, usa data() juntamente com size(); não pressuponhas um carácter nulo final.

Todas as sobrecargas são constexpr desde C++20. Em C++23, as de basic_string e CharT são noexcept, as de ponteiro não são declaradas noexcept e a de template só é noexcept se a conversão para a vista não puder lançar exceções. O suporte pode variar consoante a implementação.

Exemplos

#include <iostream>
#include <string>
#include <string_view>
#include <vector>

int main() {
    const std::string record{"A:B:\0=C", 7};
    const std::vector<char> separator{':', '\0', '='};

    std::cout << "C string: " << record.find(separator.data()) << '\n';

    const auto split = record.find(separator.data(), 0, separator.size());
    if (split == std::string::npos) {
        std::cout << "Missing required separator\n";
        return 1;
    }
    std::cout << "Counted separator: " << split << '\n';

    const std::string_view marker{separator.data(), separator.size()};
    const auto start = split + 1;
    const auto next = record.find(marker, start);
    std::cout << "From index " << start << ": ";
    if (next == std::string::npos) {
        std::cout << "not found\n";
    } else {
        std::cout << next << '\n';
    }
}

Resultado

C string: 1
Counted separator: 3
From index 4: not found

A chamada só com o ponteiro procura `:` e devolve `1`. A chamada com comprimento encontra o separador obrigatório completo `:\0=` no índice `3`. Procurar o mesmo padrão como vista a partir do índice `4` devolve `npos`.

Lições relacionadas

  • C++ · Lição 58 · Avançado · Versão: 3

Fontes