urlencoding

urlencoding is a minimal Rust library for percent-encoding and decoding URLs. It encodes everything except alphanumerics and the unreserved characters -, _, ., ~, and follows the WHATWG URL standard for error recovery when decoding incomplete percent-escapes.

The crate returns Cow<str> from its encode/decode functions to avoid heap allocation when no transformation is needed, and provides a decode_binary variant for handling arbitrary bytes and invalid UTF-8. It has no runtime dependencies and is widely used as a lightweight building block in web-facing Rust crates.

What You Get

• encode() and decode() functions for percent-encoding/decoding UTF-8 strings
• decode_binary() for decoding into arbitrary bytes, tolerating invalid UTF-8
• Cow<str>/Cow<[u8]> return types that avoid allocation when no encoding/decoding is needed
• WHATWG URL standard-compliant error recovery for malformed percent-escapes
• Zero runtime dependencies, keeping the crate lightweight for embedding in other libraries

Common Use Cases

• Encoding query parameters or path segments before building a URL
• Decoding percent-encoded query strings or form data received from an HTTP request
• Sanitizing user-supplied strings for safe inclusion in a URL
• Handling arbitrary byte payloads embedded in percent-encoded data via decode_binary

Under The Hood

Architecture - The crate is split across three small modules: enc.rs implements percent-encoding, dec.rs implements decoding (both string and binary variants), and lib.rs re-exports the public API and documents usage; total implementation is under 400 lines, keeping the surface area minimal and auditable. Tech Stack - Pure Rust (edition 2021) with zero runtime dependencies, using only std::borrow::Cow from the standard library to avoid unnecessary allocations; a benches/ directory holds Criterion-based benchmarks for encode/decode performance. Code Quality - The codebase is small enough to review in full; the maintainer (kornelski, known for numerous foundational Rust crates like pngquant/rgb) marks it with a ‘maintenance: as-is’ badge, signaling it is considered functionally complete rather than unmaintained — commits have been infrequent since 2024 because the API is stable. API Design - The API surface is deliberately minimal: encode(), decode(), and decode_binary() are the only entry points, each documented with runnable examples in the README, making adoption essentially zero-friction.