Brazilian Utils - Rust

Português | English

---

Português

Uma biblioteca Rust que fornece funções utilitárias para validação, formatação e geração de dados específicos do Brasil.

Funcionalidades

Esta biblioteca fornece utilitários abrangentes para manipular documentos, identificadores e formatos de dados brasileiros:

📋 Validação e Formatação de Documentos

• CPF (Cadastro de Pessoas Físicas) - Registro de Contribuinte Individual
• CNPJ (Cadastro Nacional da Pessoa Jurídica) - Registro Nacional de Pessoas Jurídicas
• CNH (Carteira Nacional de Habilitação) - Carteira de Motorista Nacional
• PIS (Programa de Integração Social) - Programa de Integração Social
• Título de Eleitor - Registro Eleitoral

🚗 Veículos e Transporte

• Placas de Veículo - Validação e conversão de formatos antigo e Mercosul
• RENAVAM (Registro Nacional de Veículos Automotores) - Registro Nacional de Veículos

🏛️ Legal e Administrativo

• Processo Judicial - Números de processo do sistema jurídico brasileiro
• Natureza Jurídica - Classificação de entidades jurídicas (60+ códigos oficiais)

📍 Localização e Comunicação

• CEP (Código de Endereçamento Postal) - Código Postal com busca de endereço
• Telefone - Validação de celular e fixo com formatação

💰 Financeiro e Texto

• Boleto - Validação de linha digitável de boleto bancário
• Moeda - Formatação de Real (BRL) e conversão para texto
• Utilitários de Data - Verificação de feriados e conversão de data para texto
• Email - Validação compatível com RFC 5322

Instalação

Adicione ao seu Cargo.toml:

[dependencies]
brazilian_utils = "0.1.0"

Exemplos de Uso

Validação e Formatação de CPF

use brazilian_utils::cpf;

// Validar
assert!(cpf::is_valid("11144477735"));

// Formatar
let formatado = cpf::format_cpf("11144477735");
assert_eq!(formatado, Some("111.444.777-35".to_string()));

// Gerar CPF válido aleatório
let numero_cpf = cpf::generate();
assert!(cpf::is_valid(&numero_cpf));

Validação e Formatação de CNPJ

use brazilian_utils::cnpj;

// Validar
assert!(cnpj::is_valid("11222333000181"));

// Formatar
let formatado = cnpj::format_cnpj("11222333000181");
assert_eq!(formatado, Some("11.222.333/0001-81".to_string()));

// Gerar CNPJ válido aleatório
let numero_cnpj = cnpj::generate(None);
assert!(cnpj::is_valid(&numero_cnpj));

CEP (Código Postal) com Busca de Endereço

use brazilian_utils::cep;

// Validar
assert!(cep::is_valid("01310200"));

// Formatar
let formatado = cep::format_cep("01310200");
assert_eq!(formatado, Some("01310-200".to_string()));

// Buscar endereço pelo CEP (requer internet)
if let Some(endereco) = cep::get_address_from_cep("01310200") {
    println!("Rua: {}", endereco.street);
    println!("Cidade: {}", endereco.city);
}

Validação de Boleto

use brazilian_utils::boleto;

// Validar linha digitável de boleto
assert!(boleto::is_valid("00190000090114971860168524522114675860000102656"));

// Validar com formatação (espaços e pontos)
assert!(boleto::is_valid("0019000009 01149.718601 68524.522114 6 75860000102656"));

// Validar linha inválida
assert!(!boleto::is_valid("00190000020114971860168524522114675860000102656"));

Placa de Veículo (Antiga e Mercosul)

use brazilian_utils::license_plate;

// Validar formato antigo
assert!(license_plate::is_valid("ABC1234", Some("old")));

// Validar formato Mercosul
assert!(license_plate::is_valid("ABC1D23", Some("mercosul")));

// Converter antiga para Mercosul
let mercosul = license_plate::convert_to_mercosul("ABC1234");
assert_eq!(mercosul, Some("ABC1C34".to_string()));

// Formatar
let formatado = license_plate::format_license_plate("ABC1234");
assert_eq!(formatado, Some("ABC-1234".to_string()));

Formatação e Conversão de Moeda

use brazilian_utils::currency;

// Formatar como moeda
let formatado = currency::format_currency(1234.56);
assert_eq!(formatado, "R$ 1.234,56");

