2 releases
Uses new Rust 2024
new 0.1.1 | Mar 27, 2025 |
---|---|
0.1.0 | Mar 27, 2025 |
#533 in Rust patterns
28 downloads per month
25KB
244 lines
urlquerystring
A high-performance, zero-allocation URL query string parser for Rust. This crate provides a stack-based implementation that extracts query parameters without any heap allocations, making it ideal for performance-critical environments.
Features
- Zero Heap Allocations: All memory is allocated on the stack
- High Performance: Direct byte manipulation and minimal string operations
- UTF-8 Safe: Properly handles UTF-8 encoded query parameters
- Percent-Decoding: Built-in support for URL percent-encoding
- Const-Generic Based: Flexible size configuration through const generics
- Zero-Cost Abstractions: All operations are zero-cost where possible
Example
use urlquerystring::StackQueryParams;
let url = "https://example.com/path?name=John&age=25&city=New%20York";
let params = StackQueryParams::new(url);
assert_eq!(params.get("name"), Some("John"));
assert_eq!(params.get("city"), Some("New York")); // Automatically percent-decoded
Performance
This crate is designed for maximum performance:
- No heap allocations in the core functionality
- Fixed-size buffers for predictable memory usage
- Direct byte manipulation for parsing
- Zero-cost abstractions for common operations
- Efficient percent-decoding implementation
Usage
Basic Usage
use urlquerystring::StackQueryParams;
let url = "https://example.com/path?name=John&age=25";
let params = StackQueryParams::new(url);
// Access parameters
assert_eq!(params.get("name"), Some("John"));
assert_eq!(params.get("age"), Some("25"));
Custom Size Limits
use urlquerystring::StackQueryParams;
// Create a container with custom size limits
let params = StackQueryParams::<32, 64, 256>::custom_new(
"https://example.com/path?param=value"
);
Iterating Over Parameters
use urlquerystring::StackQueryParams;
let params = StackQueryParams::new("https://example.com/path?a=1&b=2");
for (key, value) in params.iter() {
println!("{} = {}", key, value);
}
Default Size Limits
The crate provides default size limits that can be used with the new()
constructor:
- Maximum number of parameters: 16
- Maximum key length: 32 bytes
- Maximum value length: 128 bytes
These limits can be customized using the custom_new()
constructor with const generics.
When to Use This Crate
This crate is particularly useful in:
- Performance-critical applications
- Embedded systems
- Environments where heap allocations are restricted
- High-throughput web servers
- Systems with limited memory
Alternatives
If you need more flexibility or don't require zero-allocation parsing:
- url: Full URL parsing with heap allocations
- serde_urlencoded: Serialization-focused query parsing
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Acknowledgments
- Inspired by the need for high-performance URL parsing in embedded systems
- Built with zero-allocation principles in mind
- Designed for maximum performance and safety