Este é um exemplo de uma nota do instrutor. Nós as usaremos para adicionar informações complementares aos slides. Elas podem ser tanto pontos-chave que o instrutor deve cobrir quanto respostas a perguntas típicas que surgem em sala de aula.

• No Debian/Ubuntu, você também pode instalar o Cargo, o código-fonte do Rust e o formatador Rust com apt. Entretanto, isto lhe fornece uma versão desatualizada do Rust e pode levar a comportamentos inesperados. O comando seria:

  sudo apt install cargo rust-src rustfmt
  

Pontos chave:

• O Rust tem um cronograma de lançamento rápido com um novo lançamento saindo a cada seis semanas. Novos lançamentos mantêm compatibilidade com versões anteriores — além disso, eles habilitam novas funcionalidades.

• Existem três canais de lançamento: “stable”, “beta” e “nightly”.

• Novos recursos estão sendo testados em “nightly”, “beta” é o que se torna “stable” a cada seis semanas.

• Dependências também podem ser resolvidas a partir de registros alternativos, git, pastas, e outros mais.

• O Rust também tem edições: a edição atual é o Rust 2021. As edições anteriores foram o Rust 2015 e o Rust 2018.

  • As edições podem fazer alterações incompatíveis com versões anteriores da linguagem.

  • Para evitar quebra de código, as edições são opcionais: você seleciona a edição para o seu crate através do arquivo Cargo.toml.

  • Para evitar a divisão do ecossistema, os compiladores Rust podem misturar código escrito para diferentes edições.

  • Mencione que é muito raro usar o compilador diretamente, não através do cargo (a maioria dos usuários nunca o faz).

  • Pode valer a pena mencionar que o próprio Cargo é uma ferramenta extremamente poderosa e abrangente. Ele é capaz de muitos recursos avançados, incluindo, entre outros:

    • Estrutura do projeto/pacote
    • Espaços de trabalho
    • Dependências de desenvolvimento e gerenciamento/cache de dependência de tempo de execução
    • Criar scripts
    • Instalação global
    • Também é extensível com plugins de sub-comando (tais como cargo clippy).

  • Leia mais no Livro Oficial do Cargo

A maioria dos exemplos de código são editáveis, como mostrado acima. Alguns exemplos de código não são editáveis por vários motivos:

• Os playgrounds embutidos não conseguem executar testes unitários. Copie o código e cole no Playground real para demonstrar os testes unitários.

• Os playgrounds embutidos perdem seu estado no momento em que você navega para outra página! Esta é a razão pela qual os alunos devem resolver os exercícios usando uma instalação do Rust local ou via Playground real.

Tente encorajar os participantes do curso a instalar o Cargo e usar um editor local. Isso facilitará a vida deles, pois eles terão um ambiente normal de desenvolvimento.

Lembre aos alunos que:

• Eles devem fazer perguntas na hora, não as guarde para o fim.
• A aula é para ser interativa e as discussões são muito encorajadas!
  • Como instrutor, você deve tentar manter as discussões relevantes, ou seja, mantenha as discussões relacionadas a como o Rust faz as coisas versus alguma outra linguagem. Pode ser difícil encontrar o equilíbrio certo, mas procure permitir mais discussões, uma vez que elas engajam as pessoas muito mais do que uma comunicação unidirecional.
• As perguntas provavelmente farão com que falemos sobre coisas antes dos slides.
  • Isso está perfeitamente OK! A repetição é uma parte importante do aprendizado. Lembre-se que os slides são apenas um suporte e você está livre para ignorá-los quando quiser.

A ideia para o primeiro dia é mostrar as coisas “básicas” em Rust que devem ter paralelos imediatos em outras linguagens. As partes mais avançadas do Rust vêm nos dias subsequentes.

Se você estiver ensinando isso em uma sala de aula, este é um bom lugar para revisar a agenda. Observe que há um exercício no final de cada segmento, seguido por uma pausa. Planeje cobrir a solução do exercício após a pausa. Os horários listados aqui são uma sugestão para manter o curso no horário. Sinta-se à vontade para ser flexível e ajustar conforme necessário!

Rust se encaixa na mesma área que C++:

• Alta flexibilidade.
• Alto nível de controle.
• Pode ser reduzido para dispositivos com menor poder computacional, tais como microcontroladores.
• Não possui runtime ou coletor de lixo (garbage collection).
• Concentra-se em confiabilidade e segurança sem sacrificar o desempenho.

Não gaste muito tempo aqui. Todos esses pontos serão abordados em maior profundidade mais tarde.

Certifique-se de perguntar à classe com quais linguagens de programação eles têm experiência. Dependendo da resposta você pode destacar diferentes características do Rust:

• Experiência com C ou C++: Rust elimina toda uma classe de erros em tempo de execução através do verificador de empréstimos (borrow checker). Você obtém desempenho como em C e C++, mas sem os problemas de insegurança de memória. Além disso, você tem uma linguagem com funcionalidades modernas como correspondência de padrões e gerenciamento de dependência integrado.

• Experiência com Java, Go, Python, JavaScript…: Você tem a mesma segurança de memória como nessas linguagens, além de uma semelhança com linguagens de alto nível. Além disso você obtém desempenho rápido e previsível como C e C++ (sem coletor de lixo ou “garbage collector”) bem como acesso a hardware de baixo nível (caso você precise)

Conforme os alunos se dirigem para o intervalo, incentive-os a abrir o playground e experimentar um pouco. Incentive-os a manter a guia aberta e experimentar durante o resto do curso. Isso é particularmente útil para alunos avançados que desejam saber mais sobre as otimizações do Rust ou assembly gerado.

Este slide tenta deixar os alunos familiarizados com o código em Rust. Eles irão ver bastante conteúdo nos próximos quatro dias, então começamos devagar com algo familiar.

Pontos chave:

• Rust é muito parecido com outras linguagens na tradição C/C++/Java. É imperativo (não funcional) e não tenta reinventar as coisas, a menos que seja absolutamente necessário.

• Rust é moderno com suporte total para coisas como Unicode.

• Rust usa macros para situações em que você deseja ter um número variável de argumentos (sem sobrecarga de função).

• Macros “higiênicas” significam que elas não capturam acidentalmente identificadores do escopo em que são usadas. As macros em Rust são, na verdade, apenas parcialmente “higiênicas”.

• Rust é multi-paradigma. Por exemplo, ele possui funcionalidades de programação orientada à objetos poderosas, e, embora não seja uma linguagem funcional, inclui uma série de conceitos funcionais.

• Remova o comentário em x = 20 para demonstrar que as variáveis são imutáveis por padrão. Adicione a palavra-chave mut para permitir alterações.

• O i32 aqui é o tipo da variável. Isso deve ser conhecido em tempo de compilação, mas a inferência de tipo (abordada posteriormente) permite que o programador o omita em muitos casos.

Há algumas sintaxes que não são mostradas acima:

• Todos os sublinhados em números podem ser omitidos, eles são apenas para legibilidade. Por exemplo, 1_000 pode ser escrito como 1000 (ou 10_00), e 123_i64 pode ser escrito como 123i64.

Esta é a primeira vez que vemos uma função diferente de main, mas o significado deve ser claro: ela recebe três inteiros e retorna um inteiro. Funções serão abordadas com mais detalhes posteriormente.

Aritmética é muito semelhante a outras linguagens, com precedência semelhante.

E quanto ao estouro de inteiros? Em C e C++, o estouro de inteiros com sinal é realmente indefinido, e pode fazer coisas diferentes em plataformas ou compiladores diferentes. Em Rust, é definido.

Altere os i32 para i16 para ver um estouro de inteiro, que causa um pânico (verificado) em uma compilação de debug e um wrap-around em uma compilação de release. Existem outras opções, como overflowing, saturação e carrying. Estes são acessados com sintaxe de método, por exemplo, (a * b).saturating_add(b * c).saturating_add(c * a).

Na verdade, o compilador detectará o estouro de expressões constantes, é por isso que o exemplo requer uma função separada.

Este slide introduz strings. Tudo aqui será abordado com mais profundidade mais tarde, mas isso é o suficiente para que slides e exercícios subsequentes usem strings.

• UTF-8 inválido em uma string é UB, e isso não é permitido em Rust seguro.

• String é um tipo definido pelo usuário com um construtor (::new()) e métodos como s.push_str(..).

• O & em &str indica que esta é uma referência. Abordaremos referências mais tarde, então, por enquanto, pense em &str como uma unidade que significa “uma string somente leitura”.

• A linha comentada está indexando a string pela posição do byte. 12..13 não termina em um limite de caractere, então o programa entra em pânico. Ajuste para um intervalo que o faça, com base na mensagem de erro.

• Strings brutas permitem que você crie um valor &str com caracteres de escape desabilitados: r"\n" == "\\n". Você pode embutir aspas duplas utilizando uma quantidade igual de # em ambos os lados das aspas:

  fn main() {
      println!(r#"<a href="link.html">link</a>"#);
      println!("<a href=\"link.html\">link</a>");
  }

• Using {:?} is a convenient way to print array/vector/struct of values for debugging purposes, and it’s commonly used in code.

Este slide demonstra como o compilador Rust infere tipos com base em restrições dadas por declarações e usos de variáveis.

É muito importante enfatizar que variáveis declaradas assim não são de um tipo dinâmico “qualquer tipo” que possa armazenar quaisquer dados. O código de máquina gerado por tal declaração é idêntico à declaração explícita de um tipo. O compilador faz o trabalho para nós e nos ajuda a escrever um código mais conciso.

Quando nada restringe o tipo de um literal inteiro, Rust assume i32. Isso às vezes aparece como {integer} nas mensagens de erro. Da mesma forma, os literais de ponto flutuante assumem f64.

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // ERRO: nenhuma implementação para `{float} == {integer}`
}

Como if é uma expressão e deve ter um tipo específico, ambos os blocos de ramificação devem ter o mesmo tipo. Considere mostrar o que acontece se você adicionar um ; depois de "pequeno" no segundo exemplo.

Quando if é usado em uma expressão, a expressão deve ter um ; para separá-la da próxima instrução. Remova o ; antes de println! para ver o erro do compilador.

• Under the hood for loops use a concept called “iterators” to handle iterating over different kinds of ranges/collections. Iterators will be discussed in more detail later.
• Observe que o loop for itera apenas até 4. Mostre a sintaxe 1..=5 para um intervalo inclusivo.

• Observe que loop é a única construção de loop que retorna um valor não trivial . Isso ocorre porque é garantido que ele será executado pelo menos uma vez (diferente de loops while e for).

• Você pode mostrar como o valor do bloco muda alterando a última linha do bloco. Por exemplo, adicionar/remover um ponto e vírgula (;) ou usar um return.

• Mostre que o escopo de uma variável é limitado adicionando um b no bloco interno no último exemplo e, em seguida, tentando acessá-lo fora desse bloco.
• Shadowing é diferente da mutação, porque após a sobreposição (shadowing), os locais de memória de ambas as variáveis existem ao mesmo tempo. Ambas estão disponíveis com o mesmo nome, dependendo de onde você as usa no código.
• Uma variável sobreposta pode ter um tipo diferente.
• Shadowing (sobreposição) parece obscura a princípio, mas é conveniente para manter os valores após .unwrap().

• Os parâmetros de declaração são seguidos por um tipo (o inverso de algumas linguagens de programação) e, em seguida, um tipo de retorno.
• A última expressão em um corpo de uma função (ou qualquer bloco) torna-se o valor de retorno. Simplesmente omita o ; no final da expressão. A palavra-chave return pode ser usada para retorno antecipado, mas a forma “valor nu” é idiomática no final de uma função (refatore gcd para usar um return).
• Algumas funções não têm valor de retorno e retornam o ‘tipo unitário’, (). O compilador irá inferir isso se o tipo de retorno -> () for omitido.
• Sobrecarga não é suportada - cada função tem uma única implementação.
  • Sempre usa um número fixo de parâmetros. Argumentos padrão não são suportados. Macros podem ser usadas para suportar funções variádicas.
  • Sempre usa um único conjunto de tipos de parâmetros. Estes tipos podem ser genéricos, o que será abordado mais tarde.

A lição desta seção é que essas conveniências comuns existem e como usá-las. Por que elas são definidas como macros e no que elas se expandem não é especialmente crítico.

O curso não cobre a definição de macros, mas uma seção posterior descreverá o uso de macros derive (derivadas).

Pontos chave:

Matrizes:

• O valor do tipo matriz [T; N] comporta N elementos (constante em tempo de compilação) do mesmo tipo N. Note que o tamanho de uma matriz é parte do seu tipo, o que significa que [u8; 3] e [u8; 4] são considerados dois tipos diferentes. Slices (fatias), que têm um tamanho determinado em tempo de execução, são abordados mais tarde.

• Tente acessar um elemento de matriz fora dos limites. Os acessos a matrizes são verificados em tempo de execução. Rust geralmente pode otimizar essas verificações e elas podem ser evitadas usando Rust inseguro.

• Nós podemos usar literais para atribuir valores para matrizes.

• A macro println! pede a implementação de depuração com o parâmetro de formato ?: {} dá a saída padrão, {:?} dá a saída de depuração. Tipos como inteiros e strings implementam a saída padrão, mas matrizes implementam apenas a saída de depuração. Isso significa que devemos usar a saída de depuração aqui.

• Adicionando #, p.ex. {a:#?}, invoca um formato “pretty printing” (“impressão bonita”), que pode ser mais legível.

Tuplas:

• Assim como matrizes, tuplas têm tamanho fixo.

• Tuplas agrupam valores de diferentes tipos em um tipo composto.

• Campos de uma tupla podem ser acessados com um ponto e o índice do valor, p.ex. t.0, t.1.

• A tupla vazia () também é conhecida como “tipo unidade” (unit type). É tanto um tipo quanto o único valor válido desse tipo - ou seja, o tipo e seu valor são expressos como (). É usado para indicar, por exemplo, que uma função ou expressão não tem valor de retorno, como veremos em um slide futuro.

  • Você pode pensar nisso como um void, que talvez lhe seja familiar de outras linguagens de programação.

Esta funcionalidade usa o trait IntoIterator, mas ainda não a abordamos.

A macro assert_ne! é nova aqui. Existem também macros assert_eq! e assert!. Estes são sempre verificados enquanto as variantes apenas para debug como debug_assert! não compilam nada em compilações de release.

Pontos Chave:

• Você pode apontar como alguns caracteres específicos podem ser usados em um padrão

  • | como um or
  • .. pode expandir o quanto for necessário
  • 1..=5 representa um intervalo inclusivo
  • _ é um curinga

• Guardas de correspondência, como um recurso de sintaxe separado, são importantes e necessárias quando se quer expressar ideias mais complexas do que somente o padrão permitiria.

• Eles não são iguais à expressão if separada dentro do bloco de correspondência. Uma expressão if dentro do bloco de ramificação (depois de =>) acontece depois que a correspondência é selecionada. A falha na condição if dentro desse bloco não resultará em outras verificações de correspondência da expressão match original serem consideradas.

• A condição definida na guarda se aplica a todas as expressões em um padrão com um |.

• Crie um novo padrão usando _ para representar um elemento.
• Adicione mais valores à matriz.
• Aponte que .. vai expandir para levar em conta um número diferente de elementos.
• Mostre correspondência com a cauda usando os padrões [.., b] and [a@..,b]

• Uma referência é dita que “borrow” (empresta) o valor a que se refere, e este é um bom modelo para estudantes não familiarizados com ponteiros: o código pode usar a referência para acessar o valor, mas ainda é “owned” (propriedade) da variável original. O curso entrará em mais detalhes sobre ownership no dia 3.

• Referências são implementadas como ponteiros, e uma vantagem chave é que podem ser muito menores do que a coisa a que apontam. Os alunos familiarizados com C ou C++ reconhecerão referências como ponteiros. Partes posteriores do curso abordarão como o Rust impede os bugs de segurança de memória que vêm do uso de ponteiros brutos.

• O Rust não cria automaticamente referências para você - o & é sempre necessário.

• Rust will auto-dereference in some cases, in particular when invoking methods (try r.is_ascii()). There is no need for an -> operator like in C++.

• Neste exemplo, r é mutável para que possa ser reatribuído (r = &b). Observe que isso re-associa r, de modo que se refere a outra coisa. Isso é diferente do C++, onde a atribuição a uma referência altera o valor referenciado.

• Uma referência compartilhada não permite modificar o valor a que se refere, mesmo que esse valor seja mutável. Tente *r = 'X'.

• O Rust está rastreando os tempos de vida de todas as referências para garantir que elas vivam tempo suficiente. Referências pendentes não podem ocorrer em Rust seguro. x_axis retornaria uma referência a point, mas point será desalocado quando a função retornar, então isso não será compilado.

• Falaremos mais sobre empréstimos quando chegarmos à ownership.

Pontos chave:

• “Exclusivo” significa que apenas esta referência pode ser usada para acessar o valor. Nenhuma outra referência (compartilhada ou exclusiva) pode existir ao mesmo tempo, e o valor referenciado não pode ser acessado enquanto a referência exclusiva existir. Tente fazer um &point.0 ou alterar point.0 enquanto x_coord estiver ativo.

• Certifique-se de observar a diferença entre let mut x_coord: &i32 e let rx_coord: &mut i32. O primeiro representa uma referência mutável que pode ser ligada a diferentes valores, enquanto o segundo representa uma referência exclusiva a um valor mutável.