// Converter para texto
let texto = currency::convert_real_to_text(1234.56);
assert_eq!(texto, "mil duzentos e trinta e quatro reais e cinquenta e seis centavos");

Validação de Número de Telefone

use brazilian_utils::phone;

// Validar celular
assert!(phone::is_valid("11987654321", Some("mobile")));

// Validar fixo
assert!(phone::is_valid("1133334444", Some("landline")));

// Formatar
let formatado = phone::format_phone("11987654321");
assert_eq!(formatado, Some("(11) 98765-4321".to_string()));

// Gerar aleatório
let numero_telefone = phone::generate(Some("mobile"));
assert!(phone::is_valid(&numero_telefone, Some("mobile")));

Título de Eleitor

use brazilian_utils::voter_id;

// Validar
assert!(voter_id::is_valid("690847092828"));

// Formatar
let formatado = voter_id::format_voter_id("690847092828");
assert_eq!(formatado, Some("6908 4709 28 28".to_string()));

// Gerar para um estado específico
let titulo_sp = voter_id::generate(Some("SP")).unwrap();
assert!(voter_id::is_valid(&titulo_sp));

Número de Processo Judicial

use brazilian_utils::legal_process;

// Validar
assert!(legal_process::is_valid("00000000020248140141"));

// Formatar
let formatado = legal_process::format_legal_process("00000000020248140141");
assert_eq!(formatado, Some("0000000-00.2024.8.14.0141".to_string()));

// Gerar aleatório
let processo = legal_process::generate(Some(("8", "14", "0141")));
assert!(legal_process::is_valid(&processo.unwrap()));

Utilitários de Data

use brazilian_utils::date_utils;
use chrono::NaiveDate;

// Verificar se é feriado
let natal = NaiveDate::from_ymd_opt(2024, 12, 25).unwrap();
assert!(date_utils::is_holiday(&natal, None));

// Converter data para texto
let data = NaiveDate::from_ymd_opt(2024, 1, 15).unwrap();
let texto = date_utils::convert_date_to_text(&data);
assert_eq!(texto, Some("15 de janeiro de 2024".to_string()));

Todos os Módulos Disponíveis

Módulo	Funções	Descrição
boleto	is_valid, validate	Validação de linha digitável de boleto
cep	is_valid, format_cep, remove_symbols, generate, get_address_from_cep, get_cep_information_from_address	Validação de CEP e busca de endereço
cnh	is_valid_cnh	Validação de CNH
cnpj	is_valid, validate, format_cnpj, remove_symbols, generate, hashdigit, compute_checksum	Validação de registro empresarial
cpf	is_valid, validate, format_cpf, remove_symbols, generate, hashdigit, compute_checksum	Validação de CPF
currency	format_currency, convert_real_to_text, number_to_words	Formatação e conversão de moeda
date_utils	is_holiday, convert_date_to_text	Utilitários de data e verificação de feriados
email	is_valid	Validação de email RFC 5322
legal_nature	is_valid, get_description, list_all	Códigos de natureza jurídica (60+ códigos)
legal_process	is_valid, format_legal_process, remove_symbols, generate	Validação de número de processo
license_plate	is_valid, format_license_plate, remove_symbols, convert_to_mercosul, get_format, generate	Placa de veículo (antiga/Mercosul)
phone	is_valid, format_phone, remove_symbols, generate, remove_international_dialing_code	Validação de telefone
pis	is_valid, format_pis, remove_symbols, generate, checksum	Número de integração social
renavam	is_valid, generate, calculate_checksum	Número de registro de veículo
voter_id	is_valid, format_voter_id, generate, calculate_vd1, calculate_vd2	Validação de título de eleitor

Executando Testes

# Executar todos os testes
cargo test

# Executar testes de um módulo específico
cargo test cpf

# Executar com saída detalhada
cargo test -- --nocapture

Executando Exemplos

A biblioteca inclui exemplos de demonstração abrangentes para cada módulo:

# Demonstração de CPF
cargo run --example cpf_demo

# Demonstração de CNPJ
cargo run --example cnpj_demo

# Demonstração de Placa de Veículo
cargo run --example license_plate_demo

# Demonstração de Título de Eleitor
cargo run --example voter_id_demo

# E muitos mais...

Cobertura de Testes

• 149 testes unitários cobrindo toda a lógica de validação
• 55 testes de documentação garantindo que os exemplos funcionem corretamente
• Total: 204 testes com 100% de aprovação

