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