Pontos Chave:

• Structs funcionam como em C ou C++.
  • Como em C++, e ao contrário de C, nenhum typedef é necessário para definir um tipo.
  • Ao contrário do C++, não há herança entre structs.
• Este pode ser um bom momento para que as pessoas saibam que existem diferentes tipos de structs.
  • Structs de tamanho zero (por exemplo, struct Foo;) podem ser usadas ao implementar um trait em algum tipo, mas não possuem nenhum dado que você deseja armazenar nelas.
  • O próximo slide apresentará as structs de tuplas usadas quando o nome dos campos não são importantes.
• Se você já tiver variáveis com os nomes corretos, poderá criar a struct usando uma abreviação.
• The syntax ..avery allows us to copy the majority of the fields from the old struct without having to explicitly type it all out. It must always be the last element.

• Newtypes são uma ótima maneira de codificar informações adicionais sobre o valor em um tipo primitivo, por exemplo:
  • O número é medido em algumas unidades: Newtons no exemplo acima.
  • O valor passou por alguma validação quando foi criado, então não é preciso validá-lo novamente a cada uso: PhoneNumber(String) ou OddNumber(u32).
• Demonstre como somar um valor f64 em um valor do tipo Newtons acessando o campo único no newtype.
  • Geralmente, Rust não gosta de coisas implícitas, como unwrapping automático ou, por exemplo, usar booleanos como inteiros.
  • Sobrecarga de operadores é discutido no Dia 3 (genéricos).
• O examplo é uma referência sutil a falha do Orbitador Climático de Marte.

Pontos Chave:

• Enumerações permitem coletar um conjunto de valores em um tipo
• Direction é um tipo com variantes. Existem dois valores de Direction: Direction::Left e Direction::Right.
• PlayerMove é um tipo com três variantes. Além dos payloads, o Rust armazenará um discriminante para que ele saiba em tempo de execução qual variante está em um valor PlayerMove.
• Este pode ser um bom momento para comparar structs e enums:
  • Em ambos, você pode ter uma versão simples sem campos (unit struct, ou estrutura unitária) ou uma com diferentes tipos de campo (variant payloads ou cargas de variante).
  • Você pode até mesmo implementar as diferentes variantes de uma enum com structs separadas, mas elas não seriam do mesmo tipo, como seriam se todas fossem definidas em uma enum.
• O Rust usa espaço mínimo para armazenar o discriminante.

  • Se necessário, armazena um inteiro do menor tamanho necessário

  • If the allowed variant values do not cover all bit patterns, it will use invalid bit patterns to encode the discriminant (the “niche optimization”). For example, Option<&u8> stores either a pointer to an integer or NULL for the None variant.

  • É possível controlar o discriminante se necessário (p.ex., para compatibilidade com C):

    #[repr(u32)]
    enum Bar {
        A, // 0
        B = 10000,
        C, // 10001
    }
    
    fn main() {
        println!("A: {}", Bar::A as u32);
        println!("B: {}", Bar::B as u32);
        println!("C: {}", Bar::C as u32);
    }

    Sem repr, o tipo do discriminante usa 2 bytes, porque 10001 cabe em 2 bytes.

Mais para Explorar

O Rust tem várias otimizações que pode empregar para fazer com que as enums ocupem menos espaço.

• Otimização de ponteiro nulo: para alguns tipos, o Rust garante que size_of::<T>() é igual a size_of::<Option<T>>().

  Código de exemplo caso queira mostrar como a representação em bits pode ser na prática. É importante apontar que o compilador não oferece nenhuma garantia a respeito dessa representação, portanto isso é completamente inseguro.

  use std::mem::transmute;
  
  macro_rules! dbg_bits {
      ($e:expr, $bit_type:ty) => {
          println!("- {}: {:#x}", stringify!($e), transmute::<_, $bit_type>($e));
      };
  }
  
  fn main() {
      unsafe {
          println!("bool:");
          dbg_bits!(false, u8);
          dbg_bits!(true, u8);
  
          println!("Option<bool>:");
          dbg_bits!(None::<bool>, u8);
          dbg_bits!(Some(false), u8);
          dbg_bits!(Some(true), u8);
  
          println!("Option<Option<bool>>:");
          dbg_bits!(Some(Some(false)), u8);
          dbg_bits!(Some(Some(true)), u8);
          dbg_bits!(Some(None::<bool>), u8);
          dbg_bits!(None::<Option<bool>>, u8);
  
          println!("Option<&i32>:");
          dbg_bits!(None::<&i32>, usize);
          dbg_bits!(Some(&0i32), usize);
      }
  }

• Mencione que const se comporta semanticamente de maneira similar ao constexpr de C++.
• Por outro lado, static é muito mais similar a um const ou variável global mutável em C++.
• static fornece identidade de objeto: um endereço na memória e estado conforme exigido por tipos com mutabilidade interior tais como Mutex<T>.
• Não é muito comum que alguém precise de uma constante avaliada em tempo de execução, mas é útil e mais seguro do que usar uma variável estática.

Tabela de propriedades:

Mais para Explorar

Como variáveis estáticas (static) são acessíveis de qualquer thread, elas precisam ser Sync. A mutabilidade interior é possível através de um Mutex, atômico ou similar.

Dados locais da thread podem ser criados com a macro std::thread_local.

Programadores C reconhecerão isso como semelhante a um typedef.

Structs

• Modifique os valores em foo para corresponder com os outros padrões.
• Adicione um novo campo a Foo e faça mudanças nos padrões conforme necessário.
• A diferença entre uma captura (capture) e uma expressão constante pode ser difícil de perceber. Tente modificar o 2 no segundo braço para uma variável, e veja que, de forma sútil, não funciona. Mude para const e veja funcionando novamente.

Enums (Enumerações)

Pontos chave:

• A expressão if/else está retornando um enum que é posteriormente descompactado com um match.
• Você pode tentar adicionar uma terceira variante à definição de Enum e exibir os erros ao executar o código. Aponte os lugares onde seu código agora é “não exaustivo” e como o compilador tenta lhe dar dicas.
• Os valores nas variantes de uma enum só podem ser acessados após uma correspondência de padrão.
• Demonstre o que acontece quando a busca não abrange todas as possibilidades. Observe a vantagem que o compilador Rust fornece ao confirmar quando todos os casos são tratados.
• Salve o resultado de divide_in_two na variável result e faça uma correspondência de padrão (match) em um loop. Isso não irá compilar porque msg é consumido quando correspondido. Para corrigir, faça uma correspondência de padrão em &result ao invés de result. Isso fará com que msg seja uma referência, de forma que não será consumido. Essa “ergonomia de correspondência” apareceu no Rust 2018. Se você quiser suportar versões mais antigas do Rust, substitua msg por ref msg no padrão.

if-let

• Ao contrário de match, if let não precisa cobrir todas as ramificações. Isso pode torná-lo mais conciso do que match.
• Um uso comum é lidar com valores Some ao trabalhar-se com Option.
• Ao contrário de match, if let não suporta cláusulas de guarda para correspondência de padrões.

let-else

if-lets podem se acumular, como mostrado. A construção let-else permite o “achatamento” desse código aninhado. Reescreva a versão “estranha” para os alunos, para que eles possam ver a transformação.

A versão reescrita é:

#![allow(unused)]
fn main() {
fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("obteve None"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("obteve uma string vazia"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("não é um dígito hexadecimal"));
    };

    return Ok(digit);
}
}

while-let

• Ressalte que o loop while let continuará executando enquanto o valor corresponder ao padrão.
• Você pode reescrever o loop while let como um loop infinito com uma instrução if que é interrompido quando não houver mais nenhum valor para unwrap (desempacotar) para name.pop(). O while let fornece um atalho para o cenário acima.

Pontos Chave:

• Pode ser útil introduzir métodos comparando-os com funções.
  • Métodos são chamados em uma instância de um tipo (como struct ou enum), o primeiro parâmetro representa a instância como self.
  • Desenvolvedores podem optar por usar métodos para aproveitar a sintaxe do receptor do método e ajudar a mantê-los mais organizados. Usando métodos, podemos manter todo o código de implementação em um local previsível.
• Destaque o uso da palavra-chave self, um receptor de método.
  • Mostre que é um termo abreviado para self: Self e talvez mostre como o nome da struct também poderia ser usado.
  • Explique que Self é um alias de tipo para o tipo em que o bloco impl está e pode ser usado em qualquer outro lugar no bloco.
  • Observe como self é usado como outras structs e a notação de ponto pode ser usada para se referir a campos individuais.
  • Este pode ser um bom momento para demonstrar como &self difere de self modificando o código e tentando executar finish duas vezes.
  • Além das variantes de self, também existem tipos especiais de wrapper que podem ser tipos de receptores, como Box<Self>.

• Um trait define um número de métodos que os tipos devem ter para implementar o trait.

• In the “Generics” segment, next, we will see how to build functionality that is generic over all types implementing a trait.

• To implement Trait for Type, you use an impl Trait for Type { .. } block.

• Unlike Go interfaces, just having matching methods is not enough: a Cat type with a talk() method would not automatically satisfy Pet unless it is in an impl Pet block.

• Traits may provide default implementations of some methods. Default implementations can rely on all the methods of the trait. In this case, greet is provided, and relies on talk.

• Associated types are sometimes also called “output types”. The key observation is that the implementer, not the caller, chooses this type.

• Many standard library traits have associated types, including arithmetic operators and Iterator.

A derivação é implementada com macros e muitas crates fornecem macros de derivação úteis para adicionar funcionalidades úteis. Por exemplo, serde pode derivar suporte de serialização para uma struct usando #[derive(Serialize)].

Exercise: Generic Logger

Let’s design a simple logging utility, using a trait Logger with a log method. Code which might log its progress can then take an &impl Logger. In testing, this might put messages in the test logfile, while in a production build it would send messages to a log server.

However, the StderrLogger given below logs all messages, regardless of verbosity. Your task is to write a VerbosityFilter type that will ignore messages above a maximum verbosity.

This is a common pattern: a struct wrapping a trait implementation and implementing that same trait, adding behavior in the process. What other kinds of wrappers might be useful in a logging utility?

use std::fmt::Display;

pub trait Logger {
    /// Log a message at the given verbosity level.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("verbosity={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

// TODO: Define and implement `VerbosityFilter`.

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

Solução

use std::fmt::Display;

pub trait Logger {
    /// Log a message at the given verbosity level.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("verbosity={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "Uhoh");
}

/// Only log messages up to the given verbosity level.
struct VerbosityFilter<L: Logger> {
    max_verbosity: u8,
    inner: L,
}

impl<L: Logger> Logger for VerbosityFilter<L> {
    fn log(&self, verbosity: u8, message: impl Display) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

Genéricos (Generics)

This segment should take about 40 minutes. It contains:

Funções Genéricas

Rust suporta genéricos, o que permite abstrair algoritmos ou estruturas de dados (como ordenação ou uma árvore binária) sobre os tipos usados ou armazenados.

/// Pick `even` or `odd` depending on the value of `n`.
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("escolheu um número: {:?}", pick(97, 222, 333));
    println!("escolheu uma tupla: {:?}", pick(28, ("cachorro", 1), ("gato", 2)));
}

Tipos de Dados Genéricos

Você pode usar genéricos para abstrair o tipo concreto do campo:

#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn coords(&self) -> (&T, &T) {
        (&self.x, &self.y)
    }

    // fn set_x(&mut self, x: T)
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
    println!("{integer:?} e {float:?}");
    println!("coords: {:?}", integer.coords());
}

Trait Bounds (Limites de Trait)

Ao trabalhar com genéricos, muitas vezes você exigir que os tipos implementem algum trait para poder utilizar os métodos do trait.

Você consegue fazer isso com T:Trait ou impl Trait:

fn duplicate<T: Clone>(a: T) -> (T, T) {
    (a.clone(), a.clone())
}

// struct NotClonable;

fn main() {
    let foo = String::from("foo");
    let pair = duplicate(foo);
    println!("{pair:?}");
}

Trait impl

Semelhante aos limites de trait, a sintaxe do trait impl pode ser usada em argumentos de funções e em valores de retorno:

// Código simplificado para:
//   fn add_42_millions<T: Into<i32>>(x: T) -> i32 {
fn add_42_millions(x: impl Into<i32>) -> i32 {
    x.into() + 42_000_000
}

fn pair_of(x: u32) -> impl std::fmt::Debug {
    (x + 1, x - 1)
}

fn main() {
    let many = add_42_millions(42_i8);
    println!("{many}");
    let many_more = add_42_millions(10_000_000);
    println!("{many_more}");
    let debuggable = pair_of(27);
    println!("debuggable: {debuggable:?}");
}

Exercício: min Genérico

Neste exercício curto, você implementará uma função genérica min que determina o mínimo de dois valores, usando um trait LessThan.

trait LessThan {
    /// Retorna verdadeiro se self for menor que other.
    fn less_than(&self, other: &Self) -> bool;
}

#[derive(Debug, PartialEq, Eq, Clone, Copy)]
struct Citation {
    author: &'static str,
    year: u32,
}

impl LessThan for Citation {
    fn less_than(&self, other: &Self) -> bool {
        if self.author < other.author {
            true
        } else if self.author > other.author {
            false
        } else {
            self.year < other.year
        }
    }
}

// TODO: implemente a função `min` usada em `main`.

fn main() {
    let cit1 = Citation { author: "Shapiro", year: 2011 };
    let cit2 = Citation { author: "Baumann", year: 2010 };
    let cit3 = Citation { author: "Baumann", year: 2019 };
    debug_assert_eq!(min(cit1, cit2), cit2);
    debug_assert_eq!(min(cit2, cit3), cit2);
    debug_assert_eq!(min(cit1, cit3), cit3);
}

Solução

trait LessThan {
    /// Retorna verdadeiro se self for menor que other.
    fn less_than(&self, other: &Self) -> bool;
}

#[derive(Debug, PartialEq, Eq, Clone, Copy)]
struct Citation {
    author: &'static str,
    year: u32,
}

impl LessThan for Citation {
    fn less_than(&self, other: &Self) -> bool {
        if self.author < other.author {
            true
        } else if self.author > other.author {
            false
        } else {
            self.year < other.year
        }
    }
}

fn min<T: LessThan>(l: T, r: T) -> T {
    if l.less_than(&r) {
        l
    } else {
        r
    }
}

fn main() {
    let cit1 = Citation { author: "Shapiro", year: 2011 };
    let cit2 = Citation { author: "Baumann", year: 2010 };
    let cit3 = Citation { author: "Baumann", year: 2019 };
    debug_assert_eq!(min(cit1, cit2), cit2);
    debug_assert_eq!(min(cit2, cit3), cit2);
    debug_assert_eq!(min(cit1, cit3), cit3);
}

Bem-vindo de volta

Including 10 minute breaks, this session should take about 3 hours and 10 minutes. It contains:

Tipos da Biblioteca Padrão

This segment should take about 1 hour and 20 minutes. It contains:

Biblioteca Padrão

Rust vem com uma biblioteca padrão (standard library) que ajuda a estabelecer um conjunto de tipos comuns usados por bibliotecas e programas Rust. Dessa forma, duas bibliotecas podem trabalhar juntas sem problemas porque ambas usam o mesmo tipo String.

Na verdade, o Rust contém várias camadas de Biblioteca Padrão: core, alloc e std.

• core inclui os tipos e funções mais básicos que não dependem de libc, alocador ou até mesmo a presença de um sistema operacional.
• alloc inclui tipos que requerem um alocador de heap global, tais como Vec, Box e Arc.
• Os aplicativos Rust embarcados geralmente usam apenas core e, às vezes, alloc.

Documentação

O Rust vem com uma extensa documentação. Por exemplo:

• Todos os detalhes sobre loops.
• Tipos primitivos como u8.
• Tipos da biblioteca padrão como Option ou BinaryHeap.

Na verdade, você pode documentar seu próprio código:

/// Determine se o primeiro argumento é divisível pelo segundo argumento.
///
/// Se o segundo argumento for zero, o resultado é falso.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

O conteúdo é tratado como Markdown. Todos os crates publicados na biblioteca Rust são documentados automaticamente em docs.rs utilizando a ferramenta rustdoc. É idiomático documentar todos os itens públicos em uma API usando este padrão.

Para documentar um item de dentro do item (como dentro de um módulo), use //! ou /*! .. */, chamado de “comentários de documentação interna”:

//! Este módulo contém funcionalidades relacionadas à divisibilidade de inteiros.

Option

We have already seen some use of Option<T>. It stores either a value of type T or nothing. For example, String::find returns an Option<usize>.

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("find retornou {position:?}");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("find retornou {position:?}");
    assert_eq!(position.expect("Caractere não encontrado"), 0);
}

Result

Result é semelhante a Option, mas indica o sucesso ou falha de uma operação, cada um com um tipo diferente. Isso é semelhante ao Res definido no exercício de expressão, mas genérico: Result<T, E> onde T é usado na variante Ok e E aparece na variante Err.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("Querido diário: {contents} ({bytes} bytes)");
            } else {
                println!("Não é possivel ler o conteúdo do arquivo");
            }
        }
        Err(err) => {
            println!("Não foi possível abrir o diário: {err}");
        }
    }
}

String

String é o buffer padrão de cadeia de caracteres UTF-8 expansível e alocado no heap:

