Pular para o conteúdo
Rust em Português

Lição 13 de 18 · 30 min

Option e Result

Trate valores que podem faltar e operações que podem falhar sem null e sem exceção: Option, Result, unwrap, expect e o operador ?.

Ao terminar, você vai saber:

  • Usar Option para representar um valor que pode não existir
  • Tratar erros com Result e match
  • Saber quando unwrap e expect são aceitáveis e quando evitar
  • Propagar erros com o operador ?
  • Criar um tipo de erro próprio simples e fazer a main retornar Result

Muitas linguagens têm um valor especial chamado null (ou nil, ou None) para dizer “aqui não tem nada”. O problema é que qualquer variável pode ser null, e você só descobre quando o programa quebra. O criador do null chegou a chamá-lo de “erro de um bilhão de dólares”.

O Rust não tem null. No lugar, tem dois enums da biblioteca padrão que você vai usar o tempo todo: Option e Result.

Option: pode ter, pode não ter

O Option é definido mais ou menos assim:

enum Option<T> {
    Some(T),
    None,
}

O <T> quer dizer “qualquer tipo”. Option<i32> é “talvez um número”, Option<String> é “talvez um texto”. Esse assunto volta em Traits e genéricos.

Muitas funções da biblioteca padrão devolvem Option. Por exemplo, buscar um item numa lista:

fn buscar_preco(produto: &str) -> Option<f64> {
    match produto {
        "pão francês" => Some(0.75),
        "café" => Some(5.50),
        "sonho" => Some(6.50),
        _ => None,
    }
}

fn main() {
    for item in ["café", "croissant"] {
        match buscar_preco(item) {
            Some(preco) => println!("{item}: R$ {preco:.2}"),
            None => println!("{item}: não temos"),
        }
    }
}

O ponto principal: um Option<f64> não é um f64. Você não consegue somar um Option<f64> com um número. O compilador obriga você a abrir a caixa e decidir o que fazer com o None.

fn main() {
    let preco: Option<f64> = Some(5.50);
    let total = preco * 2.0;
    println!("{total}");
}
error[E0369]: cannot multiply `Option<f64>` by `{float}`
  |     let total = preco * 2.0;
  |                 ----- ^ --- {float}
  |                 |
  |                 Option<f64>

Além do match, há métodos práticos:

fn main() {
    let desconto: Option<f64> = None;

    // Valor padrão se for None
    let d = desconto.unwrap_or(0.0);
    println!("Desconto: {d}");

    // if let quando só o Some interessa
    let cupom = Some("BLACKFRIDAY");
    if let Some(codigo) = cupom {
        println!("Cupom aplicado: {codigo}");
    }

    // Saber se tem algo
    println!("Tem desconto? {}", desconto.is_some());
}

Result: deu certo ou deu errado

O Option diz “tem ou não tem”. O Result diz “deu certo, e aqui está o valor” ou “deu errado, e aqui está o motivo”:

enum Result<T, E> {
    Ok(T),
    Err(E),
}

Um exemplo clássico é converter texto em número. O usuário pode digitar qualquer coisa:

fn main() {
    let entradas = ["42", "doze", "-7"];

    for texto in entradas {
        match texto.parse::<i32>() {
            Ok(numero) => println!("{texto} virou {numero}"),
            Err(erro) => println!("{texto} não é número: {erro}"),
        }
    }
}

O parse devolve Result<i32, ParseIntError>. Nada de exceção escondida. O tipo de retorno avisa, por escrito, que a operação pode falhar.

unwrap e expect: quando evitar

unwrap abre a caixa na marra. Se for Some ou Ok, devolve o valor. Se for None ou Err, o programa para com um panic!.

fn main() {
    let idade: u32 = "35".parse().unwrap(); // funciona
    println!("Idade: {idade}");

    // Com expect, você escolhe a mensagem do panic
    let ano: u32 = "2026".parse().expect("o ano deveria ser um número");
    println!("Ano: {ano}");
}

Se a entrada fosse "trinta", o programa pararia com uma mensagem assim:

thread 'main' panicked at src/main.rs:2:39:
called `Result::unwrap()` on an `Err` value: ParseIntError { kind: InvalidDigit }

Quando usar:

  • Em exemplos rápidos, testes e protótipos, tudo bem.
  • Quando você sabe que não falha e pode explicar por quê. Aí prefira expect com a explicação.
  • Com dado que vem de fora (usuário, arquivo, rede), evite. Trate o erro.

O operador ?

Imagine uma função que lê duas notas em texto e devolve a média. Com match em tudo, fica assim:

use std::num::ParseFloatError;