Dependências

• rand - Geração de números aleatórios
• reqwest - Cliente HTTP para busca de endereço por CEP
• serde / serde_json - Serialização JSON
• chrono - Manipulação de data e hora
• regex - Correspondência de expressões regulares
• unicode-normalization - Normalização de strings

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto está licenciado sob a Licença MIT.

Agradecimentos

Inspirado em brazilian-utils/python - Uma biblioteca Python com utilitários similares para dados brasileiros.

---

English

A Rust library providing utility functions for Brazilian-specific data validation, formatting, and generation.

Features

This library provides comprehensive utilities for handling Brazilian documents, identifiers, and data formats:

📋 Document Validation & Formatting

• CPF (Cadastro de Pessoas Físicas) - Individual Taxpayer Registry
• CNPJ (Cadastro Nacional da Pessoa Jurídica) - National Registry of Legal Entities
• CNH (Carteira Nacional de Habilitação) - National Driver's License
• PIS (Programa de Integração Social) - Social Integration Program
• Voter ID (Título de Eleitor) - Electoral Registration

🚗 Vehicle & Transportation

• License Plate - Old and Mercosul format validation and conversion
• RENAVAM (Registro Nacional de Veículos Automotores) - National Motor Vehicle Registry

🏛️ Legal & Administrative

• Legal Process - Brazilian legal system process numbers
• Legal Nature - Legal entity classification (60+ official codes)

📍 Location & Communication

• CEP (Código de Endereçamento Postal) - Postal Code with address lookup
• Phone - Mobile and landline validation with formatting

💰 Financial & Text

• Boleto - Bank slip digitable line validation
• Currency - Real (BRL) formatting and text conversion
• Date Utils - Holiday checking and date text conversion
• Email - RFC 5322 compliant validation

Installation

Add this to your Cargo.toml:

[dependencies]
brazilian_utils = "0.1.0"

Usage Examples

CPF Validation and Formatting

use brazilian_utils::cpf;

// Validate
assert!(cpf::is_valid("11144477735"));

// Format
let formatted = cpf::format_cpf("11144477735");
assert_eq!(formatted, Some("111.444.777-35".to_string()));

// Generate random valid CPF
let cpf_number = cpf::generate();
assert!(cpf::is_valid(&cpf_number));

CNPJ Validation and Formatting

use brazilian_utils::cnpj;

// Validate
assert!(cnpj::is_valid("11222333000181"));

// Format
let formatted = cnpj::format_cnpj("11222333000181");
assert_eq!(formatted, Some("11.222.333/0001-81".to_string()));

// Generate random valid CNPJ
let cnpj_number = cnpj::generate(None);
assert!(cnpj::is_valid(&cnpj_number));

CEP (Postal Code) with Address Lookup

use brazilian_utils::cep;

// Validate
assert!(cep::is_valid("01310200"));

// Format
let formatted = cep::format_cep("01310200");
assert_eq!(formatted, Some("01310-200".to_string()));

// Get address from CEP (requires internet)
if let Some(address) = cep::get_address_from_cep("01310200") {
    println!("Street: {}", address.street);
    println!("City: {}", address.city);
}

Boleto Validation

use brazilian_utils::boleto;

// Validate boleto digitable line
assert!(boleto::is_valid("00190000090114971860168524522114675860000102656"));

// Validate with formatting (spaces and dots)
assert!(boleto::is_valid("0019000009 01149.718601 68524.522114 6 75860000102656"));

// Validate invalid line
assert!(!boleto::is_valid("00190000020114971860168524522114675860000102656"));

License Plate (Old and Mercosul)

use brazilian_utils::license_plate;

// Validate old format
assert!(license_plate::is_valid("ABC1234", Some("old")));

// Validate Mercosul format
assert!(license_plate::is_valid("ABC1D23", Some("mercosul")));

// Convert old to Mercosul
let mercosul = license_plate::convert_to_mercosul("ABC1234");
assert_eq!(mercosul, Some("ABC1C34".to_string()));

// Format
let formatted = license_plate::format_license_plate("ABC1234");
assert_eq!(formatted, Some("ABC-1234".to_string()));

Currency Formatting and Text Conversion

use brazilian_utils::currency;

// Format as currency
let formatted = currency::format_currency(1234.56);
assert_eq!(formatted, "R$ 1.234,56");

