Strings, UTF-8 e Texto em Rust

O manuseio de texto confunde mais novatos em Rust do que quase qualquer outra parte da linguagem, não porque a API seja incomumente grande, mas porque Rust se recusa a deixar você fingir que o texto é mais simples do que realmente é. Dois tipos (String e &str), um invariante de armazenamento (UTF-8 válido, sempre), e uma recusa categórica (sem indexação de caractere s[i]) contam toda a história - e cada uma dessas três decisões existe para prevenir uma classe específica de bug real que outras linguagens permitem silenciosamente.

Esta página é a âncora conceitual para a seção de strings e texto. Noções Básicas de Strings mostra a API do dia a dia; esta página explica por que a API é moldada da maneira que é - por que a propriedade divide String de &str da mesma forma que divide qualquer outra coleção Rust, o que a garantia UTF-8 realmente oferece, e por que a indexação por byte entra em pânico em vez de retornar silenciosamente algo errado.

Resumo

• String é um buffer de bytes próprio, expansível e alocado no heap, garantido como UTF-8 válido; &str é uma visualização emprestada de tal buffer, com a mesma garantia.
• Por que Importa: O texto tem largura variável em UTF-8 - um "caractere" pode ter de 1 a 4 bytes - então qualquer API que permitisse indexar por posição de caractere em O(1) estaria mentindo sobre o desempenho ou mentindo sobre a correção; Rust escolhe ser honesto em vez disso.
• Conceitos Chave: Codificação UTF-8, texto próprio vs. emprestado, limite de caractere, coerção Deref (String -> &str), comprimento de byte vs. contagem de caracteres.
• Quando Usar: &str para parâmetros de função e visualizações somente leitura (flexibilidade máxima, sem alocação); String quando você precisa possuir, construir ou mutar texto ao longo do tempo.
• Limitações / Compromissos: Nenhuma indexação de caractere O(1) é possível mantendo a garantia UTF-8; o manuseio correto de caracteres percebidos pelo usuário (emojis, marcas combinatórias) requer um crate além da biblioteca padrão.
• Tópicos Relacionados: propriedade e empréstimo, fatias (slices), coleções e iteradores, Cow para propriedade condicional.

Fundamentos