fn main() {
    let mut s1 = String::new();
    s1.push_str("Olá");
    println!("s1: tam = {}, capacidade = {}", s1.len(), s1.capacity());

    let mut s2 = String::with_capacity(s1.len() + 1);
    s2.push_str(&s1);
    s2.push('!');
    println!("s2: tam = {}, capacidade = {}", s2.len(), s2.capacity());

    let s3 = String::from("🇧🇷");
    println!("s3: tam = {}, número de caracteres = {}", s3.len(), s3.chars().count());
}

String implementa Deref<Target = str>, o que significa que você pode chamar todos os métodos de str em uma String.

Vec

Vec é o buffer padrão redimensionável alocado no heap:

fn main() {
    let mut v1 = Vec::new();
    v1.push(42);
    println!("v1: tamanho = {}, capacidade = {}", v1.len(), v1.capacity());

    let mut v2 = Vec::with_capacity(v1.len() + 1);
    v2.extend(v1.iter());
    v2.push(9999);
    println!("v2: tamanho = {}, capacidade = {}", v2.len(), v2.capacity());

    // Macro canônica para inicializar um vetor com elementos.
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // Mantém apenas os elementos pares.
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // Remove duplicatas consecutivas.
    v3.dedup();
    println!("{v3:?}");
}

Vec implementa Deref<Target = [T]>, o que significa que você pode chamar métodos de slice em um Vec.

HashMap

Hash map (Mapa de hash) padrão com proteção contra ataques HashDoS:

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("Adventures of Huckleberry Finn".to_string(), 207);
    page_counts.insert("Grimms' Fairy Tales".to_string(), 751);
    page_counts.insert("Pride and Prejudice".to_string(), 303);

    if !page_counts.contains_key("Les Misérables") {
        println!(
            "Nós sabemos sobre livros {}, mas não Les Misérables.",
            page_counts.len()
        );
    }

    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} páginas"),
            None => println!("{book} é desconhecido."),
        }
    }

    // Use o método .entry() para inserir um valor caso nada seja encontrado.
    for book in ["Pride and Prejudice", "Alice's Adventure in Wonderland"] {
        let page_count: &mut i32 = page_counts.entry(book.to_string()).or_insert(0);
        *page_count += 1;
    }

    println!("{page_counts:#?}");
}

Exercício: Contador

Neste exercício, você usará uma estrutura de dados muito simples e a tornará genérica. Ela usa um std::collections::HashMap para acompanhar quais valores foram vistos e quantas vezes cada um apareceu.

A versão inicial de Counter é codificada para funcionar apenas para valores u32. Faça a estrutura e seus métodos genéricos sobre o tipo de valor sendo rastreado, dessa forma Counter pode rastrear qualquer tipo de valor.

Se você terminar cedo, tente usar o método entry para reduzir pela metade o número de pesquisas de hash necessárias para implementar o método count.

use std::collections::HashMap;

/// Counter conta o número de vezes que cada valor do tipo T foi visto.
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// Cria um novo Counter.
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// Conta uma ocorrência do valor fornecido.
    fn count(&mut self, value: u32) {
        if self.values.contains_key(&value) {
            *self.values.get_mut(&value).unwrap() += 1;
        } else {
            self.values.insert(value, 1);
        }
    }

    /// Retorna o número de vezes que o valor fornecido foi visto.
    fn times_seen(&self, value: u32) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("viu {} valores iguais a {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("obteve {} maçãs", strctr.times_seen("apple"));
}

Solução

use std::collections::HashMap;
use std::hash::Hash;

/// Counter conta o número de vezes que cada valor do tipo T foi visto.
struct Counter<T: Eq + Hash> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// Cria um novo Counter.
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// Conta uma ocorrência do valor fornecido.
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// Retorna o número de vezes que o valor fornecido foi visto.
    fn times_seen(&self, value: T) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("viu {} valores iguais a {}", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("apple");
    strctr.count("orange");
    strctr.count("apple");
    println!("obteve {} maçãs", strctr.times_seen("apple"));
}

Traits da Biblioteca Padrão

This segment should take about 1 hour and 40 minutes. It contains:

Comparações

Esses traits suportam comparações entre valores. Todos os traits podem ser derivados para tipos que contêm campos que implementam esses traits.

PartialEq e Eq

PartialEq é uma relação de equivalência parcial, com o método eq obrigatório e o método ne fornecido. Os operadores == e != chamarão esses métodos.

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq for Key {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

Eq é uma relação de equivalência completa (reflexiva, simétrica e transitiva) e implica PartialEq. Funções que exigem equivalência completa usarão Eq como um limite de trait.

PartialOrd e Ord

PartialOrd define uma ordenação parcial, com um método partial_cmp. Ele é usado para implementar os operadores <, <=, >= e >.

use std::cmp::Ordering;
#[derive(Eq, PartialEq)]
struct Citation {
    author: String,
    year: u32,
}
impl PartialOrd for Citation {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        match self.author.partial_cmp(&other.author) {
            Some(Ordering::Equal) => self.year.partial_cmp(&other.year),
            author_ord => author_ord,
        }
    }
}

Ord é uma ordenação total, com cmp retornando Ordering.

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq<u32> for Key {
    fn eq(&self, other: &u32) -> bool {
        self.id == *other
    }
}

Operadores

A sobrecarga de operadores é implementada por meio do trait contido em std::ops:

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

impl std::ops::Add for Point {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        Self { x: self.x + other.x, y: self.y + other.y }
    }
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = Point { x: 100, y: 200 };
    println!("{:?} + {:?} = {:?}", p1, p2, p1 + p2);
}

From e Into

Os tipos implementam From e Into para facilitar as conversões de tipo:

fn main() {
    let s = String::from("olá");
    let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);
    let one = i16::from(true);
    let bigger = i32::from(123_i16);
    println!("{s}, {addr}, {one}, {bigger}");
}

Into é implementado automaticamente quando From é implementado:

fn main() {
    let s: String = "olá".into();
    let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();
    let one: i16 = true.into();
    let bigger: i32 = 123_i16.into();
    println!("{s}, {addr}, {one}, {bigger}");
}

Conversões

O Rust não tem conversões de tipo implícitas, mas suporta conversões explícitas com as. Essas geralmente seguem a semântica de C onde elas são definidas.

fn main() {
    let value: i64 = 1000;
    println!("como u16: {}", value as u16);
    println!("como i16: {}", value as i16);
    println!("como u8: {}", value as u8);
}

Os resultados de as são sempre definidos no Rust e consistentes em todas as plataformas. Isso pode não corresponder à sua intuição para alterar o sinal ou converter para um tipo menor - verifique a documentação e comente

Converter com as é uma ferramenta relativamente afiada que é fácil de usar incorretamente e pode ser uma fonte de bugs sutis à medida que o trabalho de manutenção futuro altera os tipos que são usados ou os intervalos de valores nos tipos. As conversões são melhores usadas apenas quando a intenção é indicar truncamento incondicional (por exemplo, selecionar os 32 bits inferiores de um u64 com as u32, independentemente do que estava nos bits altos).

Para conversões infalíveis (por exemplo, u32 para u64), prefira usar From ou Into em vez de as para confirmar que a conversão é de fato infalível. Para conversões falíveis, TryFrom e TryInto estão disponíveis quando você deseja lidar com conversões que se encaixam de maneira diferente daquelas que não se encaixam.

Read e Write

Usando Read e BufRead, você pode abstrair as fontes de dados do tipo u8:

use std::io::{BufRead, BufReader, Read, Result};

fn count_lines<R: Read>(reader: R) -> usize {
    let buf_reader = BufReader::new(reader);
    buf_reader.lines().count()
}

fn main() -> Result<()> {
    let slice: &[u8] = b"foo\nbar\nbaz\n";
    println!("linhas na _slice_: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("linhas no arquivo: {}", count_lines(file));
    Ok(())
}

Da mesma forma, Write permite abstrair a escrita de dados do tipo u8:

use std::io::{Result, Write};

fn log<W: Write>(writer: &mut W, msg: &str) -> Result<()> {
    writer.write_all(msg.as_bytes())?;
    writer.write_all("\n".as_bytes())
}

fn main() -> Result<()> {
    let mut buffer = Vec::new();
    log(&mut buffer, "Olá")?;
    log(&mut buffer, "Mundo")?;
    println!("Registrado: {:?}", buffer);
    Ok(())
}

O Trait Default

O trait Default fornece uma implementação padrão para um tipo.

#[derive(Debug, Default)]
struct Derived {
    x: u32,
    y: String,
    z: Implemented,
}

#[derive(Debug)]
struct Implemented(String);

impl Default for Implemented {
    fn default() -> Self {
        Self("John Smith".into())
    }
}

fn main() {
    let default_struct = Derived::default();
    println!("{default_struct:#?}");

    let almost_default_struct =
        Derived { y: "Y está definido!".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

    let nothing: Option<Derived> = None;
    println!("{:#?}", nothing.unwrap_or_default());
}

Closures

Closures ou expressões lambda têm tipos que não podem ser nomeados. No entanto, eles implementam os traits especiais Fn, FnMut e FnOnce:

fn apply_with_log(func: impl FnOnce(i32) -> i32, input: i32) -> i32 {
    println!("Chamando a função com {input}");
    func(input)
}

fn main() {
    let add_3 = |x| x + 3;
    println!("add_3: {}", apply_with_log(add_3, 10));
    println!("add_3: {}", apply_with_log(add_3, 20));

    let mut v = Vec::new();
    let mut accumulate = |x: i32| {
        v.push(x);
        v.iter().sum::<i32>()
    };
    println!("accumulate: {}", apply_with_log(&mut accumulate, 4));
    println!("accumulate: {}", apply_with_log(&mut accumulate, 5));

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    println!("multiply_sum: {}", apply_with_log(multiply_sum, 3));
}

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name);
}

fn main() {
    let hi = make_greeter("Olá".to_string());
    hi("Greg");
}

Exercício: ROT13

Neste exemplo, você implementará o clássico cifra “ROT13”. Copie este código para o playground e implemente as partes que faltam. Apenas rotacione caracteres alfabéticos ASCII para garantir que o resultado ainda seja UTF-8 válido.

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

// Implemente o trait `Read` para `RotDecoder`.

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

O que acontece se você encadear duas instâncias de RotDecoder, cada uma rotacionando 13 caracteres?

Solução

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

impl<R: Read> Read for RotDecoder<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        let size = self.input.read(buf)?;
        for b in &mut buf[..size] {
            if b.is_ascii_alphabetic() {
                let base = if b.is_ascii_uppercase() { 'A' } else { 'a' } as u8;
                *b = (*b - base + self.rot) % 26 + base;
            }
        }
        Ok(size)
    }
}

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

Bem-vindo ao Dia 3

Hoje, vamos cobrir:

• Gerenciamento de memória, tempos de vida (lifetimes) e o verificador de empréstimo (borrow checker): como o Rust garante a segurança da memória.
• Ponteiros inteligentes (smart pointers): tipos de ponteiros da biblioteca padrão.

Agenda

Including 10 minute breaks, this session should take about 2 hours and 20 minutes. It contains:

Gerenciamento de Memória

This segment should take about 1 hour. It contains:

Revisão da Memória de Programa

Os programas alocam memória de duas maneiras:

• Pilha: Área contínua de memória para variáveis locais.

  • Os valores têm tamanhos fixos conhecidos em tempo de compilação.
  • Extremamente rápida: basta mover um ponteiro de pilha.
  • Fácil de gerenciar: segue chamadas de função.
  • Ótima localidade de memória.

• Heap: Armazenamento de valores fora das chamadas de função.

  • Valores possuem tamanhos dinâmicos determinados em tempo de execução.
  • Ligeiramente mais devagar que a pilha: é necessário um pouco de gerenciamento.
  • Sem garantias de localidade de memória.

Exemplo

A criação de uma String coloca metadados de tamanho fixo na pilha e dados dinamicamente dimensionados - a string propriamente dita - no heap:

fn main() {
    let s1 = String::from("Olá");
}

fn main() {
    let mut s1 = String::from("Olá");
    s1.push(' ');
    s1.push_str("mundo");
    // NÃO FAÇA ISSO EM CASA! Somente com propósito educacional.
    // String não fornece nenhuma garantia sobre o seu layout, então isso pode causar
    // um comportamento indefinido.
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacity = {capacity}, ptr = {ptr:#x}, len = {len}");
    }
}

Abordagens para Gerenciamento de Memória

Tradicionalmente, as linguagens se dividem em duas grandes categorias:

• Controle total através do gerenciamento manual de memória: C, C++, Pascal, …
  • Programador decide quando alocar ou liberar memória do heap.
  • Programador deve determinar se um ponteiro ainda aponta para uma memória válida.
  • Estudos mostram que os programadores cometem erros.
• Segurança total através do gerenciamento automático de memória em tempo de execução: Java, Python, Go, Haskell, …
  • Um sistema em tempo de execução garante que a memória não seja liberada até que não possa mais ser referenciada.
  • Normalmente implementado com contagem de referência, coleta de lixo ou RAII.

Rust oferece uma nova combinação:

Controle total e segurança por imposição do correto gerenciamento de memória em tempo de compilação.

Ele faz isso com um conceito de ownership (posse) explícito.

Ownership

Todas as associações de variáveis têm um escopo onde são válidas e é um erro usar uma variável fora de seu escopo:

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        println!("x: {}", p.0);
    }
    println!("y: {}", p.1);
}

Dizemos que a variável owns (possui) o valor. Todo valor em Rust tem precisamente um owner (dono) em todos os momentos.

No final do escopo, a variável é descartada e os dados são liberados. Um destrutor pode ser executado aqui para liberar recursos.

Semântica de Movimento

Uma atribuição transferirá o ownership entre variáveis:

fn main() {
    let s1: String = String::from("Olá!");
    let s2: String = s1;
    println!("s2: {s2}");
    // println!("s1: {s1}");
}

• A atribuição de s1 a s2 transfere o ownership.
• Quando s1 sai do escopo, nada acontece: ele não tem ownership.
• Quando s2 sai do escopo, os dados da string são liberados.

Antes de mover para s2:

Depois de mover para s2:

Quando você passa um valor para uma função, o valor é atribuído ao parâmetro da função. Isso transfere a ownership:

fn say_hello(name: String) {
    println!("Olá {name}")
}

fn main() {
    let name = String::from("Alice");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // Duplica os dados em s1.

Clone

Às vezes você quer fazer uma cópia de um valor. O trait Clone consegue isso.

#[derive(Default)]
struct Backends {
    hostnames: Vec<String>,
    weights: Vec<f64>,
}

impl Backends {
    fn set_hostnames(&mut self, hostnames: &Vec<String>) {
        self.hostnames = hostnames.clone();
        self.weights = hostnames.iter().map(|_| 1.0).collect();
    }
}

Tipos Copiáveis

Embora a semântica de movimento seja o padrão, certos tipos são copiados por padrão:

fn main() {
    let x = 42;
    let y = x;
    println!("x: {x}"); // would not be accessible if not Copy
    println!("y: {y}");
}

Esses tipos implementam o trait Copy.

Você pode habilitar seus próprios tipos para usar a semântica de cópia:

#[derive(Copy, Clone, Debug)]
struct Point(i32, i32);

fn main() {
    let p1 = Point(3, 4);
    let p2 = p1;
    println!("p1: {p1:?}");
    println!("p2: {p2:?}");
}

• Após a atribuição, tanto p1 quanto p2 possuem seus próprios dados.
• Também podemos usar p1.clone() para copiar os dados explicitamente.

O Trait Drop

Valores que implementam Drop podem especificar o código a ser executado quando saem do escopo:

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Descartando {}", self.name);
    }
}

fn main() {
    let a = Droppable { name: "a" };
    {
        let b = Droppable { name: "b" };
        {
            let c = Droppable { name: "c" };
            let d = Droppable { name: "d" };
            println!("Saindo do bloco B");
        }
        println!("Saindo do bloco A");
    }
    drop(a);
    println!("Saindo do main");
}

Exercício: Tipo Builder

Neste exemplo, implementaremos um tipo de dados complexo que possui todos os seus dados. Usaremos o “builder pattern” para suportar a construção de um novo valor peça por peça, usando funções de conveniência.

