urlquerystring 0.1.1

A high-performance, zero-allocation URL query string parser.
Documentation

urlquerystring

Crates.io Documentation License

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