url-escape

url-escape is a small, focused Rust library for percent-encoding special characters in URLs and decoding them back. It provides context-specific encode functions for every part of a URL, including fragments, paths, query strings, user info, components, and application/x-www-form-urlencoded form data.

Each encoder comes in convenient variants that return a new string or write directly into an existing buffer, vector, or writer, making it efficient to build up complete URLs piece by piece. Matching decode functions reverse the process, restoring the original text from percent-encoded input.

What You Get

• Context-specific encoders: encode_fragment, encode_path, encode_query, encode_userinfo, encode_component
• www-form-urlencoded encoding and decoding for HTML form payloads
• _to_string, _to_vec, and _to_writer variants that append into existing buffers
• A general decode function that restores percent-encoded text
• A dependency-light crate suitable for both std and buffer-building workflows

Common Use Cases

• Assembling correctly escaped URLs from user-supplied components
• Encoding query strings and form data for HTTP requests
• Decoding percent-encoded path or query segments received from clients
• Streaming URL text directly into an output buffer or writer

Under The Hood

Architecture - The crate is built around a family of encode_* functions, each parameterized by the character set legal for a specific URL component (fragment, path, query, userinfo, component, form). A macro-driven pattern generates the base, _to_string, _to_vec, and _to_writer variants so every context gets the same ergonomic surface, while decode functions perform the inverse percent-decoding.

Tech Stack - Pure Rust with minimal dependencies, published to crates.io and documented on docs.rs. Continuous integration runs via GitHub Actions, and the crate targets stable Rust with straightforward std-based string handling.

Code Quality - The README doubles as an executable specification, with assert_eq! doctests covering each encoder and decoder against concrete inputs and expected percent-encoded output. The component-per-function design keeps each unit small and independently testable.

API Design - Function names read as intent (encode_query, encode_fragment), and the consistent to* suffix convention lets callers choose between allocation and in-place buffer growth without learning a new pattern per function. This makes building complex URLs incrementally both explicit and efficient.