A Linguagem de Programação Rust (PT-BR)

Melhorando Nosso Projeto de E/S

Com esse novo conhecimento sobre iteradores, podemos melhorar o projeto de E/S do Capítulo 12 usando iteradores para tornar partes do código mais claras e mais concisas. Vamos ver como iteradores podem melhorar nossa implementação de Config::build e da função search.

Removendo um clone com um Iterador

Na Listagem 12-6, adicionamos código que recebia uma fatia de valores String e criava uma instância da struct Config indexando essa fatia e clonando os valores, para permitir que Config passasse a ser dona desses dados. Na Listagem 13-17, reproduzimos a implementação da função Config::build como ela estava na Listagem 12-23.

use std::env;
use std::error::Error;
use std::fs;
use std::process;

use minigrep::{search, search_case_insensitive};

fn main() {
    let args: Vec<String> = env::args().collect();

    let config = Config::build(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {err}");
        process::exit(1);
    });

    if let Err(e) = run(config) {
        println!("Application error: {e}");
        process::exit(1);
    }
}

pub struct Config {
    pub query: String,
    pub file_path: String,
    pub ignore_case: bool,
}

impl Config {
    fn build(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

        let query = args[1].clone();
        let file_path = args[2].clone();

        let ignore_case = env::var("IGNORE_CASE").is_ok();

        Ok(Config {
            query,
            file_path,
            ignore_case,
        })
    }
}

fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.file_path)?;

    let results = if config.ignore_case {
        search_case_insensitive(&config.query, &contents)
    } else {
        search(&config.query, &contents)
    };

    for line in results {
        println!("{line}");
    }

    Ok(())
}

Na época, dissemos para não se preocupar com as chamadas ineficientes a clone, porque as removeríamos no futuro. Pois bem, esse momento chegou!

Precisávamos de clone porque temos uma fatia com elementos String no parâmetro args, mas a função build não tem ownership de args. Para retornar ownership de uma instância de Config, tivemos de clonar os valores dos campos query e file_path, para que a própria instância de Config passasse a possuí-los.

Com nosso novo conhecimento sobre iteradores, podemos alterar build para receber ownership de um iterador como argumento, em vez de emprestar uma fatia. Vamos usar a funcionalidade dos iteradores no lugar do código que verifica o comprimento da fatia e indexa posições específicas. Isso deixará mais claro o que Config::build está fazendo, porque será o iterador que acessará os valores.

Quando Config::build passar a tomar ownership do iterador e deixar de usar operações de indexação que fazem empréstimos, poderemos mover os valores String do iterador para Config, em vez de chamar clone e fazer uma nova alocação.

Usando Diretamente o Iterador Retornado

Abra o arquivo src/main.rs do seu projeto de E/S, que deve se parecer com isto:

Arquivo: src/main.rs

use std::env;
use std::error::Error;
use std::fs;
use std::process;

use minigrep::{search, search_case_insensitive};

fn main() {
    let args: Vec<String> = env::args().collect();

    let config = Config::build(&args).unwrap_or_else(|err| {
        eprintln!("Problem parsing arguments: {err}");
        process::exit(1);
    });

    // --snip--

    if let Err(e) = run(config) {
        eprintln!("Application error: {e}");
        process::exit(1);
    }
}

pub struct Config {
    pub query: String,
    pub file_path: String,
    pub ignore_case: bool,
}

impl Config {
    fn build(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

        let query = args[1].clone();
        let file_path = args[2].clone();

        let ignore_case = env::var("IGNORE_CASE").is_ok();

        Ok(Config {
            query,
            file_path,
            ignore_case,
        })
    }
}

fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.file_path)?;

    let results = if config.ignore_case {
        search_case_insensitive(&config.query, &contents)
    } else {
        search(&config.query, &contents)
    };

    for line in results {
        println!("{line}");
    }

    Ok(())
}

Primeiro, vamos alterar o início da função main, que estava na Listagem 12-24, para o código da Listagem 13-18, que desta vez usa um iterador. Isso ainda não compilará até que atualizemos também Config::build.

use std::env;
use std::error::Error;
use std::fs;
use std::process;

use minigrep::{search, search_case_insensitive};

fn main() {
    let config = Config::build(env::args()).unwrap_or_else(|err| {
        eprintln!("Problem parsing arguments: {err}");
        process::exit(1);
    });

    // --snip--

    if let Err(e) = run(config) {
        eprintln!("Application error: {e}");
        process::exit(1);
    }
}