Preencha as peças que faltam.

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// Uma representação de um pacote de software.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Retorna uma representação deste pacote como uma dependência, para uso na
    /// construção de outros pacotes.
    fn as_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// Um construtor para um Pacote. Use `build()` para criar o próprio `Package`.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        todo!("2")
    }

    /// Define a versão do pacote.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Define os autores do pacote.
    fn authors(mut self, authors: Vec<String>) -> Self {
        todo!("3")
    }

    /// Adiciona uma dependência adicional.
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// Define a linguagem. Se não definida, a linguagem é None.
    fn language(mut self, language: Language) -> Self {
        todo!("5")
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

Solução

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// Uma representação de um pacote de software.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Retorna uma representação deste pacote como uma dependência, para uso na
    /// construção de outros pacotes.
    fn as_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// Um construtor para um Pacote. Use `build()` para criar o próprio `Package`.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self(Package {
            name: name.into(),
            version: "0.1".into(),
            authors: vec![],
            dependencies: vec![],
            language: None,
        })
    }

    /// Define a versão do pacote.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Define os autores do pacote.
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// Adiciona uma dependência adicional.
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// Define a linguagem. Se não definida, a linguagem é None.
    fn language(mut self, language: Language) -> Self {
        self.0.language = Some(language);
        self
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

Ponteiros Inteligentes (Smart Pointers)

This segment should take about 55 minutes. It contains:

Box<T>

Box é um ponteiro owned para dados no heap:

fn main() {
    let five = Box::new(5);
    println!("cinco: {}", *five);
}

Box<T> implementa Deref<Target = T>, o que significa que você pode chamar métodos de T diretamente em um Box<T>.

Tipos de dados recursivos ou tipos de dados com tamanhos dinâmicos precisam usar uma Box:

#[derive(Debug)]
enum List<T> {
    /// Uma lista não vazia: primeiro elemento e o resto da lista.
    Element(T, Box<List<T>>),
    /// Uma lista vazia.
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

#[derive(Debug)]
enum List<T> {
    Element(T, Box<List<T>>),
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

Rc

Rc é um ponteiro compartilhado com contagem de referência. Use-o quando precisar consultar os mesmos dados a partir de vários locais:

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    println!("a: {a}");
    println!("b: {b}");
}

• Veja Arc e Mutex se você estiver em um contexto multi-thread.
• Você pode demover (downgrade) um ponteiro compartilhado para um ponteiro Weak (fraco) para criar ciclos que serão descartados.

Objetos Trait

Objetos trait permitem valores de diferentes tipos, por exemplo, em uma coleção:

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("Auau, meu nome é {}", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Bidu"), age: 5 }),
    ];
    for pet in pets {
        println!("Olá, quem é você? {}", pet.talk());
    }
}

Layout da memória após alocar pets:

Exercício: Árvore Binária

Uma árvore binária é uma estrutura de dados do tipo árvore onde cada nó tem dois filhos (esquerdo e direito). Criaremos uma árvore onde cada nó armazena um valor. Para um determinado nó N, todos os nós na subárvore esquerda de N contêm valores menores, e todos os nós na subárvore direita de N conterão valores maiores.

Implemente os seguintes tipos, para que os testes fornecidos passem.

Extra: implemente um iterador sobre uma árvore binária que retorna os valores em ordem.

/// Um nó na árvore binária.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Uma subárvore possivelmente vazia.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Um contêiner que armazena um conjunto de valores, usando uma árvore binária.
///
/// Se o mesmo valor for adicionado várias vezes, ele é armazenado apenas uma vez.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

// Implemente `new`, `insert`, `len` e `has`.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // não é um item único
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Solução

use std::cmp::Ordering;

/// Um nó na árvore binária.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// Uma subárvore possivelmente vazia.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// Um contêiner que armazena um conjunto de valores, usando uma árvore binária.
///
/// Se o mesmo valor for adicionado várias vezes, ele é armazenado apenas uma vez.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

impl<T: Ord> Subtree<T> {
    fn new() -> Self {
        Self(None)
    }

    fn insert(&mut self, value: T) {
        match &mut self.0 {
            None => self.0 = Some(Box::new(Node::new(value))),
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.insert(value),
                Ordering::Equal => {}
                Ordering::Greater => n.right.insert(value),
            },
        }
    }

    fn has(&self, value: &T) -> bool {
        match &self.0 {
            None => false,
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.has(value),
                Ordering::Equal => true,
                Ordering::Greater => n.right.has(value),
            },
        }
    }

    fn len(&self) -> usize {
        match &self.0 {
            None => 0,
            Some(n) => 1 + n.left.len() + n.right.len(),
        }
    }
}

impl<T: Ord> Node<T> {
    fn new(value: T) -> Self {
        Self { value, left: Subtree::new(), right: Subtree::new() }
    }
}

fn main() {
    let mut tree = BinaryTree::new();
    tree.insert("foo");
    assert_eq!(tree.len(), 1);
    tree.insert("bar");
    assert!(tree.has(&"foo"));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // não é um item único
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

Bem-vindo de volta

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

Empréstimo (Borrowing)

This segment should take about 50 minutes. It contains:

Emprestando um Valor

Como vimos antes, ao invés de transferir a ownership ao chamar uma função, você pode deixar uma função emprestar (borrow) o valor:

#[derive(Debug)]
struct Point(i32, i32);

fn add(p1: &Point, p2: &Point) -> Point {
    Point(p1.0 + p2.0, p1.1 + p2.1)
}

fn main() {
    let p1 = Point(3, 4);
    let p2 = Point(10, 20);
    let p3 = add(&p1, &p2);
    println!("{p1:?} + {p2:?} = {p3:?}");
}

• A função add pega emprestado (borrows) dois pontos e retorna um novo ponto.
• O chamador mantém a ownership das entradas.

Verificação de Empréstimo

O verificador de empréstimo (borrow checker) do Rust impõe restrições sobre as maneiras como você pode emprestar valores. Para um determinado valor, a qualquer momento:

• Você pode ter uma ou mais referências compartilhadas para o valor, ou
• Você pode ter exatamente uma referência exclusiva para o valor.

fn main() {
    let mut a: i32 = 10;
    let b: &i32 = &a;

    {
        let c: &mut i32 = &mut a;
        *c = 20;
    }

    println!("a: {a}");
    println!("b: {b}");
}

Mutabilidade Interior

In some situations, it’s necessary to modify data behind a shared (read-only) reference. For example, a shared data structure might have an internal cache, and wish to update that cache from read-only methods.

The “interior mutability” pattern allows exclusive (mutable) access behind a shared reference. The standard library provides several ways to do this, all while still ensuring safety, typically by performing a runtime check.

RefCell

use std::cell::RefCell;
use std::rc::Rc;

#[derive(Debug, Default)]
struct Node {
    value: i64,
    children: Vec<Rc<RefCell<Node>>>,
}

impl Node {
    fn new(value: i64) -> Rc<RefCell<Node>> {
        Rc::new(RefCell::new(Node { value, ..Node::default() }))
    }

    fn sum(&self) -> i64 {
        self.value + self.children.iter().map(|c| c.borrow().sum()).sum::<i64>()
    }
}

fn main() {
    let root = Node::new(1);
    root.borrow_mut().children.push(Node::new(5));
    let subtree = Node::new(10);
    subtree.borrow_mut().children.push(Node::new(11));
    subtree.borrow_mut().children.push(Node::new(12));
    root.borrow_mut().children.push(subtree);

    println!("grafo: {root:#?}");
    println!("soma do grafo: {}", root.borrow().sum());
}

Cell

Cell wraps a value and allows getting or setting the value, even with a shared reference to the Cell. However, it does not allow any references to the value. Since there are no references, borrowing rules cannot be broken.

Exercício: Estatísticas de Saúde

Você está trabalhando na implementação de um sistema de monitoramento de saúde. Como parte disso, você precisa acompanhar as estatísticas de saúde dos usuários.

Você começará com um esboço de função em um bloco impl e também uma definição de struct User. Seu objetivo é implementar o método esboçado na struct User definida no bloco impl.

Copie o código abaixo em https://play.rust-lang.org/ e implemente os métodos que estão faltando:

// TODO: remova isto quando você terminar sua implementação.
#![allow(unused_variables, dead_code)]


#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        todo!("Atualiza as estatísticas de um usuário com base nas medições de uma visita ao médico")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("I'm {} and my age is {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
}

Solução

#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        self.visit_count += 1;
        let bp = measurements.blood_pressure;
        let report = HealthReport {
            patient_name: &self.name,
            visit_count: self.visit_count as u32,
            height_change: measurements.height - self.height,
            blood_pressure_change: match self.last_blood_pressure {
                Some(lbp) => {
                    Some((bp.0 as i32 - lbp.0 as i32, bp.1 as i32 - lbp.1 as i32))
                }
                None => None,
            },
        };
        self.height = measurements.height;
        self.last_blood_pressure = Some(bp);
        report
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("I'm {} and my age is {}", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
}

Slices (Fatias) e Tempos de Vida (Lifetimes)

This segment should take about 1 hour and 10 minutes. It contains:

Slices (Fatias)

Uma slice (fatia) oferece uma visão de uma coleção maior:

fn main() {
    let mut a: [i32; 6] = [10, 20, 30, 40, 50, 60];
    println!("a: {a:?}");

    let s: &[i32] = &a[2..4];

    println!("s: {s:?}");
}

• Slices pegam dados emprestados (_borrow) do tipo original.
• Pergunta: O que acontece se você modificar a[3] imediatamente antes de imprimir s?

Referências de String

Agora podemos entender os dois tipos de string em Rust: &str é quase como &[char], mas com seus dados armazenados em uma codificação de comprimento variável (UTF-8).

fn main() {
    let s1: &str = "Mundo";
    println!("s1: {s1}");

    let mut s2: String = String::from("Olá ");
    println!("s2: {s2}");
    s2.push_str(s1);
    println!("s2: {s2}");

    let s3: &str = &s2[6..];
    println!("s3: {s3}");
}

Terminologia do Rust:

• &str é uma referência imutável para uma slice de string.
• String é um buffer de string mutável.

Anotações de Tempo de Vida

Uma referência tem um tempo de vida (lifetime), que não deve “sobreviver” ao valor ao qual se refere. Isso é verificado pelo borrow checker (verificador de empréstimo).

O tempo de vida pode ser implícito - isso é o que vimos até agora. Os tempos de vida também podem ser explícitos: &'a Point, &'document str. Os tempos de vida começam com ' e 'a é um nome padrão típico. Leia &'a Point como “um Point emprestado que é válido por pelo menos o tempo de vida a”.

Os tempos de vida são sempre inferidos pelo compilador: você não pode atribuir um tempo de vida por conta própria. Anotações explícitas de tempo de vida criam restrições onde há ambiguidade; o compilador verifica se há uma solução válida.

Os tempos de vida se tornam mais complicados ao considerar a passagem de valores para e a devolução de valores de funções.

#[derive(Debug)]
struct Point(i32, i32);

fn left_most(p1: &Point, p2: &Point) -> &Point {
    if p1.0 < p2.0 {
        p1
    } else {
        p2
    }
}

fn main() {
    let p1: Point = Point(10, 10);
    let p2: Point = Point(20, 20);
    let p3 = left_most(&p1, &p2); // Qual é o tempo de vida de p3?
    println!("p3: {p3:?}");
}

fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {

Tempos de vida (Lifetimes) em Chamadas de Função

Tempos de vida para argumentos de função e valores de retorno precisam ser completamente especificados, mas o Rust permite que eles sejam omitidos na maioria das vezes com algumas regras simples. Isso não é inferência - é apenas uma abreviação sintática.

• Cada argumento que não tem uma anotação de tempo de vida é dado um.
• Se houver apenas um tempo de vida de argumento, ele é dado a todos os valores de retorno não anotados.
• Se houver vários tempos de vida de argumento, mas o primeiro for para self (self), esse tempo de vida é dado a todos os valores de retorno não anotados.

#[derive(Debug)]
struct Point(i32, i32);

fn cab_distance(p1: &Point, p2: &Point) -> i32 {
    (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
}

fn nearest<'a>(points: &'a [Point], query: &Point) -> Option<&'a Point> {
    let mut nearest = None;
    for p in points {
        if let Some((_, nearest_dist)) = nearest {
            let dist = cab_distance(p, query);
            if dist < nearest_dist {
                nearest = Some((p, dist));
            }
        } else {
            nearest = Some((p, cab_distance(p, query)));
        };
    }
    nearest.map(|(p, _)| p)
}

fn main() {
    println!(
        "{:?}",
        nearest(
            &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1),],
            &Point(0, 2)
        )
    );
}

fn nearest<'a, 'q>(points: &'a [Point], query: &'q Point) -> Option<&'q Point> {

Tempos de Vida em Estruturas de Dados

Se um tipo de dados armazena dados emprestados, ele deve ser anotado com um tempo de vida:

#[derive(Debug)]
struct Highlight<'doc>(&'doc str);

fn erase(text: String) {
    println!("Até logo {text}!");
}

fn main() {
    let text = String::from("The quick brown fox jumps over the lazy dog.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // erase(text);
    println!("{fox:?}");
    println!("{dog:?}");
}

Exercício: Análise de Protobuf

Neste exercício, você construirá um analisador (parser) para a codificação binária de protobuf. Não se preocupe, é mais simples do que parece! Isso ilustra um padrão de análise comum, passando slices de dados. Os próprios dados subjacentes nunca são copiados.

Analisar (parse) completamente uma mensagem protobuf requer conhecer os tipos dos campos, indexados por seus números de campo. Isso é normalmente fornecido em um arquivo proto. Neste exercício, codificaremos essas informações em declarações match em funções que são chamadas para cada campo.

Usaremos o seguinte proto:

message PhoneNumber {
  optional string number = 1;
  optional string type = 2;
}

message Person {
  optional string name = 1;
  optional int32 id = 2;
  repeated PhoneNumber phones = 3;
}

Uma mensagem proto é codificada como uma série de campos, um após o outro. Cada um é implementado como uma “tag” seguida pelo valor. A tag contém um número de campo (por exemplo, 2 para o campo id de uma mensagem Person) e um tipo de fio (wire type) definindo como a carga útil deve ser determinada a partir do fluxo (stream) de bytes.

Números inteiros, incluindo a tag, são representados com uma codificação de comprimento variável chamada VARINT. Felizmente, parse_varint é definido para você abaixo. O código fornecido também define callbacks para lidar com campos Person e PhoneNumber, e para analisar uma mensagem em uma série de chamadas para esses callbacks.

O que resta para você é implementar a função parse_field e o trait ProtoMessage para Person e PhoneNumber.

use std::convert::TryFrom;
use thiserror::Error;

#[derive(Debug, Error)]
enum Error {
    #[error("Varint inválido")]
    InvalidVarint,
    #[error("Wire-type inválido")]
    InvalidWireType,
    #[error("EOF inesperado")]
    UnexpectedEOF,
    #[error("Comprimento inválido")]
    InvalidSize(#[from] std::num::TryFromIntError),
    #[error("Wire-type inesperado")]
    UnexpectedWireType,
    #[error("String inválida (não UTF-8)")]
    InvalidString,
}

/// Um wire type como visto no wire.
enum WireType {
    /// O Varint WireType indica que o valor é um único VARINT.
    Varint,
    //I64,  -- não é necessário para este exercício
    /// O Len WireType indica que o valor é um comprimento representado como um
    /// VARINT seguido exatamente por esse número de bytes.
    Len,
    /// O I32 WireType indica que o valor é precisamente 4 bytes em
    /// ordem little-endian contendo um inteiro de 32 bits com sinal.
    I32,
}

#[derive(Debug)]
/// O valor de um campo, digitado com base no wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- não é necessário para este exercício
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// Um campo, contendo o número do campo e seu valor.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default + 'a {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error>;
}

impl TryFrom<u64> for WireType {
    type Error = Error;

    fn try_from(value: u64) -> Result<WireType, Error> {
        Ok(match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- não é necessário para este exercício
            2 => WireType::Len,
            5 => WireType::I32,
            _ => return Err(Error::InvalidWireType),
        })
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> Result<&'a str, Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        std::str::from_utf8(data).map_err(|_| Error::InvalidString)
    }

    fn as_bytes(&self) -> Result<&'a [u8], Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(data)
    }

    fn as_u64(&self) -> Result<u64, Error> {
        let FieldValue::Varint(value) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(*value)
    }
}

/// Analise (_parse_) um VARINT, retornando o valor analisado e os bytes restantes.
fn parse_varint(data: &[u8]) -> Result<(u64, &[u8]), Error> {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            return Err(Error::InvalidVarint);
        };
        if b & 0x80 == 0 {
            // Este é o último byte do VARINT, então converta-o para
            // um u64 e retorne-o.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return Ok((value, &data[i + 1..]));
        }
    }

    // Mais de 7 bytes é inválido.
    Err(Error::InvalidVarint)
}

/// Converta uma tag em um número de campo e um WireType.
fn unpack_tag(tag: u64) -> Result<(u64, WireType), Error> {
    let field_num = tag >> 3;
    let wire_type = WireType::try_from(tag & 0x7)?;
    Ok((field_num, wire_type))
}


/// Analise (_parse_) um campo, retornando os bytes restantes
fn parse_field(data: &[u8]) -> Result<(Field, &[u8]), Error> {
    let (tag, remainder) = parse_varint(data)?;
    let (field_num, wire_type) = unpack_tag(tag)?;
    let (fieldvalue, remainder) = match wire_type {
        _ => todo!("Com base no wire type, construa um Field, consumindo quantos bytes forem necessários.")
    };
    todo!("Retorne o campo e quaisquer bytes não consumidos.")
}

/// Analise (_parse_) uma mensagem nos dados fornecidos, chamando `T::add_field` para cada campo na
/// mensagem.
///
/// Todo o input é consumido.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> Result<T, Error> {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data)?;
        result.add_field(parsed.0)?;
        data = parsed.1;
    }
    Ok(result)
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TODO: Implemente ProtoMessage para Person e PhoneNumber.

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ])
    .unwrap();
    println!("{:#?}", person);
}

Solução

use std::convert::TryFrom;
use thiserror::Error;