// Convert to text
let text = currency::convert_real_to_text(1234.56);
assert_eq!(text, "mil duzentos e trinta e quatro reais e cinquenta e seis centavos");

Phone Number Validation

use brazilian_utils::phone;

// Validate mobile
assert!(phone::is_valid("11987654321", Some("mobile")));

// Validate landline
assert!(phone::is_valid("1133334444", Some("landline")));

// Format
let formatted = phone::format_phone("11987654321");
assert_eq!(formatted, Some("(11) 98765-4321".to_string()));

// Generate random
let phone_number = phone::generate(Some("mobile"));
assert!(phone::is_valid(&phone_number, Some("mobile")));

Voter ID (Título de Eleitor)

use brazilian_utils::voter_id;

// Validate
assert!(voter_id::is_valid("690847092828"));

// Format
let formatted = voter_id::format_voter_id("690847092828");
assert_eq!(formatted, Some("6908 4709 28 28".to_string()));

// Generate for a specific state
let voter_id_sp = voter_id::generate(Some("SP")).unwrap();
assert!(voter_id::is_valid(&voter_id_sp));

Legal Process Number

use brazilian_utils::legal_process;

// Validate
assert!(legal_process::is_valid("00000000020248140141"));

// Format
let formatted = legal_process::format_legal_process("00000000020248140141");
assert_eq!(formatted, Some("0000000-00.2024.8.14.0141".to_string()));

// Generate random
let process = legal_process::generate(Some(("8", "14", "0141")));
assert!(legal_process::is_valid(&process.unwrap()));

Date Utilities

use brazilian_utils::date_utils;
use chrono::NaiveDate;

// Check if date is a holiday
let christmas = NaiveDate::from_ymd_opt(2024, 12, 25).unwrap();
assert!(date_utils::is_holiday(&christmas, None));

// Convert date to text
let date = NaiveDate::from_ymd_opt(2024, 1, 15).unwrap();
let text = date_utils::convert_date_to_text(&date);
assert_eq!(text, Some("15 de janeiro de 2024".to_string()));

All Available Modules

Module	Functions	Description
boleto	is_valid, validate	Bank slip digitable line validation
cep	is_valid, format_cep, remove_symbols, generate, get_address_from_cep, get_cep_information_from_address	Postal code validation and address lookup
cnh	is_valid_cnh	Driver's license validation
cnpj	is_valid, validate, format_cnpj, remove_symbols, generate, hashdigit, compute_checksum	Company registration validation
cpf	is_valid, validate, format_cpf, remove_symbols, generate, hashdigit, compute_checksum	Individual taxpayer validation
currency	format_currency, convert_real_to_text, number_to_words	Currency formatting and text conversion
date_utils	is_holiday, convert_date_to_text	Date utilities and holiday checking
email	is_valid	RFC 5322 email validation
legal_nature	is_valid, get_description, list_all	Legal entity nature codes (60+ codes)
legal_process	is_valid, format_legal_process, remove_symbols, generate	Legal process number validation
license_plate	is_valid, format_license_plate, remove_symbols, convert_to_mercosul, get_format, generate	Vehicle license plate (old/Mercosul)
phone	is_valid, format_phone, remove_symbols, generate, remove_international_dialing_code	Phone number validation
pis	is_valid, format_pis, remove_symbols, generate, checksum	Social integration number
renavam	is_valid, generate, calculate_checksum	Vehicle registration number
voter_id	is_valid, format_voter_id, generate, calculate_vd1, calculate_vd2	Electoral registration validation

Running Tests

# Run all tests
cargo test

# Run tests for a specific module
cargo test cpf

# Run with output
cargo test -- --nocapture

Running Examples

The library includes comprehensive demo examples for each module:

# CPF demonstration
cargo run --example cpf_demo

# CNPJ demonstration
cargo run --example cnpj_demo

# License Plate demonstration
cargo run --example license_plate_demo

# Voter ID demonstration
cargo run --example voter_id_demo

# And many more...

Test Coverage

• 149 unit tests covering all validation logic
• 55 documentation tests ensuring examples work correctly
• Total: 204 tests with 100% passing rate

Dependencies

• rand - Random number generation
• reqwest - HTTP client for CEP address lookup
• serde / serde_json - JSON serialization
• chrono - Date and time handling
• regex - Regular expression matching
• unicode-normalization - String normalization

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Acknowledgments

Inspired by brazilian-utils/python - A Python library with similar utilities for Brazilian data.