wellformed_validate/
lib.rs

1//! # wellformed_validate
2//!
3//! High-throughput validation primitives for wellformed schemas.
4//!
5//! This crate provides extremely fast validation primitives optimized for
6//! high-throughput structured-data processing. Key features:
7//!
8//! - **SIMD TIN validation**: 1.4ns per SSN/EIN (~700M validations/sec)
9//! - **Zero-allocation hot path**: Static registry, no per-call allocations
10//! - **Batch-oriented API**: Process thousands of forms with cache-optimal layout
11//! - **Hand-written validators**: 90x faster than regex for short strings
12//!
13//! ## Performance
14//!
15//! These figures are local benchmark results for short ASCII identifiers. Run
16//! the included criterion benchmarks on your deployment hardware before using
17//! them for capacity planning.
18//!
19//! | Validator | Latency | Throughput |
20//! |-----------|---------|------------|
21//! | `is_ssn_format` | 1.4 ns | 700M/sec |
22//! | `is_ein_format` | 1.4 ns | 700M/sec |
23//! | `is_zip_format` | 0.95 ns | 1B/sec |
24//! | `validate_ssn` (full) | 2.9 ns | 345M/sec |
25//! | Batch (10K forms) | 48 µs | 209M/sec |
26//!
27//! ## Quick Start
28//!
29//! ```rust
30//! use wellformed_validate::{tin, patterns};
31//!
32//! // Ultra-fast format checks (no regex, hand-written)
33//! assert!(patterns::is_ssn_format("123-45-6789"));
34//! assert!(patterns::is_ein_format("12-3456789"));
35//! assert!(patterns::is_zip_format("12345"));
36//!
37//! // Full TIN validation with IRS rules
38//! assert!(tin::validate_ssn("123-45-6789"));
39//! assert!(tin::validate_ein("12-3456789"));
40//!
41//! // Batch validation (SIMD accelerated)
42//! let tins = vec!["123456789", "987654321", "111223333"];
43//! let results = tin::validate_batch(&tins);
44//! ```
45//!
46//! ## Architecture
47//!
48//! ```text
49//! ┌─────────────────────────────────────────────────────────────┐
50//! │                    wellformed_validate                         │
51//! ├─────────────────────────────────────────────────────────────┤
52//! │  tin.rs          │ SIMD TIN/SSN/EIN validation              │
53//! │  registry.rs     │ LazyLock predicate registry              │
54//! │  patterns.rs     │ Fast format checks (no regex)            │
55//! │  batch.rs        │ SoA batch validation                     │
56//! └─────────────────────────────────────────────────────────────┘
57//! ```
58//!
59//! ## When to Use Vectorscan
60//!
61//! The optional `vectorscan` feature is for scanning **large documents** (KB/MB)
62//! for multiple patterns. For validating short strings like TINs, the hand-written
63//! validators are 5,700x faster.
64
65#![cfg_attr(feature = "nightly", feature(portable_simd))]
66
67pub mod error;
68pub mod registry;
69pub mod tin;
70
71pub mod patterns;
72
73pub mod batch;
74
75// Re-exports for convenience
76pub use error::{ValidationError, ValidationResult};
77pub use patterns::{is_ein_format, is_email_format, is_ssn_format, is_zip_format};
78pub use registry::REGISTRY;
79pub use tin::{TinKind, TinValidator};
80
81/// Validate a TIN string, returning true if valid.
82///
83/// This is the fastest single-TIN validation path.
84/// For bulk validation, use [`tin::validate_batch`].
85#[inline]
86pub fn validate_tin(tin: &str) -> bool {
87    tin::validate_any(tin)
88}
89
90/// Validate an SSN string.
91#[inline]
92pub fn validate_ssn(ssn: &str) -> bool {
93    tin::validate_ssn(ssn)
94}
95
96/// Validate an EIN string.
97#[inline]
98pub fn validate_ein(ein: &str) -> bool {
99    tin::validate_ein(ein)
100}
wellformed_validate/lib.rs

wellformed_validate/
lib.rs