#[derive(Debug, Error)]
enum Error {
    #[error("Varint inválido")]
    InvalidVarint,
    #[error("Wire-type inválido")]
    InvalidWireType,
    #[error("EOF inesperado")]
    UnexpectedEOF,
    #[error("Comprimento inválido")]
    InvalidSize(#[from] std::num::TryFromIntError),
    #[error("Wire-type inesperado")]
    UnexpectedWireType,
    #[error("String inválida (não UTF-8)")]
    InvalidString,
}

/// Um wire type como visto no wire.
enum WireType {
    /// O Varint WireType indica que o valor é um único VARINT.
    Varint,
    //I64,  -- não é necessário para este exercício
    /// O Len WireType indica que o valor é um comprimento representado como um
    /// VARINT seguido exatamente por esse número de bytes.
    Len,
    /// O I32 WireType indica que o valor é precisamente 4 bytes em
    /// ordem little-endian contendo um inteiro de 32 bits com sinal.
    I32,
}

#[derive(Debug)]
/// O valor de um campo, digitado com base no wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- não é necessário para este exercício
    Len(&'a [u8]),
    I32(i32),
}

#[derive(Debug)]
/// Um campo, contendo o número do campo e seu valor.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default + 'a {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error>;
}

impl TryFrom<u64> for WireType {
    type Error = Error;

    fn try_from(value: u64) -> Result<WireType, Error> {
        Ok(match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- não é necessário para este exercício
            2 => WireType::Len,
            5 => WireType::I32,
            _ => return Err(Error::InvalidWireType),
        })
    }
}

impl<'a> FieldValue<'a> {
    fn as_string(&self) -> Result<&'a str, Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        std::str::from_utf8(data).map_err(|_| Error::InvalidString)
    }

    fn as_bytes(&self) -> Result<&'a [u8], Error> {
        let FieldValue::Len(data) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(data)
    }

    fn as_u64(&self) -> Result<u64, Error> {
        let FieldValue::Varint(value) = self else {
            return Err(Error::UnexpectedWireType);
        };
        Ok(*value)
    }
}

/// Analise (_parse_) um VARINT, retornando o valor analisado e os bytes restantes.
fn parse_varint(data: &[u8]) -> Result<(u64, &[u8]), Error> {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            return Err(Error::InvalidVarint);
        };
        if b & 0x80 == 0 {
            // Este é o último byte do VARINT, então converta-o para
            // um u64 e retorne-o.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return Ok((value, &data[i + 1..]));
        }
    }

    // Mais de 7 bytes é inválido.
    Err(Error::InvalidVarint)
}

/// Converta uma tag em um número de campo e um WireType.
fn unpack_tag(tag: u64) -> Result<(u64, WireType), Error> {
    let field_num = tag >> 3;
    let wire_type = WireType::try_from(tag & 0x7)?;
    Ok((field_num, wire_type))
}

/// Analise (_parse_) um campo, retornando os bytes restantes
fn parse_field(data: &[u8]) -> Result<(Field, &[u8]), Error> {
    let (tag, remainder) = parse_varint(data)?;
    let (field_num, wire_type) = unpack_tag(tag)?;
    let (fieldvalue, remainder) = match wire_type {
        WireType::Varint => {
            let (value, remainder) = parse_varint(remainder)?;
            (FieldValue::Varint(value), remainder)
        }
        WireType::Len => {
            let (len, remainder) = parse_varint(remainder)?;
            let len: usize = len.try_into()?;
            if remainder.len() < len {
                return Err(Error::UnexpectedEOF);
            }
            let (value, remainder) = remainder.split_at(len);
            (FieldValue::Len(value), remainder)
        }
        WireType::I32 => {
            if remainder.len() < 4 {
                return Err(Error::UnexpectedEOF);
            }
            let (value, remainder) = remainder.split_at(4);
            // Unwrap o erro porque `value` definitivamente tem 4 bytes.
            let value = i32::from_le_bytes(value.try_into().unwrap());
            (FieldValue::I32(value), remainder)
        }
    };
    Ok((Field { field_num, value: fieldvalue }, remainder))
}

/// Analise (_parse_) uma mensagem nos dados fornecidos, chamando `T::add_field` para cada campo na
/// mensagem.
///
/// Todo o input é consumido.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> Result<T, Error> {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data)?;
        result.add_field(parsed.0)?;
        data = parsed.1;
    }
    Ok(result)
}

#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

impl<'a> ProtoMessage<'a> for Person<'a> {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error> {
        match field.field_num {
            1 => self.name = field.value.as_string()?,
            2 => self.id = field.value.as_u64()?,
            3 => self.phone.push(parse_message(field.value.as_bytes()?)?),
            _ => {} // pule todo o resto
        }
        Ok(())
    }
}

impl<'a> ProtoMessage<'a> for PhoneNumber<'a> {
    fn add_field(&mut self, field: Field<'a>) -> Result<(), Error> {
        match field.field_num {
            1 => self.number = field.value.as_string()?,
            2 => self.type_ = field.value.as_string()?,
            _ => {} // pule todo o resto
        }
        Ok(())
    }
}

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ])
    .unwrap();
    println!("{:#?}", person);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn as_string() {
        assert!(FieldValue::Varint(10).as_string().is_err());
        assert!(FieldValue::I32(10).as_string().is_err());
        assert_eq!(FieldValue::Len(b"olá").as_string().unwrap(), "olá");
    }

    #[test]
    fn as_bytes() {
        assert!(FieldValue::Varint(10).as_bytes().is_err());
        assert!(FieldValue::I32(10).as_bytes().is_err());
        assert_eq!(FieldValue::Len(b"olá").as_bytes().unwrap(), b"olá");
    }

    #[test]
    fn as_u64() {
        assert_eq!(FieldValue::Varint(10).as_u64().unwrap(), 10u64);
        assert!(FieldValue::I32(10).as_u64().is_err());
        assert!(FieldValue::Len(b"olá").as_u64().is_err());
    }
}

Bem-vindo ao Dia 4

Hoje abordaremos tópicos relacionados à construção de software em larga escala em Rust:

• Iteradores: uma análise profunda do trait Iterator.
• Módulos e visibilidade.
• Testes.
• Tratamento de erros: pânicos, Result e o operador ?.
• Rust inseguro: a saída de emergência quando você não consegue se expressar em Rust seguro.

Agenda

Including 10 minute breaks, this session should take about 2 hours and 50 minutes. It contains:

Iteradores

This segment should take about 45 minutes. It contains:

Iterator

O trait Iterator suporta a iteração sobre valores em uma coleção. Ele requer um método next e fornece muitos métodos. Muitos tipos da biblioteca padrão implementam Iterator, e você também pode implementá-lo:

struct Fibonacci {
    curr: u32,
    next: u32,
}

impl Iterator for Fibonacci {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let new_next = self.curr + self.next;
        self.curr = self.next;
        self.next = new_next;
        Some(self.curr)
    }
}

fn main() {
    let fib = Fibonacci { curr: 0, next: 1 };
    for (i, n) in fib.enumerate().take(5) {
        println!("fib({i}): {n}");
    }
}

IntoIterator

O trait Iterator informa como iterar depois de criar um iterador. O trait relacionado IntoIterator define como criar um iterador para um tipo. Ele é usado automaticamente pelo laço for.

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl IntoIterator for Grid {
    type Item = (u32, u32);
    type IntoIter = GridIter;
    fn into_iter(self) -> GridIter {
        GridIter { grid: self, i: 0, j: 0 }
    }
}

struct GridIter {
    grid: Grid,
    i: usize,
    j: usize,
}

impl Iterator for GridIter {
    type Item = (u32, u32);

    fn next(&mut self) -> Option<(u32, u32)> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((self.grid.x_coords[self.i], self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };
    for (x, y) in grid {
        println!("point = {x}, {y}");
    }
}

FromIterator

FromIterator permite que você construa uma coleção a partir de um Iterator.

fn main() {
    let primes = vec![2, 3, 5, 7];
    let prime_squares = primes.into_iter().map(|p| p * p).collect::<Vec<_>>();
    println!("prime_squares: {prime_squares:?}");
}

fn collect<B>(self) -> B
where
    B: FromIterator<Self::Item>,
    Self: Sized

Exercício: Encadeamento de Métodos de Iterador

Neste exercício, você precisará encontrar e usar alguns dos métodos fornecidos no trait Iterator para implementar um cálculo complexo.

Copie o seguinte código para https://play.rust-lang.org/ e faça os testes passarem. Use uma expressão de iterador e collect o resultado para construir o valor de retorno.

#![allow(unused)]
fn main() {
/// Calcule as diferenças entre os elementos de `values` deslocados por `offset`,
/// voltando ao início de `values` no final.
///
/// O elemento `n` do resultado é `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    unimplemented!()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}
}

Solução

/// Calcule as diferenças entre os elementos de `values` deslocados por `offset`,
/// voltando ao início de `values` no final.
///
/// O elemento `n` do resultado é `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    let a = (&values).into_iter();
    let b = (&values).into_iter().cycle().skip(offset);
    a.zip(b).map(|(a, b)| *b - *a).take(values.len()).collect()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

fn main() {}

Módulos

This segment should take about 40 minutes. It contains:

Módulos

Vimos como os blocos impl nos permitem usar namespaces (espaços de nomes) de funções para um tipo.

Da mesma forma, mod nos permite usar namespaces de tipos e funções:

mod foo {
    pub fn do_something() {
        println!("No módulo foo");
    }
}

mod bar {
    pub fn do_something() {
        println!("No módulo bar");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

Hierarquia do Sistema de Arquivos

Omitir o conteúdo do módulo dirá ao Rust para procurá-lo em outro arquivo:

mod garden;

Isto diz ao Rust que o conteúdo do módulo garden é encontrado em src/garden.rs. Da mesma forma, um módulo garden::vegetables pode ser encontrado em src/garden/vegetables.rs.

A raiz do crate está em:

• src/lib.rs (para um crate de biblioteca)
• src/main.rs (para um crate binário)

Módulos definidos em arquivos também podem ser documentados usando “comentários internos de documento” (inner doc comments). Estes documentam o item que os contém - neste caso, um módulo.

//! Este módulo implementa o jardim (_garden_), incluindo uma implementação de germinação
//!  de alto desempenho.

// Re-exporta tipos deste módulo.
pub use garden::Garden;
pub use seeds::SeedPacket;

/// Semeia os pacotes de semente fornecidos.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Colhe os vegetais no jardim que está pronto.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

Visibilidade

Módulos são limitadores de privacidade:

• Itens do módulo são privados por padrão (ocultam detalhes de implementação).
• Itens paternos e fraternos são sempre visíveis.
• Em outras palavras, se um item é visível no módulo foo, ele é visível em todos os descendentes de foo.

mod outer {
    fn private() {
        println!("outer::private");
    }

    pub fn public() {
        println!("outer::public");
    }

    mod inner {
        fn private() {
            println!("outer::inner::private");
        }

        pub fn public() {
            println!("outer::inner::public");
            super::private();
        }
    }
}

fn main() {
    outer::public();
}

use, super, self

Um módulo pode trazer símbolos de outro módulo para o escopo com use. Normalmente, você verá algo assim na parte superior de cada módulo:

use std::collections::HashSet;
use std::process::abort;

Caminhos (Paths)

Caminhos são resolvidos da seguinte forma:

1. Como um caminho relativo:

   • foo ou self::foo referem-se à foo no módulo atual,
   • super::foo refere-se à foo no módulo pai.

2. Como um caminho absoluto:

   • crate::foo refere-se à foo na raiz do crate atual,
   • bar::foo refere-se a foo no crate bar.

Exercise: Modules for a GUI Library

In this exercise, you will reorganize a small GUI Library implementation. This library defines a Widget trait and a few implementations of that trait, as well as a main function.

It is typical to put each type or set of closely-related types into its own module, so each widget type should get its own module.

Configuração do Cargo

O playground do Rust suporta apenas um arquivo, então você precisará criar um projeto Cargo em seu sistema de arquivos local:

cargo init gui-modules
cd gui-modules
cargo run

Edit the resulting src/main.rs to add mod statements, and add additional files in the src directory.

Source

Here’s the single-module implementation of the GUI library:

pub trait Widget {
    /// Largura natural de `self`.
    fn width(&self) -> usize;

    /// Desenha o _widget_ em um buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Desenha o _widget_ na saída padrão.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub struct Label {
    label: String,
}

impl Label {
    fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

pub struct Button {
    label: Label,
}

impl Button {
    fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // Adiciona 4 preenchimentos para as bordas
        self.inner_width() + 4
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: Change draw_into to return Result<(), std::fmt::Error>. Then use the
        // ?-operator here instead of .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        self.label.width() + 8 // adicione um pouco de preenchimento
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

fn main() {
    let mut window = Window::new("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("Este é um pequeno demo de GUI em texto.")));
    window.add_widget(Box::new(Button::new("Clique em mim!")));
    window.draw();
}

Solução

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
mod button;
mod label;
mod window;

pub trait Widget {
    /// Largura natural de `self`.
    fn width(&self) -> usize;

    /// Desenha o _widget_ em um buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Desenha o _widget_ na saída padrão.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub use button::Button;
pub use label::Label;
pub use window::Window;

// ---- src/widgets/label.rs ----
use super::Widget;

pub struct Label {
    label: String,
}

impl Label {
    pub fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        // ANCHOR_END: Label-width
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    // ANCHOR: Label-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Label-draw_into
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

// ---- src/widgets/button.rs ----
use super::{Label, Widget};

pub struct Button {
    label: Label,
}

impl Button {
    pub fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        // ANCHOR_END: Button-width
        self.label.width() + 8 // adicione um pouco de preenchimento
    }

    // ANCHOR: Button-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Button-draw_into
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", "").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", "").unwrap();
    }
}

// ---- src/widgets/window.rs ----
use super::Widget;

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    pub fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    pub fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // ANCHOR_END: Window-width
        // Adiciona 4 preenchimentos para as bordas
        self.inner_width() + 4
    }

    // ANCHOR: Window-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Window-draw_into
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: depois de aprender sobre tratamento de erros, você pode alterar
        // draw_into para retornar Result<(), std::fmt::Error>. Então use
        // o operador ? aqui em vez de .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", "").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", "").unwrap();
    }
}

// ---- src/main.rs ----
mod widgets;

use widgets::Widget;

fn main() {
    let mut window = widgets::Window::new("Rust GUI Demo 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("Este é um pequeno demo de GUI em texto.")));
    window.add_widget(Box::new(widgets::Button::new("Clique em mim!")));
    window.draw();
}

Testando

This segment should take about 1 hour. It contains:

Testes Unitários

Rust e Cargo vêm com uma estrutura de testes unitários simples:

• Testes unitários são suportados em todo o seu código.

• Testes de integração são suportados através do diretório tests/.

Testes são marcados com #[test]. Testes unitários são frequentemente colocados em um módulo aninhado tests, usando #[cfg(test)] para compilá-los condicionalmente apenas ao construir testes.

fn first_word(text: &str) -> &str {
    match text.find(' ') {
        Some(idx) => &text[..idx],
        None => &text,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty() {
        assert_eq!(first_word(""), "");
    }

    #[test]
    fn test_single_word() {
        assert_eq!(first_word("Olá"), "Olá");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("Hello World"), "Olá");
    }
}

• Isso permite que você tenha testes unitários auxiliares privados.
• O atributo #[cfg(test)] somente fica ativo quando você executa cargo test.

Outros Tipos de Testes

Testes de Integração

Se quiser testar sua biblioteca como um cliente, use um teste de integração.

Crie um arquivo .rs em tests/:

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

Esses testes têm acesso somente à API pública do seu crate.

Testes de Documentação

Rust tem suporte embutido para testes de documentação:

#![allow(unused)]
fn main() {
/// Reduz uma string para o comprimento fornecido.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hello World", 5), "Hello");
/// assert_eq!(shorten_string("Hello World", 20), "Hello World");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• Blocos de código em comentários /// são vistos automaticamente como código Rust.
• O código será compilado e executado como parte do cargo test.
• Adicionar # no código o ocultará da documentação, mas ainda o compilará/executará.
• Teste o código acima no Rust Playground.

Crates Úteis

Rust possui apenas suporte básico para escrever testes.

Estes são alguns crates adicionais que recomendamos para a escrita de testes:

• googletest: Biblioteca abrangente para testes de assertividade na tradição de GoogleTest para C++.
• proptest: Testes baseados em propriedades para Rust.
• rstest: Suporte para testes parametrizados e acessórios.

GoogleTest

O crate GoogleTest permite assertividade de testes flexível usando matchers (correspondentes):

use googletest::prelude::*;

#[googletest::test]
fn test_elements_are() {
    let value = vec!["foo", "bar", "baz"];
    expect_that!(value, elements_are!(eq("foo"), lt("xyz"), starts_with("b")));
}

Se mudarmos o último elemento para "!", o teste falha com uma mensagem de erro estruturada apontando o erro:

---- test_elements_are stdout ----
Value of: value
Expected: has elements:
  0. is equal to "foo"
  1. is less than "xyz"
  2. starts with prefix "!"
Actual: ["foo", "bar", "baz"],
  where element #2 is "baz", which does not start with "!"
  at src/testing/googletest.rs:6:5
Error: See failure output above

#[test]
fn test_multiline_string_diff() {
    let haiku = "Memory safety found,\n\
                 Rust's strong typing guides the way,\n\
                 Secure code you'll write.";
    assert_that!(
        haiku,
        eq("Memory safety found,\n\
            Rust's silly humor guides the way,\n\
            Secure code you'll write.")
    );
}

    Value of: haiku
Expected: is equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Actual: "Memory safety found,\nRust's strong typing guides the way,\nSecure code you'll write.",
  which isn't equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Difference(-actual / +expected):
 Memory safety found,
-Rust's strong typing guides the way,
+Rust's silly humor guides the way,
 Secure code you'll write.
  at src/testing/googletest.rs:17:5

Mocking

Para mocking, Mockall é uma biblioteca muito usada. Você precisa refatorar seu código para usar traits, que você pode então rapidamente “mockar”:

use std::time::Duration;

#[mockall::automock]
pub trait Pet {
    fn is_hungry(&self, since_last_meal: Duration) -> bool;
}

#[test]
fn test_robot_dog() {
    let mut mock_dog = MockPet::new();
    mock_dog.expect_is_hungry().return_const(true);
    assert_eq!(mock_dog.is_hungry(Duration::from_secs(10)), true);
}

#[test]
fn test_robot_cat() {
    let mut mock_cat = MockPet::new();
    mock_cat
        .expect_is_hungry()
        .with(mockall::predicate::gt(Duration::from_secs(3 * 3600)))
        .return_const(true);
    mock_cat.expect_is_hungry().return_const(false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(1 * 3600)), false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(5 * 3600)), true);
}

Lints do Compilador e Clippy

O compilador Rust produz mensagens de erro fantásticas, bem como alertas/lints úteis embutidos. Clippy fornece ainda mais lints, organizados em grupos que podem ser habilitados por projeto.

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!("X provavelmente cabe em um u16, certo? {}", x as u16);
}

Exercício: Algoritmo de Luhn

Algoritmo de Luhn

O algoritmo de Luhn é usado para validar números de cartão de crédito. O algoritmo recebe uma string como entrada e faz o seguinte para validar o número do cartão de crédito:

• Ignore all spaces. Reject number with fewer than two digits.

• Movendo-se da direita para a esquerda, dobre cada segundo dígito: para o número 1234, dobramos 3 e 1. Para o número 98765, dobramos 6 e 8.

• Depois de dobrar um dígito, some os dígitos se o resultado for maior que 9. Então, dobrar 7 se torna 14 que se torna 1 + 4 = 5.

• Some todos os dígitos, dobrados ou não.

• O número do cartão de crédito é válido se a soma terminar em 0.

O código fornecido fornece uma implementação com bugs do algoritmo de Luhn, junto com dois testes unitários básicos que confirmam que a maior parte do algoritmo é implementada corretamente.

Copy the code below to https://play.rust-lang.org/ and write additional tests to uncover bugs in the provided implementation, fixing any bugs you find.

#![allow(unused)]
fn main() {
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }
}
}

