Struct QueryString 

pub struct QueryString<'a> { /* private fields */ }

A zero-allocation query string builder for percent encoding key-value pairs.

This builder borrows all keys and values. Building performs a single Vec allocation for the pair list; rendering percent-encodes each value on the fly without allocating intermediate strings.

If you need a builder without a lifetime parameter — e.g. to store it in a struct or return it from a function that owns the values — use QueryStringOwned or convert via into_owned.

Example

use query_string_builder::QueryString;

let tasty = true;
let qs = QueryString::new()
    .with("q", "apple")
    .with("tasty", &tasty)
    .with_opt("category", Some("fruits and vegetables"));

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=apple&tasty=true&category=fruits%20and%20vegetables"
);

Borrowing footgun

Because the builder borrows its values, temporaries created inline do not live long enough — bind them to a variable first:

use query_string_builder::QueryString;

let qs = QueryString::new().with("answer", &42.to_string()); // temporary dropped here
println!("{qs}");

use query_string_builder::QueryString;

let answer = 42.to_string();
let qs = QueryString::new().with("answer", &answer);
assert_eq!(qs.to_string(), "?answer=42");

Implementations

impl<'a> QueryString<'a>

pub fn new() -> Self

Creates a new, empty query string builder.

pub fn with<K, V>(self, key: K, value: V) -> Self

where K: IntoPart<'a>, V: IntoPart<'a>,

Appends a key-value pair to the query string.

Example

use query_string_builder::QueryString;

let answer = 42;
let qs = QueryString::new()
    .with("q", "🍎 apple")
    .with("category", "fruits and vegetables")
    .with("answer", &answer);

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=%F0%9F%8D%8E%20apple&category=fruits%20and%20vegetables&answer=42"
);

pub fn with_opt<K, V>(self, key: K, value: Option<V>) -> Self

where K: IntoPart<'a>, V: IntoPart<'a>,

Appends a key-value pair to the query string if the value exists.

Example

use query_string_builder::QueryString;

let works = true;
let qs = QueryString::new()
    .with_opt("q", Some("🍎 apple"))
    .with_opt("f", None::<&str>)
    .with_opt("category", Some("fruits and vegetables"))
    .with_opt("works", Some(&works));

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=%F0%9F%8D%8E%20apple&category=fruits%20and%20vegetables&works=true"
);

pub fn push<K, V>(&mut self, key: K, value: V) -> &mut Self

where K: IntoPart<'a>, V: IntoPart<'a>,

Appends a key-value pair to the query string.

Example

use query_string_builder::QueryString;

let mut qs = QueryString::new();
qs.push("q", "apple");
qs.push("category", "fruits and vegetables");

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=apple&category=fruits%20and%20vegetables"
);

pub fn push_opt<K, V>(&mut self, key: K, value: Option<V>) -> &mut Self

where K: IntoPart<'a>, V: IntoPart<'a>,

Appends a key-value pair to the query string if the value exists.

Example

use query_string_builder::QueryString;

let mut qs = QueryString::new();
qs.push_opt("q", None::<&str>);
qs.push_opt("q", Some("🍎 apple"));

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=%F0%9F%8D%8E%20apple"
);

pub fn len(&self) -> usize

Determines the number of key-value pairs currently in the builder.

pub fn is_empty(&self) -> bool

Determines if the builder is currently empty.

pub fn append(&mut self, other: QueryString<'a>)

Appends another query string builder’s values.

Example

use query_string_builder::QueryString;

let mut qs = QueryString::new().with("q", "apple");
let more = QueryString::new().with("q", "pear");

qs.append(more);

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=apple&q=pear"
);

pub fn append_into(self, other: QueryString<'a>) -> Self

Appends another query string builder’s values, consuming both types.

Example

use query_string_builder::QueryString;

let qs = QueryString::new().with("q", "apple");
let more = QueryString::new().with("q", "pear");

let qs = qs.append_into(more);

assert_eq!(
    format!("https://example.com/{qs}"),
    "https://example.com/?q=apple&q=pear"
);

pub fn into_owned(self) -> QueryStringOwned

Converts this borrowing builder into a QueryStringOwned by rendering each key and value to an owned String.

Useful for building cheaply with borrows and then storing or returning the result past the borrows’ lifetimes.

Example

use query_string_builder::{QueryString, QueryStringOwned};

let qs: QueryStringOwned = {
    let q = String::from("apple");
    QueryString::new().with("q", &q).into_owned()
};

assert_eq!(qs.to_string(), "?q=apple");

Trait Implementations

impl<'a> Clone for QueryString<'a>

fn clone(&self) -> QueryString<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryString<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for QueryString<'a>

fn default() -> QueryString<'a>

Returns the “default value” for a type.

impl Display for QueryString<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.