Crate url_query_string 

url_query_string Procedural Macro Crate

The url_query_string crate provides a procedural macro #[derive(ToQueryString)] for automatically generating methods to serialize Rust structs into URL query strings.

This crate leverages serde_qs for serialization, ensuring compatibility with serde and its powerful features. By deriving ToQueryString, two methods are added to your struct:

• to_query_string: Converts the struct to a query string, ignoring errors and returning an empty string in case of failure.
• try_to_query_string: Returns a Result containing either the query string or a serialization error from serde_qs.

Features

• Automatic Query String Generation: Simplifies converting structs into URL-friendly query strings.
• Compatible with serde: Supports serialization conventions like camelCase or snake_case through serde attributes.
• Error Handling: Offers try_to_query_string for cases where error handling is necessary.

Usage

Add the Crate

Add the crate to your Cargo.toml:

[dependencies]
url_query_string = "0.1"
serde = { version = "1.0", features = ["derive"] }
serde_qs = "0.7"

Example

use serde::Serialize;
use url_query_string::ToQueryString;

#[derive(Serialize, ToQueryString)]
#[serde(rename_all = "camelCase")]
struct TestStruct {
    pub page: Option<u32>,
    pub page_size: Option<u32>,
    pub id: Option<String>,
    pub user_id: Option<String>,
}

fn main() {
    let instance = TestStruct {
        page: Some(1),
        page_size: Some(20),
        id: Some("test_id".to_string()),
        user_id: Some("user_123".to_string()),
    };

    // Generate query string (ignores errors).
    let query_string = instance.to_query_string();
    println!("Query String: {}", query_string);

    // Generate query string with error handling.
    match instance.try_to_query_string() {
        Ok(qs) => println!("Query String (with Result): {}", qs),
        Err(e) => eprintln!("Error: {}", e),
    }
}

Output

Running the example above will produce:

Query String: page=1&pageSize=20&id=test_id&userId=user_123
Query String (with Result): page=1&pageSize=20&id=test_id&userId=user_123

Integration with serde

The crate uses serde attributes to control the serialization behavior. For example, you can use #[serde(rename_all = "snake_case")] to adjust the case of field names in the query string.

Example with snake_case

use serde::Serialize;
use url_query_string::ToQueryString;

#[derive(Serialize, ToQueryString)]
#[serde(rename_all = "snake_case")]
struct AnotherStruct {
    pub user_name: Option<String>,
    pub access_token: Option<String>,
}

This will generate query strings like:

user_name=test_user&access_token=abcd1234

Generated Methods

When deriving ToQueryString, the following methods are added to your struct:

• pub fn to_query_string(&self) -> String: Converts the struct into a query string. Returns an empty string if serialization fails.

• pub fn try_to_query_string(&self) -> Result<String, serde_qs::Error>: Converts the struct into a query string. Returns a Result with either the query string or an error.

Contribution

Contributions are welcome! If you encounter any bugs or have feature requests, please open an issue or submit a pull request on GitHub.

Derive Macros

ToQueryString

Procedural macro to derive query string serialization methods for structs.