Solução

// Esta é a versão com bugs que aparece no problema.
#[cfg(never)]
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

// Esta é a solução e passa em todos os testes abaixo.
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;
    let mut digits = 0;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            digits += 1;
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else if c.is_whitespace() {
            continue;
        } else {
            return false;
        }
    }

    digits >= 2 && sum % 10 == 0
}

fn main() {
    let cc_number = "1234 5678 1234 5670";
    println!(
        "O número do cartão de crédito {cc_number} é válido? {}",
        if luhn(cc_number) { "sim" } else { "não" }
    );
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }

    #[test]
    fn test_non_digit_cc_number() {
        assert!(!luhn("foo"));
        assert!(!luhn("foo 0 0 "));
    }

    #[test]
    fn test_empty_cc_number() {
        assert!(!luhn(""));
        assert!(!luhn(" "));
        assert!(!luhn("  "));
        assert!(!luhn("    "));
    }

    #[test]
    fn test_single_digit_cc_number() {
        assert!(!luhn("0"));
    }

    #[test]
    fn test_two_digit_cc_number() {
        assert!(luhn(" 0 0 "));
    }
}

Bem-vindo de volta

Including 10 minute breaks, this session should take about 2 hours and 10 minutes. It contains:

Tratamento de Erros

This segment should take about 55 minutes. It contains:

Pânicos (Panics)

Rust lida com erros fatais com um “pânico”.

O Rust irá disparar um panic (pânico) se um erro fatal ocorrer em tempo de execução:

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• Pânicos são para erros irrecuperáveis e inesperados.
  • Pânicos são sintomas de bugs no programa.
  • Falhas em tempo de execução como verificações de limites falhadas podem disparar um pânico
  • Asserções (como assert!) disparam um pânico em caso de falha
  • Pânicos com moticos específicos podem usar a macro panic!.
• Um pânico irá “desenrolar” a pilha, descartando valores como se as funções tivessem retornado.
• Use APIs que não disparam erros do tipo pânico (como Vec::get) se não for aceitável o travamento do programa.

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "Nenhum problema aqui!");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("ah não!");
    });
    println!("{result:?}");
}

Operador Try

Erros em tempo de execução como conexão recusada ou arquivo não encontrado são tratados com o tipo Result, mas combinar esse tipo em cada chamada pode ser complicado. O operador ? é usado para retornar erros ao chamador. Ele permite que você transforme o comum

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

no muito mais simples

some_expression?

Podemos usar isso para simplificar nosso código de tratamento de erros:

use std::io::Read;
use std::{fs, io};

fn read_username(path: &str) -> Result<String, io::Error> {
    let username_file_result = fs::File::open(path);
    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(err) => return Err(err),
    };

    let mut username = String::new();
    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(err) => Err(err),
    }
}

fn main() {
    //fs::write("config.dat", "alice").unwrap();
    let username = read_username("config.dat");
    println!("username ou erro: {username:?}");
}

Conversões Try

A expansão efetiva do operador ? é um pouco mais complicada do que indicado anteriormente:

expression?

funciona da mesma forma que

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

A chamada From::from aqui significa que tentamos converter o tipo de erro para o tipo retornado pela função. Isso torna fácil encapsular erros em erros de nível superior.

Exemplo

use std::error::Error;
use std::fmt::{self, Display, Formatter};
use std::fs::File;
use std::io::{self, Read};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername(String),
}

impl Error for ReadUsernameError {}

impl Display for ReadUsernameError {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "Erro E/S: {e}"),
            Self::EmptyUsername(path) => write!(f, "Nome de usuário não encontrado em {path}"),
        }
    }
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("username ou erro: {username:?}");
}

Tipos de Erros Dinâmicos

Às vezes, queremos permitir que qualquer tipo de erro seja retornado sem escrever nosso próprio enum cobrindo todas as possibilidades diferentes. O trait std::error::Error torna fácil criar um objeto trait que pode conter qualquer erro.

use std::error::Error;
use std::fs;
use std::io::Read;

fn read_count(path: &str) -> Result<i32, Box<dyn Error>> {
    let mut count_str = String::new();
    fs::File::open(path)?.read_to_string(&mut count_str)?;
    let count: i32 = count_str.parse()?;
    Ok(count)
}

fn main() {
    fs::write("count.dat", "1i3").unwrap();
    match read_count("count.dat") {
        Ok(count) => println!("Contagem: {count}"),
        Err(err) => println!("Erro: {err}"),
    }
}

thiserror e anyhow

The thiserror and anyhow crates are widely used to simplify error handling.

• thiserror is often used in libraries to create custom error types that implement From<T>.
• anyhow is often used by applications to help with error handling in functions, including adding contextual information to your errors.

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("Nome de usuário não encontrado em {0}")]
struct EmptyUsernameError(String);

fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("Falha ao abrir {path}"))?
        .read_to_string(&mut username)
        .context("Falha ao ler")?;
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Nome do usuário: {username}"),
        Err(err) => println!("Erro: {err:?}"),
    }
}

Exercício: Reescrevendo com Result

O seguinte implementa um analisador muito simples para uma linguagem de expressão. No entanto, ele lida com erros disparando um pânico. Reescreva-o para usar o tratamento de erros idiomático e propagar erros para um retorno de main. Sinta-se à vontade para usar thiserror e anyhow.

DICA: comece corrigindo o tratamento de erros na função parse. Depois que isso estiver funcionando corretamente, atualize Tokenizer para implementar Iterator<Item=Result<Token, TokenizerError>> e trate isso no analisador (parser).

use std::iter::Peekable;
use std::str::Chars;

/// Um operador aritmético.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Um token na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Uma expressão na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Uma referência a uma variável.
    Var(String),
    /// Um número literal.
    Number(u32),
    /// Uma operação binária.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Token;

    fn next(&mut self) -> Option<Token> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => {
                let mut num = String::from(c);
                while let Some(c @ '0'..='9') = self.0.peek() {
                    num.push(*c);
                    self.0.next();
                }
                Some(Token::Number(num))
            }
            'a'..='z' => {
                let mut ident = String::from(c);
                while let Some(c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
                    ident.push(*c);
                    self.0.next();
                }
                Some(Token::Identifier(ident))
            }
            '+' => Some(Token::Operator(Op::Add)),
            '-' => Some(Token::Operator(Op::Sub)),
            _ => panic!("Caractere inesperado {c}"),
        }
    }
}

fn parse(input: &str) -> Expression {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(tokens: &mut Tokenizer<'a>) -> Expression {
        let Some(tok) = tokens.next() else {
            panic!("Fim de entrada inesperado");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("Inteiro de 32 bits inválido'");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("Token inesperado {tok:?}"),
        };
        // Olhe adiante para analisar uma operação binária, se presente.
        match tokens.next() {
            None => expr,
            Some(Token::Operator(op)) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)),
            ),
            Some(tok) => panic!("Token inesperado {tok:?}"),
        }
    }

    parse_expr(&mut tokens)
}

fn main() {
    let expr = parse("10+foo+20-30");
    println!("{expr:?}");
}

Solução

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// Um operador aritmético.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// Um token na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// Uma expressão na linguagem de expressão.
#[derive(Debug, PartialEq)]
enum Expression {
    /// Uma referência a uma variável.
    Var(String),
    /// Um número literal.
    Number(u32),
    /// Uma operação binária.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("Caractere '{0}' inesperado na entrada")]
    UnexpectedCharacter(char),
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Result<Token, TokenizerError>;

    fn next(&mut self) -> Option<Result<Token, TokenizerError>> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => {
                let mut num = String::from(c);
                while let Some(c @ '0'..='9') = self.0.peek() {
                    num.push(*c);
                    self.0.next();
                }
                Some(Ok(Token::Number(num)))
            }
            'a'..='z' => {
                let mut ident = String::from(c);
                while let Some(c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
                    ident.push(*c);
                    self.0.next();
                }
                Some(Ok(Token::Identifier(ident)))
            }
            '+' => Some(Ok(Token::Operator(Op::Add))),
            '-' => Some(Ok(Token::Operator(Op::Sub))),
            _ => Some(Err(TokenizerError::UnexpectedCharacter(c))),
        }
    }
}

#[derive(Debug, Error)]
enum ParserError {
    #[error("Erro de tokenizador: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("Fim de entrada inesperado")]
    UnexpectedEOF,
    #[error("Token inesperado {0:?}")]
    UnexpectedToken(Token),
    #[error("Número inválido")]
    InvalidNumber(#[from] std::num::ParseIntError),
}

fn parse(input: &str) -> Result<Expression, ParserError> {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(
        tokens: &mut Tokenizer<'a>,
    ) -> Result<Expression, ParserError> {
        let tok = tokens.next().ok_or(ParserError::UnexpectedEOF)??;
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse()?;
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => return Err(ParserError::UnexpectedToken(tok)),
        };
        // Olhe adiante para analisar uma operação binária, se presente.
        Ok(match tokens.next() {
            None => expr,
            Some(Ok(Token::Operator(op))) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)?),
            ),
            Some(Err(e)) => return Err(e.into()),
            Some(Ok(tok)) => return Err(ParserError::UnexpectedToken(tok)),
        })
    }

    parse_expr(&mut tokens)
}

fn main() -> anyhow::Result<()> {
    let expr = parse("10+foo+20-30")?;
    println!("{expr:?}");
    Ok(())
}

Rust Inseguro (Unsafe)

This segment should take about 1 hour and 5 minutes. It contains:

Rust Inseguro (Unsafe)

A linguagem Rust tem duas partes:

• Rust Seguro (Safe): memória segura, nenhum comportamento indefinido é possível.
• Rust Inseguro (Unsafe): pode desencadear comportamento indefinido se pré-condições forem violadas.

Veremos principalmente Rust seguro neste curso, mas é importante saber o que é Rust inseguro.

Código inseguro é geralmente pequeno e isolado, e seu funcionamento correto deve ser cuidadosamente documentado. Geralmente é envolto em uma camada de abstração segura.

O código inseguro do Rust oferece acesso a cinco novos recursos:

• Desreferenciar ponteiros brutos (raw pointers).
• Acessar ou modificar variáveis estáticas mutáveis.
• Acessar os campos de uma union.
• Chamar funções unsafe (inseguras), incluindo funções extern (externas).
• Implementar traits unsafe.

A seguir, abordaremos brevemente os recursos inseguros. Para detalhes completos, consulte o Capítulo 19.1 no Rust Book e o Rustonomicon.

Desreferenciando Ponteiros Brutos

Criar ponteiros é seguro, mas desreferenciá-los requer unsafe:

fn main() {
    let mut s = String::from("cuidado!");

    let r1 = &mut s as *mut String;
    let r2 = r1 as *const String;

    // Seguro porque r1 e r2 foram obtidos através de referências e logo é
    // garantido que eles não sejam nulos e sejam propriamente alinhados, os objetos
    // cujas referências foram obtidas são válidos por
    // todo o bloco inseguro, e eles não sejam acessados tanto através das
    // referências ou concorrentemente através de outros ponteiros.
    unsafe {
        println!("r1 é: {}", *r1);
        *r1 = String::from("oh-oh");
        println!("r2 é: {}", *r2);
    }

    // NÃO É SEGURO. NÃO FAÇA ISSO.
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 é: {}", *r3);
    */
}

Variáveis Estáticas Mutáveis

É seguro ler uma variável estática imutável:

static HELLO_WORLD: &str = "Olá, mundo!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

No entanto, como podem ocorrer corridas de dados (data races), não é seguro ler e gravar dados em variáveis estáticas mutáveis:

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    unsafe {
        println!("COUNTER: {COUNTER}");
    }
}

Uniões

Unions são como enums, mas você mesmo precisa rastrear o campo ativo:

#[repr(C)]
union MyUnion {
    i: u8,
    b: bool,
}

fn main() {
    let u = MyUnion { i: 42 };
    println!("int: {}", unsafe { u.i });
    println!("bool: {}", unsafe { u.b }); // Comportamento indefinido!
}

Funções Inseguras

Chamando Funções Inseguras

Uma função ou método pode ser marcado como unsafe se houver pré-condições extras que você deve respeitar para evitar comportamento indefinido:

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // Seguro porque os índices estão na ordem correta, dentro dos limites da
    // slice da string, e contido dentro da sequência UTF-8.
    unsafe {
        println!("emoji: {}", emojis.get_unchecked(0..4));
        println!("emoji: {}", emojis.get_unchecked(4..7));
        println!("emoji: {}", emojis.get_unchecked(7..11));
    }

    println!("contador de caracteres: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    unsafe {
        // Comportamento indefinido se abs se comportar mal.
        println!("Valor absoluto de -3 de acordo com C: {}", abs(-3));
    }

    // Não manter o requerimento de codificação UTF-8 viola segurança de memória!
    // println!("emoji: {}", unsafe { emojis.get_unchecked(0..3) });
    // println!("contador caracter: {}", count_chars(unsafe {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

Escrevendo Funções Inseguras

Você pode marcar suas próprias funções como inseguras (unsafe) se elas exigirem condições específicas para evitar comportamentos indefinidos.

