postal-code

postal-code is a robust, production-grade Rust library for validating and manipulating international postal codes. It supports a variety of countries, including the USA, Canada, UK, France, Germany, and Italy, with the flexibility to add more.

This crate offers:

• Strongly typed Country integration from an external country crate.
• Compile-time verified regular expressions for each supported country's postal code format.
• Builder patterns (derive_builder) for safer, more ergonomic construction of PostalCode and PostalCodeCollection instances.
• A modular, extensible validator system using traits and macros to easily add new countries.
• Comprehensive error handling via a well-structured PostalCodeConstructionError type.
• A robust test suite that covers valid and invalid postal codes, edge cases, and collection handling.

Key Features:

• Type-Safe: Each postal code is associated with a Country enum variant, ensuring that once created, it is guaranteed to be valid for that country.
• Extensible: Add new countries by defining regex patterns and calling a macro to generate validators.
• Error Handling: Strong, typed errors (PostalCodeConstructionError) avoid stringly-typed error handling.
• Testing and Reliability: Thorough tests ensure that edge cases and invalid inputs are handled correctly.

Usage Example:

use postal_code::PostalCode;
use country::Country;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let us_code = PostalCode::new(Country::USA, "12345")?;
    println!("Valid US postal code: {}", us_code.code());

    let ca_code = PostalCode::new(Country::Canada, "K1A0B1")?;
    println!("Valid Canadian postal code: {}", ca_code.code());

    // Attempting an invalid UK code:
    let uk_code = PostalCode::new(Country::UK, "SW1A1AAZ");
    match uk_code {
        Ok(code) => println!("Valid UK code: {}", code.code()),
        Err(e) => eprintln!("Invalid postal code: {:?}", e),
    }

    Ok(())
}

Testing:

Run the test suite with:

cargo test

This will run an extensive battery of tests, including correctness checks for various countries, invalid inputs, and builder patterns.

Contributing:

Contributions are welcome! Please open issues or submit pull requests on the project’s GitHub repository.

License:

postal-code is licensed under the MIT license. See LICENSE for details.