pub struct Config {
    pub query: String,
    pub file_path: String,
    pub ignore_case: bool,
}

impl Config {
    fn build(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

        let query = args[1].clone();
        let file_path = args[2].clone();

        let ignore_case = env::var("IGNORE_CASE").is_ok();

        Ok(Config {
            query,
            file_path,
            ignore_case,
        })
    }
}

fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.file_path)?;

    let results = if config.ignore_case {
        search_case_insensitive(&config.query, &contents)
    } else {
        search(&config.query, &contents)
    };

    for line in results {
        println!("{line}");
    }

    Ok(())
}

A função env::args retorna um iterador! Em vez de coletar os valores do iterador em um vetor e depois passar uma fatia para Config::build, agora estamos passando diretamente para Config::build o ownership do iterador retornado por env::args.

Em seguida, precisamos atualizar a definição de Config::build. Vamos alterar a assinatura de Config::build para que se pareça com a Listagem 13-19. Isso ainda não compilará, porque também precisamos atualizar o corpo da função.

use std::env;
use std::error::Error;
use std::fs;
use std::process;

use minigrep::{search, search_case_insensitive};

fn main() {
    let config = Config::build(env::args()).unwrap_or_else(|err| {
        eprintln!("Problem parsing arguments: {err}");
        process::exit(1);
    });

    if let Err(e) = run(config) {
        eprintln!("Application error: {e}");
        process::exit(1);
    }
}

pub struct Config {
    pub query: String,
    pub file_path: String,
    pub ignore_case: bool,
}

impl Config {
    fn build(
        mut args: impl Iterator<Item = String>,
    ) -> Result<Config, &'static str> {
        // --snip--
        if args.len() < 3 {
            return Err("not enough arguments");
        }

        let query = args[1].clone();
        let file_path = args[2].clone();

        let ignore_case = env::var("IGNORE_CASE").is_ok();

        Ok(Config {
            query,
            file_path,
            ignore_case,
        })
    }
}

fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.file_path)?;

    let results = if config.ignore_case {
        search_case_insensitive(&config.query, &contents)
    } else {
        search(&config.query, &contents)
    };

    for line in results {
        println!("{line}");
    }

    Ok(())
}

A documentação da biblioteca padrão para env::args mostra que o tipo do iterador que ela retorna é std::env::Args, e esse tipo implementa a trait Iterator, retornando valores String.

Atualizamos a assinatura de Config::build para que o parâmetro args tenha um tipo genérico com os limites de trait impl Iterator<Item = String>, em vez de &[String]. Esse uso da sintaxe impl Trait, discutido na seção “Usando Traits como Parâmetros” do Capítulo 10, significa que args pode ser qualquer tipo que implemente a trait Iterator e retorne itens do tipo String.

Como estamos tomando ownership de args e vamos modificá-lo ao iterar sobre ele, podemos adicionar a palavra-chave mut à especificação do parâmetro args para torná-lo mutável.

Usando Métodos da Trait Iterator

Agora vamos corrigir o corpo de Config::build. Como args implementa a trait Iterator, sabemos que podemos chamar next nele! A Listagem 13-20 atualiza o código da Listagem 12-23 para usar o método next.

use std::env;
use std::error::Error;
use std::fs;
use std::process;

use minigrep::{search, search_case_insensitive};

fn main() {
    let config = Config::build(env::args()).unwrap_or_else(|err| {
        eprintln!("Problem parsing arguments: {err}");
        process::exit(1);
    });

    if let Err(e) = run(config) {
        eprintln!("Application error: {e}");
        process::exit(1);
    }
}

pub struct Config {
    pub query: String,
    pub file_path: String,
    pub ignore_case: bool,
}

impl Config {
    fn build(
        mut args: impl Iterator<Item = String>,
    ) -> Result<Config, &'static str> {
        args.next();

        let query = match args.next() {
            Some(arg) => arg,
            None => return Err("Didn't get a query string"),
        };

        let file_path = match args.next() {
            Some(arg) => arg,
            None => return Err("Didn't get a file path"),
        };

        let ignore_case = env::var("IGNORE_CASE").is_ok();

        Ok(Config {
            query,
            file_path,
            ignore_case,
        })
    }
}

fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.file_path)?;

    let results = if config.ignore_case {
        search_case_insensitive(&config.query, &contents)
    } else {
        search(&config.query, &contents)
    };

    for line in results {
        println!("{line}");
    }

    Ok(())
}

Lembre-se de que o primeiro valor retornado por env::args é o nome do programa. Queremos ignorá-lo e chegar ao próximo valor, então primeiro chamamos next e não fazemos nada com o valor retornado. Em seguida, chamamos next para obter o valor que queremos colocar no campo query de Config. Se next retornar Some, usamos um match para extrair o valor. Se retornar None, isso significa que não foram fornecidos argumentos suficientes, e retornamos imediatamente com um valor Err. Fazemos a mesma coisa para o valor file_path.

Tornando o Código Mais Claro com Adaptadores de Iteradores

Também podemos tirar proveito de iteradores na função search do nosso projeto de E/S, reproduzida aqui na Listagem 13-21 como ela aparecia na Listagem 12-19.

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    let mut results = Vec::new();

    for line in contents.lines() {
        if line.contains(query) {
            results.push(line);
        }
    }

    results
}

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

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }
}

Podemos escrever esse código de forma mais concisa usando métodos adaptadores de iteradores. Isso também nos permite evitar um vetor intermediário mutável, results. O estilo de programação funcional prefere minimizar a quantidade de estado mutável para tornar o código mais claro. Remover esse estado mutável pode até permitir uma melhoria futura que torne a busca paralela, porque não teríamos de gerenciar acesso concorrente ao vetor results. A Listagem 13-22 mostra essa mudança.

pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    contents
        .lines()
        .filter(|line| line.contains(query))
        .collect()
}

pub fn search_case_insensitive<'a>(
    query: &str,
    contents: &'a str,
) -> Vec<&'a str> {
    let query = query.to_lowercase();
    let mut results = Vec::new();

    for line in contents.lines() {
        if line.to_lowercase().contains(&query) {
            results.push(line);
        }
    }

    results
}

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

    #[test]
    fn case_sensitive() {
        let query = "duct";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";

        assert_eq!(
            vec!["Rust:", "Trust me."],
            search_case_insensitive(query, contents)
        );
    }
}

Lembre-se de que o objetivo da função search é retornar todas as linhas de contents que contêm query. De forma semelhante ao exemplo de filter na Listagem 13-16, esse código usa o adaptador filter para manter apenas as linhas para as quais line.contains(query) retorna true. Em seguida, coletamos as linhas correspondentes em outro vetor com collect. Muito mais simples! Sinta-se à vontade para fazer a mesma mudança na função search_case_insensitive.

Para uma melhoria adicional, você pode fazer a função search retornar um iterador removendo a chamada a collect e mudando o tipo de retorno para impl Iterator<Item = &'a str>, de modo que a própria função se torne um adaptador de iterador. Observe que você também precisará atualizar os testes! Pesquise em um arquivo grande usando sua ferramenta minigrep antes e depois de fazer essa alteração para observar a diferença de comportamento. Antes dessa mudança, o programa não imprimirá nenhum resultado até ter coletado todos eles; depois, os resultados serão impressos à medida que cada linha correspondente for encontrada, porque o laço for na função run poderá tirar proveito da natureza preguiçosa do iterador.

Escolhendo entre Laços e Iteradores

A próxima pergunta lógica é qual estilo você deve escolher no seu próprio código e por quê: a implementação original da Listagem 13-21 ou a versão com iteradores da Listagem 13-22, assumindo que estamos coletando todos os resultados antes de devolvê-los, em vez de retornar o iterador. A maioria das pessoas que programam em Rust prefere o estilo com iteradores. Pode ser um pouco mais difícil de pegar o jeito no começo, mas, depois que você se familiariza com os vários adaptadores e com o que eles fazem, os iteradores podem ser mais fáceis de entender. Em vez de lidar com todos os detalhes de controle do laço e da construção de novos vetores, o código se concentra no objetivo de alto nível da operação. Isso abstrai parte do código rotineiro e facilita enxergar os conceitos realmente únicos daquele trecho, como a condição de filtragem que cada elemento precisa satisfazer.

Mas será que as duas implementações são realmente equivalentes? A intuição pode levar você a supor que o laço de nível mais baixo será mais rápido. Vamos falar sobre desempenho.