/// Troca os valores apontadoes pelos ponteiros fornecidos.
///
/// # Segurança
///
/// Os ponteiros precisam ser válidos e corretamente alinhados.
unsafe fn swap(a: *mut u8, b: *mut u8) {
    let temp = *a;
    *a = *b;
    *b = temp;
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // Seguro porque ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

Implementando Traits Inseguros

Assim como nas funções, você pode marcar um trait como unsafe se a implementação precisa garantir condições particulares para evitar comportamento indefinido.

Por exemplo, o crate zerocopy tem um trait inseguro que parece algo assim:

use std::mem::size_of_val;
use std::slice;

/// ...
/// # Segurança
/// O tipo precisa ter uma representação definida e nenhum preenchimento.
pub unsafe trait AsBytes {
    fn as_bytes(&self) -> &[u8] {
        unsafe {
            slice::from_raw_parts(
                self as *const Self as *const u8,
                size_of_val(self),
            )
        }
    }
}

// Seguro porque u32 possui uma representação definida e sem preenchimento.
unsafe impl AsBytes for u32 {}

Wrapper FFI seguro

Rust tem ótimo suporte para chamar funções por meio de uma interface para funções externas (Function Foreign Interface - FFI). Usaremos isso para construir um wrapper (invólucro) seguro para as funções da libc de C que você usaria para ler os nomes dos arquivos de um diretório.

Você vai querer consultar as páginas do manual:

• opendir(3)
• readdir(3)
• closedir(3)

Você também vai querer navegar pelo módulo std::ffi. Lá você encontrará um número de tipos de string que você precisará para o exercício:

Você irá converter entre todos estes tipos:

• &str para CString: você precisa alocar espaço para o caracter terminador \0,
• CString para *const i8: você precisa de um ponteiro para chamar funções em C,
• *const i8 para &CStr: você você precisa de algo que pode encontrar o caracter terminador \0,
• &CStr para &[u8]: um slice de bytes é a interface universal para “algum dado desconhecido”,
• &[u8] para &OsStr: &OsStr é um passo em direção a OsString, use OsStrExt para criá-lo,
• &OsStr para OsString: você precisa clonar os dados em &OsStr para poder retorná-lo e chamar readdir novamente.

O Nomicon também tem um capítulo bastante útil sobre FFI.

Copie o código abaixo para https://play.rust-lang.org/ e implemente as funções e métodos que faltam:

// TODO: remova isto quando você terminar sua implementação.
#![allow(unused_imports, unused_variables, dead_code)]

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Tipo opaco. Veja https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Layout de acordo com a página man do Linux para readdir(3), onde ino_t e
    // off_t são resolvidos de acordo com as definições em
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Layout de acordo com a página man do macOS man page para dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // Veja https://github.com/rust-lang/libc/issues/414 e a seção sobre
        // _DARWIN_FEATURE_64_BIT_INODE na página man do macOS para stat(2).
        //
        // "Plataformas que existiram antes destas atualizações estarem disponíveis" refere-se
        // ao macOS (ao contrário do iOS / wearOS / etc.) em Intel e PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Chama opendir e retorna um valor Ok se funcionar,
        // ou retorna Err com uma mensagem.
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Continua chamando readdir até nós obtermos um ponteiro NULL de volta.
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Chama closedir se necessário.
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

Solução

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Tipo opaco. Veja https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Layout de acordo com a página man do Linux para readdir(3), onde ino_t e
    // off_t são resolvidos de acordo com as definições em
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Layout de acordo com a página man do macOS man page para dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // Veja https://github.com/rust-lang/libc/issues/414 e a seção sobre
        // _DARWIN_FEATURE_64_BIT_INODE na página man do macOS para stat(2).
        //
        // "Plataformas que existiram antes destas atualizações estarem disponíveis" refere-se
        // ao macOS (ao contrário do iOS / wearOS / etc.) em Intel e PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Chama opendir e retorna um valor Ok se funcionar,
        // ou retorna Err com uma mensagem.
        let path =
            CString::new(path).map_err(|err| format!("Invalid path: {err}"))?;
        // SEGURANÇA: path.as_ptr() não pode ser NULL.
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("Não foi possível abrir {:?}", path))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Continua chamando readdir até nós obtermos um ponteiro NULL de volta.
        // SEGURANÇA: self.dir nunca é NULL.
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // Chegamos ao final do diretório.
            return None;
        }
        // SEGURANÇA: dirent não é NULL e dirent.d_name é terminado em NUL
        let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };
        let os_str = OsStr::from_bytes(d_name.to_bytes());
        Some(os_str.to_owned())
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Chama closedir se necessário.
        if !self.dir.is_null() {
            // SEGURANÇA: self.dir não é NULL.
            if unsafe { ffi::closedir(self.dir) } != 0 {
                panic!("Não foi possível fechar {:?}", self.path);
            }
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn test_nonexisting_directory() {
        let iter = DirectoryIterator::new("no-such-directory");
        assert!(iter.is_err());
    }

    #[test]
    fn test_empty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Caracter não UTF-8 no caminho")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", ".."]);
        Ok(())
    }

    #[test]
    fn test_nonempty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        std::fs::write(tmp.path().join("foo.txt"), "The Foo Diaries\n")?;
        std::fs::write(tmp.path().join("bar.png"), "<PNG>\n")?;
        std::fs::write(tmp.path().join("crab.rs"), "//! Caranguejo (Crab)\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("Caracter não UTF-8 no caminho")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

Bem-vindo ao Rust para Android

O Rust é suportado para software de sistema no Android. Isso significa que você pode escrever novos serviços, bibliotecas, drivers ou até mesmo firmware em Rust (ou melhorar o código existente conforme necessário).

Hoje tentaremos chamar Rust a partir de um de seus próprios projetos. Então tente encontrar um cantinho da sua base de código onde podemos mover algumas linhas de código para o Rust. Quanto menos dependências e tipos “exóticos”, melhor. Algo que analise alguns bytes brutos seria o ideal.

Configuração

Usaremos um Dispositivo Virtual Android Cuttlefish para testar nosso código. Certifique-se de ter acesso a um ou crie um novo com:

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

Consulte o Codelab para Desenvolvedor Android para maiores detalhes.

Regras de Compilação (Build Rules)

O sistema de compilação do Android (Soong) oferece suporte ao Rust por meio de vários módulos:

Veremos rust_binary e rust_library a seguir.

Binários do Rust

Vamos começar com um aplicativo simples. Na raiz de um checkout AOSP, crie os seguintes arquivos:

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs:

//! Rust demo.

/// Imprime uma saudação na saída padrão.
fn main() {
    println!("Olá do Rust!");
}

Agora você pode compilar, enviar e executar o binário:

m hello_rust
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust /data/local/tmp"
adb shell /data/local/tmp/hello_rust

Hello from Rust!

Bibliotecas de Rust

Você usa rust_library para criar uma nova biblioteca Rust para Android.

Aqui declaramos uma dependência em duas bibliotecas:

• libgreeting, que definimos abaixo,
• libtextwrap, que é um crate já oferecido em external/rust/crates/.

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust_with_dep",
    crate_name: "hello_rust_with_dep",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libgreetings",
        "libtextwrap",
    ],
    prefer_rlib: true, // Precisamos disso para evitar erro de ligação dinâmica.
}

rust_library {
    name: "libgreetings",
    crate_name: "greetings",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs:

//! Rust demo.

use greetings::greeting;
use textwrap::fill;

/// Imprime uma saudação na saída padrão.
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs:

//! Greeting library.

/// Saudação `nome`.
pub fn greeting(name: &str) -> String {
    format!("Olá {nome}, prazer em conhecê-lo!")
}

Você constrói, envia e executa o binário como antes:

m hello_rust_with_dep
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep /data/local/tmp"
adb shell /data/local/tmp/hello_rust_with_dep

Hello Bob, it is very
nice to meet you!

AIDL

A Linguagem de Definição de Interface Android (AIDL) é compatível com Rust:

• O código Rust pode chamar servidores AIDL existentes,
• Você pode criar novos servidores AIDL em Rust.

Birthday Service Tutorial

To illustrate how to use Rust with Binder, we’re going to walk through the process of creating a Binder interface. We’re then going to both implement the described service and write client code that talks to that service.

Interfaces AIDL

Você declara a API do seu serviço usando uma interface AIDL:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Interface de serviço de aniversário. */
interface IBirthdayService {
    /** Gera uma mensagem de feliz aniversário. */
    String wishHappyBirthday(String name, int years);
}

birthday_service/aidl/Android.bp:

aidl_interface {
    name: "com.example.birthdayservice",
    srcs: ["com/example/birthdayservice/*.aidl"],
    unstable: true,
    backend: {
        rust: { // Rust não está ativado por padrão
            enabled: true,
        },
    },
}

Generated Service API

Binder generates a trait corresponding to the interface definition. trait to talk to the service.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Interface de serviço de aniversário. */
interface IBirthdayService {
    /** Gera uma mensagem de feliz aniversário. */
    String wishHappyBirthday(String name, int years);
}

Generated trait:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

Your service will need to implement this trait, and your client will use this trait to talk to the service.

Implementação do Serviço

Agora podemos implementar o serviço AIDL:

birthday_service/src/lib.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// A implementação de `IBirthdayService`.
pub struct BirthdayService;

impl binder::Interface for BirthdayService {}

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
        Ok(format!("Feliz aniversário {name}, parabéns pelos seus {years} anos!"))
    }
}

birthday_service/Android.bp:

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

Servidor AIDL

Finalmente, podemos criar um servidor que expõe o serviço:

birthday_service/src/server.rs:

//! Birthday service.
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Ponto de entrada para serviço de aniversário.
fn main() {
    let birthday_service = BirthdayService;
    let birthday_service_binder = BnBirthdayService::new_binder(
        birthday_service,
        binder::BinderFeatures::default(),
    );
    binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())
        .expect("Falha ao registrar o serviço");
    binder::ProcessState::join_thread_pool()
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_server",
    crate_name: "birthday_server",
    srcs: ["src/server.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
        "libbirthdayservice",
    ],
    prefer_rlib: true, // To avoid dynamic link error.
}

Implantar

Agora podemos compilar, enviar e iniciar o serviço:

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server /data/local/tmp"
adb root
adb shell /data/local/tmp/birthday_server

Em outro terminal, verifique se o serviço está sendo executado:

adb shell service check birthdayservice

Service birthdayservice: found

Você também pode chamar o serviço com service call:

adb shell service call birthdayservice 1 s16 Bob i32 24

Result: Parcel(
  0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'
  0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'
  0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'
  0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'
  0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'
  0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'
  0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'
  0x00000070: 00210073 00000000                   's.!.....        ')

Cliente AIDL

Por fim, podemos criar um cliente Rust para nosso novo serviço.