fn media(a: &str, b: &str) -> Result<f64, ParseFloatError> {
    let nota_a = match a.parse::<f64>() {
        Ok(n) => n,
        Err(e) => return Err(e),
    };
    let nota_b = match b.parse::<f64>() {
        Ok(n) => n,
        Err(e) => return Err(e),
    };
    Ok((nota_a + nota_b) / 2.0)
}

fn main() {
    println!("{:?}", media("7.5", "9"));
}

Esse padrão (“se deu certo, pega o valor; se deu erro, devolve o erro”) é tão comum que virou um símbolo: o ?.

use std::num::ParseFloatError;

fn media(a: &str, b: &str) -> Result<f64, ParseFloatError> {
    let nota_a: f64 = a.parse()?;
    let nota_b: f64 = b.parse()?;
    Ok((nota_a + nota_b) / 2.0)
}

fn main() {
    println!("{:?}", media("7.5", "9"));
    println!("{:?}", media("7.5", "nove"));
}

As duas versões fazem a mesma coisa. O ? só funciona dentro de função que também devolve Result (ou Option, quando o valor for Option).

Erro próprio simples

Nem todo erro vem da biblioteca padrão. Às vezes a regra é sua: um saque maior que o saldo, por exemplo. Um enum resolve bem.

#[derive(Debug)]
enum ErroSaque {
    ValorInvalido,
    SaldoInsuficiente { falta: f64 },
}

fn sacar(saldo: f64, valor: f64) -> Result<f64, ErroSaque> {
    if valor <= 0.0 {
        return Err(ErroSaque::ValorInvalido);
    }
    if valor > saldo {
        return Err(ErroSaque::SaldoInsuficiente { falta: valor - saldo });
    }
    Ok(saldo - valor)
}

fn main() {
    for valor in [50.0, -10.0, 500.0] {
        match sacar(200.0, valor) {
            Ok(novo) => println!("Saque de R$ {valor:.2}. Saldo: R$ {novo:.2}"),
            Err(ErroSaque::ValorInvalido) => println!("Valor inválido: {valor}"),
            Err(ErroSaque::SaldoInsuficiente { falta }) => {
                println!("Faltam R$ {falta:.2} para sacar R$ {valor:.2}")
            }
        }
    }
}

Quem chama a função sabe, pelo tipo, todos os erros possíveis. E o match obriga a tratar cada um.

main retornando Result

A main também pode devolver Result. Assim dá para usar ? direto nela. Se um erro chegar até o fim, o programa termina com código de erro e mostra o erro na tela.

use std::num::ParseIntError;

fn main() -> Result<(), ParseIntError> {
    let quantidade: u32 = "12".parse()?;
    let preco_centavos: u32 = "75".parse()?;

    let total = quantidade * preco_centavos;
    println!("Total: R$ {},{:02}", total / 100, total % 100);
    Ok(())
}

O () é o tipo vazio: “deu certo e não tenho nada para devolver”. Por isso a última linha é Ok(()).

Resumo

  • O Rust não tem null. Valor que pode faltar é Option: Some(valor) ou None.
  • Operação que pode falhar devolve Result: Ok(valor) ou Err(erro).
  • O compilador obriga você a tratar o caso ruim antes de usar o valor.
  • unwrap e expect causam panic! no caso ruim. Evite com dado que vem de fora.
  • ? devolve o erro na hora e segue com o valor se deu certo.
  • Um enum é um ótimo tipo de erro próprio, e a main pode devolver Result.

Desafio

Escreva fn validar_cpf(cpf: &str) -> Result<String, ErroCpf> que aceita CPF com ou sem pontos e traço, remove a pontuação e confere só duas coisas: se sobraram 11 caracteres e se todos são dígitos. Crie o enum ErroCpf com TamanhoErrado(usize) e CaractereInvalido(char). (Não precisa conferir os dígitos verificadores.)

Ver uma resposta
#[derive(Debug)]
enum ErroCpf {
    TamanhoErrado(usize),
    CaractereInvalido(char),
}

fn validar_cpf(cpf: &str) -> Result<String, ErroCpf> {
    let mut digitos = String::new();

    for c in cpf.chars() {
        if c == '.' || c == '-' {
            continue; // pontuação é permitida, só ignora
        }
        if !c.is_ascii_digit() {
            return Err(ErroCpf::CaractereInvalido(c));
        }
        digitos.push(c);
    }

    if digitos.len() != 11 {
        return Err(ErroCpf::TamanhoErrado(digitos.len()));
    }
    Ok(digitos)
}

fn main() {
    for entrada in ["123.456.789-09", "12345678909", "123.456", "123.45a.789-09"] {
        match validar_cpf(entrada) {
            Ok(limpo) => println!("{entrada}: ok ({limpo})"),
            Err(erro) => println!("{entrada}: {:?}", erro),
        }
    }
}
Salvo só neste navegador.