String e &str se dividem da mesma forma que Vec<T> e [T] (uma fatia) fazem, e pela mesma razão. String possui um buffer expansível alocado no heap - você pode adicionar a ele, possuí-lo, movê-lo, e ele é descartado quando sai do escopo. &str é uma visualização emprestada de uma sequência de bytes UTF-8, que pode residir dentro do buffer de um String, dentro do binário compilado (um literal &'static str), ou dentro de qualquer outra fonte de bytes que mantenha a garantia UTF-8. Todo String pode produzir uma visualização &str de si mesmo essencialmente de graça (através de Deref), mas nem todo &str tem um String por trás dele - um literal de string "hello" é um &'static str apontando diretamente para os dados somente leitura do programa, sem nenhum String proprietário em lugar nenhum.

Essa divisão é o motivo pelo qual assinaturas de função idiomáticas aceitam &str em vez de String ou &String: um parâmetro &str aceita um empréstimo de um String próprio, um literal de string, ou uma fatia de qualquer um deles, uniformemente, sem forçar o chamador a alocar apenas para chamar sua função. String como tipo de parâmetro é um sinal de que a função especificamente precisa possuir o texto (para armazená-lo, estendê-lo ou passá-lo adiante).

O segundo fato fundamental é a própria garantia UTF-8: o compilador e a biblioteca padrão de Rust tratam "isto é um str" e "isto é UTF-8 válido" como a mesma afirmação. Não há como construir um &str ou String contendo UTF-8 inválido através de código seguro - String::from_utf8 retorna um Result especificamente porque os bytes de entrada podem não ser válidos, e construí-lo a partir de bytes que você não validou requer uma função unsafe (from_utf8_unchecked) que coloca o ônus da prova sobre você.

Mecânicas e Interações

UTF-8 codifica cada valor escalar Unicode ("caractere", em sentido amplo) como um a quatro bytes, com a contagem de bytes determinada pelo ponto de código do caractere. Caracteres ASCII levam exatamente um byte e são byte a byte idênticos a texto ASCII puro; a maioria dos scripts não latinos e emojis levam de dois a quatro bytes. Essa variabilidade é toda a razão pela qual str não pode ser indexado por posição de caractere da maneira que um array pode:

  "Hello"   -> 5 bytes, 5 chars  (tudo ASCII, 1 byte cada)
  "Hello 🦀" -> 10 bytes, 7 chars (🦀 sozinho tem 4 bytes)

Um índice de array como arr[3] é rápido precisamente porque o tamanho do elemento é fixo, então o endereço do elemento n é uma simples multiplicação. O caractere n em uma string UTF-8 não tem um deslocamento fixo - encontrá-lo requer caminhar a partir do início (ou de um limite conhecido) e decodificar a largura de bytes de cada caractere ao longo do caminho, o que é uma operação O(n), não O(1). Em vez de oferecer um método chamado .char_at(n) que silenciosamente custa O(n) e atrai as pessoas a chamá-lo em um loop (o que silenciosamente se torna O(n^2)), Rust simplesmente não implementa Index<usize> para str de forma alguma. s[3] é um erro de compilação, não um erro de tempo de execução - a honestidade é imposta o mais cedo possível.

O que str suporta é a indexação por intervalo de bytes (&s[0..3]), que é O(1) exatamente da maneira que você esperaria que o fatiamento fosse, mas vem com uma obrigação: ambos os pontos finais do intervalo devem cair em um limite de caractere - o início de um caractere codificado, não o meio de um. Fatiar no meio de um caractere multibyte entra em pânico em tempo de execução, porque o resultado seria um str contendo uma sequência UTF-8 truncada e inválida, que o próprio invariante do tipo proíbe que exista.

fn safe_prefix(s: &str, max_bytes: usize) -> &str {
    if s.len() <= max_bytes { return s; }
    let mut end = max_bytes;
    // Caminha para trás a partir do deslocamento de byte solicitado até chegarmos a um
    // limite de caractere real - o fatiamento de `str` entra em pânico caso contrário, porque
    // uma sequência UTF-8 meio codificada violaria a garantia do tipo.
    while !s.is_char_boundary(end) { end -= 1; }
    &s[..end]
}

É por isso também que len() em um str retorna o comprimento de byte, não uma contagem de caracteres: o comprimento de byte é a única medida que é genuinamente O(1), pois é apenas o tamanho do buffer. Obter uma contagem de caracteres requer s.chars().count(), que percorre e decodifica toda a string - uma operação O(n) com um perfil de custo diferente que a API torna visível exigindo uma chamada de método explícita em vez de escondê-la atrás de .len().

Considerações Avançadas e Aplicações

Mesmo "contagem de caracteres" é um alvo escorregadio, porque o Unicode tem três noções comumente confundidas de "qual o comprimento deste texto": bytes (len()), valores escalares Unicode (chars().count()), e caracteres percebidos pelo usuário, ou clusters de grafemas (o que uma pessoa chamaria de "uma letra na tela"). Um único grafema como um emoji com um modificador de tom de pele, ou uma letra latina mais uma marca de acento combinatória, pode ser múltiplos chars e vários bytes a mais, tudo enquanto um humano o lê como um único caractere. A biblioteca padrão para deliberadamente em char (um valor escalar Unicode); a segmentação de grafemas é sensível a localidade e script de maneiras que inchariam std, então ela reside no crate unicode-segmentation em vez disso.

Truncar texto com segurança para exibição é um caso concreto onde tudo isso importa ao mesmo tempo: truncar por contagem de bytes arrisca fatiar no meio de um caractere (um pânico, ou saída corrompida com fatiamento unsafe); truncar por chars().count() ainda pode cortar um cluster de grafemas ao meio (separando uma sequência de emoji ou uma marca combinatória de sua letra base); apenas o truncamento ciente de grafemas corresponde ao que um usuário consideraria um "caractere inteiro" removido de forma limpa. Código de protocolo e formato de arquivo, por outro lado, quase sempre quer o comprimento de byte - ele precisa corresponder ao que está realmente na rede, não ao que um leitor humano contaria.

A interoperação com o sistema operacional é o outro lugar onde a garantia UTF-8 termina visivelmente: caminhos de arquivo e strings em nível de sistema operacional não são garantidos como UTF-8 válido em todas as plataformas (caminhos do Windows são baseados em UTF-16, e caminhos Unix são sequências de bytes arbitrárias), que é exatamente por que std::ffi::OsString e std::path::Path existem como tipos separados de String - eles intencionalmente não carregam o invariante UTF-8, porque não é uma garantia que o sistema operacional realmente fornece.

Conceitos Errôneos Comuns

• "String e &str são basicamente o mesmo tipo, um apenas tem um &" - Eles diferem da mesma forma que Vec<T> e [T] fazem: um possui um buffer expansível, o outro empresta uma visualização; entendê-los através dessa lente (não como "string mutável vs. imutável") esclarece a maioria das confusões sobre qual usar onde.
• "s.len() diz quantos caracteres há na string" - Ele diz o comprimento em bytes da codificação UTF-8, que é igual à contagem de caracteres apenas para texto puramente ASCII; qualquer coisa fora do ASCII precisa de chars().count(), e mesmo isso não é a contagem de caracteres percebida pelo usuário.
• "s[i] deveria funcionar como para arrays" - A indexação de array é rápida porque cada elemento tem o mesmo tamanho; caracteres UTF-8 têm de 1 a 4 bytes cada, então não há maneira O(1) de encontrar "o enésimo caractere", e Rust se recusa a oferecer uma API que finja o contrário.
• "Um String e as fatias &str retiradas dele são cópias separadas" - Um &str emprestado de um String aponta diretamente para o buffer existente no heap desse String; nenhuma cópia ocorre a menos que você explicitamente chame .to_string() ou .to_owned().
• "Qualquer sequência de bytes pode ser tratada como uma string se você apenas a converter" - String/str garantem UTF-8 válido como um invariante imposto pelo sistema de tipos; transformar bytes arbitrários em um deles ou os valida (String::from_utf8, que pode falhar) ou requer código unsafe afirmando uma garantia que você deve realmente cumprir.

FAQs

Relacionados

• Noções Básicas de Strings - sintaxe prática de String/&str, push_str e format!.
• UTF-8 e Indexação - fatiamento seguro, char_indices e is_char_boundary na prática.
• Chars, Bytes e Grafemas - as três maneiras de medir o comprimento do texto, incluindo clusters de grafemas.
• Manipulação de Strings - divisão, remoção de espaços em branco, substituição e construção de strings.
• OsString, Path e CStr - tipos de texto que deliberadamente não carregam a garantia UTF-8.

Versões do Stack: Esta página é conceitual e não está vinculada a uma versão específica do stack.