birthday_server/src/client.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Chama o serviço de aniversário.
fn main() -> Result<(), Box<dyn Error>> {
    let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
    let years = std::env::args()
        .nth(2)
        .and_then(|arg| arg.parse::<i32>().ok())
        .unwrap_or(42);

    binder::ProcessState::start_thread_pool();
    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
        .map_err(|_| "Falha ao conectar-se a BirthdayService")?;

    // Call the service.
    let msg = service.wishHappyBirthday(&name, years)?;
    println!("{msg}");
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_client",
    crate_name: "birthday_client",
    srcs: ["src/client.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
    prefer_rlib: true, // To avoid dynamic link error.
}

Observe que o cliente não depende de libbirthdayservice.

Compile, envie e execute o cliente em seu dispositivo:

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client" /data/local/tmp
adb shell /data/local/tmp/birthday_client Charlie 60

Happy Birthday Charlie, congratulations with the 60 years!

Alterando API

Vamos estender a API com mais funcionalidades: queremos permitir que os clientes especifiquem uma lista de frases para o cartão de aniversário:

package com.example.birthdayservice;

/** Interface de serviço de aniversário. */
interface IBirthdayService {
    /** Gera uma mensagem de feliz aniversário. */
    String wishHappyBirthday(String name, int years, in String[] text);
}

This results in an updated trait definition for IBirthdayService:

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

Updating Client and Service

Update the client and server code to account for the new API.

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String> {
        let mut msg = format!(
            "Feliz aniversário {name}, parabéns pelos seus {years} anos!",
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_server/src/client.rs:

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Habby birfday to yuuuuu"),
        String::from("And also: many more"),
    ],
)?;

Working With AIDL Types

AIDL types translate into the appropriate idiomatic Rust type:

• Primitive types map (mostly) to idiomatic Rust types.
• Collection types like slices, Vecs and string types are supported.
• References to AIDL objects and file handles can be sent between clients and services.
• File handles and parcelables are fully supported.

Primitive Types

Primitive types map (mostly) idiomatically:

Array Types

The array types (T[], byte[], and List<T>) get translated to the appropriate Rust array type depending on how they are used in the function signature:

Sending Objects

AIDL objects can be sent either as a concrete AIDL type or as the type-erased IBinder interface:

birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl:

package com.example.birthdayservice;

interface IBirthdayInfoProvider {
    String name();
    int years();
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.IBirthdayInfoProvider;

interface IBirthdayService {
    /** The same thing, but using a binder object. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** The same thing, but using `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// Rust struct implementing the `IBirthdayInfoProvider` interface.
struct InfoProvider {
    name: String,
    age: u8,
}

impl binder::Interface for InfoProvider {}

impl IBirthdayInfoProvider for InfoProvider {
    fn name(&self) -> binder::Result<String> {
        Ok(self.name.clone())
    }

    fn years(&self) -> binder::Result<i32> {
        Ok(self.age as i32)
    }
}

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Falha ao conectar-se a BirthdayService");

    // Create a binder object for the `IBirthdayInfoProvider` interface.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Send the binder object to the service.
    service.wishWithProvider(&provider)?;

    // Perform the same operation but passing the provider as an `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

Parcelables

Binder for Rust supports sending parcelables directly:

birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl:

package com.example.birthdayservice;

parcelable BirthdayInfo {
    String name;
    int years;
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.BirthdayInfo;

interface IBirthdayService {
    /** The same thing, but with a parcelable. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Falha ao conectar-se a BirthdayService");

    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
}

Sending Files

Files can be sent between Binder clients/servers using the ParcelFileDescriptor type:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** The same thing, but loads info from a file. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Falha ao conectar-se a BirthdayService");

    // Open a file and put the birthday info in it.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Create a `ParcelFileDescriptor` from the file and send it.
    let file = ParcelFileDescriptor::new(file);
    service.wishFromFile(&file)?;
}

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishFromFile(
        &self,
        info_file: &ParcelFileDescriptor,
    ) -> binder::Result<String> {
        // Convert the file descriptor to a `File`. `ParcelFileDescriptor` wraps
        // an `OwnedFd`, which can be cloned and then used to create a `File`
        // object.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("Invalid file handle");

        let mut contents = String::new();
        info_file.read_to_string(&mut contents).unwrap();

        let mut lines = contents.lines();
        let name = lines.next().unwrap();
        let years: i32 = lines.next().unwrap().parse().unwrap();

        Ok(format!("Feliz aniversário {name}, parabéns pelos seus {years} anos!"))
    }
}

Gerando Registros (Log)

Você deve usar o crate log para logar automaticamente no logcat (no dispositivo) ou stdout (no host):

hello_rust_logs/Android.bp:

rust_binary {
    name: "hello_rust_logs",
    crate_name: "hello_rust_logs",
    srcs: ["src/main.rs"],
    rustlibs: [
        "liblog_rust",
        "liblogger",
    ],
    host_supported: true,
}

hello_rust_logs/src/main.rs:

//! Rust logging demo.

use log::{debug, error, info};

/// Registra uma saudação.
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_min_level(log::Level::Trace),
    );
    debug!("Iniciando programa.");
    info!("As coisas estão indo bem.");
    error!("Algo deu errado!");
}

Compile, envie e execute o binário em seu dispositivo:

m hello_rust_logs
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs /data/local/tmp"
adb shell /data/local/tmp/hello_rust_logs

Os logs aparecem em adb logcat:

adb logcat -s rust

09-08 08:38:32.454  2420  2420 D rust: hello_rust_logs: Starting program.
09-08 08:38:32.454  2420  2420 I rust: hello_rust_logs: Things are going fine.
09-08 08:38:32.454  2420  2420 E rust: hello_rust_logs: Something went wrong!

Interoperabilidade

O Rust tem excelente suporte para interoperabilidade com outras linguagens. Isso significa que você pode:

• Chamar funções Rust em outras linguagens.
• Chamar funções escritas em outras linguagens no Rust.

Quando você chama funções em outra linguagem, dizemos que você está usando uma interface de função externa, também conhecida como FFI.

Interoperabilidade com C

Rust tem suporte completo para vincular arquivos de objeto com uma convenção de chamada C. Da mesma forma, você pode exportar funções Rust e chamá-las em C.

Você pode fazer isso manualmente se quiser:

extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    let abs_x = unsafe { abs(x) };
    println!("{x}, {abs_x}");
}

Já vimos isso no exercício Safe FFI Wrapper .

Isso pressupõe conhecimento total da plataforma de destino. Não recomendado para produção.

Veremos opções melhores a seguir.

Usando Bindgen

A ferramenta bindgen pode gerar vínculos (bindings) automaticamente a partir de um arquivo de cabeçalho C.

Primeiro crie uma pequena biblioteca C:

interoperability/bindgen/libbirthday.h:

typedef struct card {
  const char* name;
  int years;
} card;

void print_card(const card* card);

interoperability/bindgen/libbirthday.c:

#include <stdio.h>
#include "libbirthday.h"

void print_card(const card* card) {
  printf("+--------------\n");
  printf("|Feliz Aniversário %s!\n", card->name);
  printf("|Parabéns pelos %i anos!\n", card->years);
  printf("+--------------\n");
}

Adicione isto ao seu arquivo Android.bp:

interoperability/bindgen/Android.bp:

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

Crie um arquivo de cabeçalho wrapper para a biblioteca (não estritamente necessário neste exemplo):

interoperability/bindgen/libbirthday_wrapper.h:

#include "libbirthday.h"

Agora você pode gerar automaticamente as vinculações (bindings):

interoperability/bindgen/Android.bp:

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "bindings",
    static_libs: ["libbirthday"],
}

Finalmente, podemos usar as vinculações (bindings) em nosso programa Rust:

interoperability/bindgen/Android.bp:

rust_binary {
    name: "print_birthday_card",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

interoperability/bindgen/main.rs:

//! Bindgen demo.

use birthday_bindgen::{card, print_card};

fn main() {
    let name = std::ffi::CString::new("Peter").unwrap();
    let card = card { name: name.as_ptr(), years: 42 };
    // SEGURANÇA: `print_card` é seguro para chamar com um ponteiro `card` válido.
    unsafe {
        print_card(&card as *const card);
    }
}

Compile, envie e execute o binário em seu dispositivo:

m print_birthday_card
adb push "$ANDROID_PRODUCT_OUT/system/bin/print_birthday_card /data/local/tmp"
adb shell /data/local/tmp/print_birthday_card

Por fim, podemos executar testes gerados automaticamente para garantir que as vinculações funcionem:

interoperability/bindgen/Android.bp:

rust_test {
    name: "libbirthday_bindgen_test",
    srcs: [":libbirthday_bindgen"],
    crate_name: "libbirthday_bindgen_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,
    clippy_lints: "none", // Arquivo gerado, pule o linting
    lints: "none",
}

atest libbirthday_bindgen_test

Chamando Rust

Exportar funções e tipos do Rust para C é fácil:

interoperability/rust/libanalyze/analyze.rs

//! Rust FFI demo.
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Analisar os números.
#[no_mangle]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("x ({x}) é o menor!");
    } else {
        println!("y ({y}) é provavelmente maior que x ({x})");
    }
}

interoperability/rust/libanalyze/analyze.h

#ifndef ANALYSE_H
#define ANALYSE_H

extern "C" {
void analyze_numbers(int x, int y);
}

#endif

interoperability/rust/libanalyze/Android.bp

rust_ffi {
    name: "libanalyze_ffi",
    crate_name: "analyze_ffi",
    srcs: ["analyze.rs"],
    include_dirs: ["."],
}

Agora podemos chamá-lo a partir de um binário C:

interoperability/rust/analisar/main.c

#include "analyze.h"

int main() {
  analyze_numbers(10, 20);
  analyze_numbers(123, 123);
  return 0;
}

interoperability/rust/analyze/Android.bp

cc_binary {
    name: "analyze_numbers",
    srcs: ["main.c"],
    static_libs: ["libanalyze_ffi"],
}

Compile, envie e execute o binário em seu dispositivo:

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers /data/local/tmp"
adb shell /data/local/tmp/analyze_numbers

Com C++

O crate CXX possibilita a interoperabilidade segura entre Rust e C++.

A abordagem geral é assim:

O Módulo Bridge

O CXX depende de uma descrição das assinaturas de função que serão expostas de cada linguagem para a outra. Você fornece essa descrição usando blocos externos em um módulo Rust anotado com a macro de atributo #[cxx::bridge].

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // Estruturas compartilhadas com campos visíveis para ambas as linguagens.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // Tipos e assinaturas Rust expostos ao C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // Tipos e assinaturas C++ expostos ao Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Declarações de Bridge Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // Tipo opaco
        fn foo(&self); // Método em `MyType`
        fn bar() -> Box<MyType>; // Função livre
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

C++ Gerado

#[cxx::bridge]
mod ffi {
    // Tipos e assinaturas Rust expostos ao C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

Resulta (aproximadamente) no seguinte C++:

struct MultiBuf final : public ::rust::Opaque {
  ~MultiBuf() = delete;

private:
  friend ::rust::layout;
  struct layout {
    static ::std::size_t size() noexcept;
    static ::std::size_t align() noexcept;
  };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

Declarações de Bridge C++

#[cxx::bridge]
mod ffi {
    // Tipos e assinaturas C++ expostos ao Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

Resulta (aproximadamente) no seguinte Rust:

#[repr(C)]
pub struct BlobstoreClient {
    _private: ::cxx::private::Opaque,
}

pub fn new_blobstore_client() -> ::cxx::UniquePtr<BlobstoreClient> {
    extern "C" {
        #[link_name = "org$blobstore$cxxbridge1$new_blobstore_client"]
        fn __new_blobstore_client() -> *mut BlobstoreClient;
    }
    unsafe { ::cxx::UniquePtr::from_raw(__new_blobstore_client()) }
}

impl BlobstoreClient {
    pub fn put(&self, parts: &mut MultiBuf) -> u64 {
        extern "C" {
            #[link_name = "org$blobstore$cxxbridge1$BlobstoreClient$put"]
            fn __put(
                _: &BlobstoreClient,
                parts: *mut ::cxx::core::ffi::c_void,
            ) -> u64;
        }
        unsafe {
            __put(self, parts as *mut MultiBuf as *mut ::cxx::core::ffi::c_void)
        }
    }
}

// ...

Tipos Compartilhados

#[cxx::bridge]
mod ffi {
    #[derive(Clone, Debug, Hash)]
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1, J=11, Q=12, K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Enums Compartilhados

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Rust gerado:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
    pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
    pub const Clubs: Self = Suit { repr: 0 };
    pub const Diamonds: Self = Suit { repr: 1 };
    pub const Hearts: Self = Suit { repr: 2 };
    pub const Spades: Self = Suit { repr: 3 };
}
}

C++ gerado:

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

Tratamento de Erros do Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 requer profundidade > 0"));
    }

    Ok("Sucesso!".into())
}

Tratamento de Erros do C++

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Erro: {}", err);
        process::exit(1);
    }
}

Tipos Adicionais

Compilando no Android

Crie uma cc_library_static para compilar a biblioteca C++, incluindo o cabeçalho e o arquivo de origem gerados pelo CXX.

cc_library_static {
    name: "libcxx_test_cpp",
    srcs: ["cxx_test.cpp"],
    generated_headers: [
        "cxx-bridge-header",
        "libcxx_test_bridge_header"
    ],
    generated_sources: ["libcxx_test_bridge_code"],
}

Compilando no Android

Crie duas regras de geração: uma para gerar o cabeçalho CXX e outra para gerar o arquivo de origem CXX. Estes são então usados como entradas para a cc_library_static.

// Gera um cabeçalho C++ contendo as vinculações C++
// para as funções exportadas do Rust em lib.rs.
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Gera o código C++ que o Rust chama.
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

Compilando no Android

Crie um rust_binary que depende de libcxx e sua cc_library_static.

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

Interoperabilidade com Java

Java pode carregar objetos compartilhados via Java Native Interface (JNI). O crate jni permite que você crie uma biblioteca compatível.

Primeiro, criamos uma função Rust para exportar para Java:

interoperability/java/src/lib.rs:

#![allow(unused)]
fn main() {
//! Rust <-> Java FFI demo.

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// Implementação do método HelloWorld::hello.
#[no_mangle]
pub extern "system" fn Java_HelloWorld_hello(
    env: JNIEnv,
    _class: JClass,
    name: JString,
) -> jstring {
    let input: String = env.get_string(name).unwrap().into();
    let greeting = format!("Olá, {input}!");
    let output = env.new_string(greeting).unwrap();
    output.into_inner()
}
}

interoperability/java/Android.bp:

rust_ffi_shared {
    name: "libhello_jni",
    crate_name: "hello_jni",
    srcs: ["src/lib.rs"],
    rustlibs: ["libjni"],
}

We then call this function from Java:

interoperability/java/HelloWorld.java:

class HelloWorld {
    private static native String hello(String name);

    static {
        System.loadLibrary("hello_jni");
    }

    public static void main(String[] args) {
        String output = HelloWorld.hello("Alice");
        System.out.println(output);
    }
}

interoperability/java/Android.bp:

java_binary {
    name: "helloworld_jni",
    srcs: ["HelloWorld.java"],
    main_class: "HelloWorld",
    required: ["libhello_jni"],
}

Por fim, você pode criar, sincronizar e executar o binário:

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

Exercícios

Este é um exercício em grupo: Nós iremos ver um dos projetos com os quais você trabalha e tentar integrar um pouco de Rust nele. Algumas sugestões:

• Chame seu serviço AIDL com um cliente escrito em Rust.

• Mova uma função do seu projeto para o Rust e a chame.

Bem-vindo ao Rust para Chromium

O Rust é suportado para bibliotecas de terceiros no Chromium, com código original para conectar com o código C++ existente do Chromium.

Hoje, chamaremos o Rust para fazer algo simples com strings. Se você tem um pedacinho do código onde é exibida uma string UTF8 para o usuário, sinta-se à vontade para seguir esta receita em sua parte do código-fonte em vez da parte exata sobre a qual falamos.

Configuração

Certifique-se de que você pode compilar e executar o Chromium. Qualquer plataforma e conjunto de flags de compilação está OK, desde que seu código seja relativamente recente (posição de commit 1223636 em diante, correspondendo a novembro de 2023):

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

(Um componente, compilação de debug é recomendado para o tempo de iteração mais rápido. Este é o padrão!)

Veja Como compilar o Chromium se você ainda não estiver nesse ponto. Atenção: configurar a compilação do Chromium leva tempo.

Também é recomendável que você tenha o Visual Studio Code instalado.

Sobre os exercícios

Esta parte do curso tem uma série de exercícios que se complementam. Faremo-os ao longo do curso em vez de apenas no final. Se você não tiver tempo para concluir uma determinada parte, não se preocupe: você pode alcançar no próximo slot.

Comparando os Ecossistemas do Chromium e do Cargo

A comunidade Rust normalmente usa cargo e bibliotecas de crates.io. O Chromium é compilado usando gn e ninja e um conjunto de dependências selecionadas.

Ao escrever código em Rust, suas escolhas são:

• Use gn e ninja com a ajuda dos templates de //build/rust/*.gni (por exemplo, rust_static_library que veremos mais adiante). Isso usa o conjunto de ferramentas e crates auditados do Chromium.
• Use cargo, mas restrinja-se ao conjunto de ferramentas e crates auditados do Chromium
• Use cargo, confiando em um conjunto de ferramentas e/ou crates baixados da internet

Daqui em diante, estaremos focando em gn e ninja, porque é assim que o código Rust pode ser compilado no navegador Chromium. Ao mesmo tempo, o Cargo é uma parte importante do ecossistema Rust e você deve mantê-lo em sua caixa de ferramentas.

Mini exercício

Dividam-se em pequenos grupos e:

• Faça um brainstorm de cenários em que o cargo pode oferecer uma vantagem e avalie o perfil de risco desses cenários.
• Discuta quais ferramentas, bibliotecas e grupos de pessoas precisam ser confiáveis ao usar gn e ninja, cargo offline, etc.

Política do Rust para Chromium

O Chromium ainda não permite que Rust seja utlizado diretamente, exceto em casos raros, conforme aprovado pelos Area Tech Leads do Chromium.

A política do Chromium sobre bibliotecas de terceiros é descrita aqui - o Rust é permitido para bibliotecas de terceiros em várias circunstâncias, incluindo se forem a melhor opção para desempenho ou para segurança.

Muito poucas bibliotecas Rust expõem diretamente uma API C/C++, o que significa que quase todas essas bibliotecas exigirão diretamente um pouco de código de integração.

O código próprio de integração Rust para um determinado crate de terceiros deve ser mantido normalmente em third_party/rust/<crate>/<version>/wrapper.

Por causa disso, o curso de hoje será fortemente focado em:

• Trabalhando com bibliotecas Rust de terceiros (“crates”)
• Escrevendo código de integração para poder usar esses crates a partir do C++ do Chromium.

Se essa política mudar com o tempo, o curso evoluirá para acompanhar.

Regras de Compilação

O código Rust geralmente é compilado usando cargo. O Chromium é compilado com gn e ninja para eficiência — suas regras estáticas permitem a máxima paralelização. O Rust não é exceção.

Adicionando código Rust ao Chromium

Em algum arquivo BUILD.gn existente do Chromium, declare um rust_static_library:

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

Você também pode adicionar deps em outros módulos Rust. Mais tarde, usaremos isso para depender de código de terceiros.

Incluindo código Rust unsafe (inseguro)

O código Rust inseguro é proibido em rust_static_library por padrão — não será compilado. Se você precisar de código Rust inseguro, adicione allow_unsafe = true ao alvo gn. (Mais tarde no curso, veremos circunstâncias em que isso é necessário).

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [
    "lib.rs",
    "hippopotamus.rs"
  ]
  allow_unsafe = true
}

Dependendo de Código Rust do C++ do Chromium

Basta adicionar o alvo acima às deps de algum alvo C++ do Chromium.

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

# or source_set, static_library etc.
component("preexisting_cpp") {
  deps = [ ":my_rust_lib" ]
}

Visual Studio Code

Os tipos são omitidos no código Rust, o que torna um bom IDE ainda mais útil do que para C++. O Visual Studio Code funciona bem para Rust no Chromium. Para usá-lo,

• Verifique se o seu VSCode tem a extensão rust-analyzer, não as formas anteriores de suporte ao Rust
• gn gen out/Debug --export-rust-project (ou equivalente para seu diretório de saída)
• ln -s out/Debug/rust-project.json rust-project.json

Exercício de regras de compilação

Em sua compilação do Chromium, adicione um novo módulo Rust a //ui/base/BUILD.gn contendo:

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("Olá do Rust!")
}
}

Importante: observe que no_mangle aqui é considerado um tipo de insegurança pelo compilador Rust, portanto, você precisará permitir código inseguro em seu alvo gn.

Adicione este novo módulo Rust como uma dependência de //ui/base:base. Declare esta função no topo de ui/base/resource/resource_bundle.cc (mais tarde, veremos como isso pode ser automatizado por ferramentas de geração de bindings):

extern "C" void hello_from_rust();

Chame esta função de algum lugar em ui/base/resource/resource_bundle.cc - sugerimos o topo de ResourceBundle::MaybeMangleLocalizedString. Compile e execute o Chromium e verifique se “Hello from Rust!” é impresso muitas vezes.

Se você usar o VSCode, agora configure o Rust para funcionar bem no VSCode. Isto será útil nos exercícios subsequentes. Se você tiver sucesso, poderá usar o botão direito do mouse em “Ir para definição” em println!.

Onde encontrar ajuda

• As opções disponíveis para o rust_static_library gn template
• Informações sobre #[no_mangle]
• Informações sobre extern "C"
• Informações sobre o --export-rust-project do gn
• Como instalar o rust-analyzer no VSCode

Testando

A comunidade Rust normalmente escreve testes unitários em um módulo colocado no mesmo arquivo de código sendo testado. Isso foi abordado anteriormente no curso e se parece com isso:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

No Chromium, colocamos os testes unitários em um arquivo de código separado e continuamos a seguir essa prática para o Rust — isso torna os testes consistentemente descobríveis e ajuda a evitar a reconstrução de arquivos .rs uma segunda vez (na configuração test).

Isto resulta nas seguintes opções para testar código Rust no Chromium:

• Testes nativos Rust (ou seja, #[test]). Desencorajado fora de //third_party/rust.
• Testes gtest escritos em C++ e exercitando Rust via chamadas FFI. Suficiente quando o código Rust é apenas uma camada FFI fina e os testes unitários existentes fornecem cobertura suficiente para o recurso.
• Testes gtest escritos em Rust e usando o crate sob teste por meio de sua API pública (usando pub mod for_testing { ... } se necessário). Este é o assunto dos próximos slides.

Biblioteca rust_gtest_interop

A biblioteca [rust_gtest_interop](https://chromium.googlesource.com/chromium/src/+ /main/testing/rust_gtest_interop/README.md) fornece uma maneira de:

• Use uma função Rust como um caso de teste gtest (usando o atributo #[gtest(...)])
• Use expect_eq! e macros semelhantes (semelhantes a assert_eq! mas não falhando e não terminando o teste quando a asserção falha).

Exemplo:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

Regras GN para Testes em Rust

A maneira mais simples de compilar testes gtest Rust é adicioná-los a um binário de teste existente que já contém testes escritos em C++. Por exemplo:

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

Escrever testes Rust em uma static_library separada também funciona, mas exige a declaração manual da dependência das bibliotecas de suporte:

rust_static_library("my_rust_lib_unittests") {
  testonly = true
  is_gtest_unittests = true
  crate_root = "my_rust_lib_unittest.rs"
  sources = [ "my_rust_lib_unittest.rs" ]
  deps = [
    ":my_rust_lib",
    "//testing/rust_gtest_interop",
  ]
}

test("ui_base_unittests") {
  ...
  deps += [ ":my_rust_lib_unittests" ]
}

Macro chromium::import!

Depois de adicionar :my_rust_lib às deps do GN, ainda precisamos aprender como importar e usar my_rust_lib de my_rust_lib_unittest.rs. Não fornecemos um crate_name explícito para my_rust_lib, portanto, seu nome de crate é calculado com base no caminho e nome do alvo completo. Felizmente, podemos evitar trabalhar com um nome tão difícil de usar usando o macro chromium::import! do crate chromium automaticamente importado:

chromium::import! {
    "//ui/base:my_rust_lib";
}

use my_rust_lib::my_function_under_test;

Por baixo dos panos, a macro se expande para algo semelhante a:

extern crate ui_sbase_cmy_urust_ulib as my_rust_lib;

use my_rust_lib::my_function_under_test;

Mais informações podem ser encontradas no comentário de documentação da macro chromium::import.

Exercício sobre testes

Hora de mais um exercício!

Em sua compilação do Chromium:

• Adicione uma função testável ao lado de hello_from_rust. Algumas sugestões: adicionar dois inteiros recebidos como argumentos, calcular o n-ésimo número de Fibonacci, somar inteiros em uma slice, etc.
• Adicione um arquivo ..._unittest.rs separado com um teste para a nova função.
• Adicione os novos testes a BUILD.gn.
• Compile os testes, execute-os e verifique se o novo teste funciona.

Interoperabilidade com C++

A comunidade Rust oferece várias opções para interoperabilidade C++/Rust, com novas ferramentas sendo desenvolvidas o tempo todo. No momento, o Chromium usa uma ferramenta chamada CXX.

Você descreve toda a fronteira da linguagem em uma linguagem de definição de interface (que se parece muito com Rust) e, em seguida, as ferramentas CXX geram declarações para funções e tipos em Rust e C++.

Veja o tutorial CXX para um exemplo completo de como usá-lo.

Exemplo de Bindings

O CXX requer que toda a fronteira C++/Rust seja declarada em módulos cxx::bridge dentro do código-fonte .rs.

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("example/include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
    }
}

// Definições de tipos e funções Rust vão aqui

Limitações do CXX

De longe, a página mais útil ao usar o CXX é a referência de tipo.

CXX fundamentalmente é adequado para casos em que: