Struct QueryBuilder

Source

pub struct QueryBuilder { /* private fields */ }

Expand description

Standalone query-string builder with typed Display values.

Produces key=value pairs separated by &, with form-encoding applied to both key and value. Use merge_into to append the query string to an existing URL.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new()
    .param("limit", 20u32)
    .param("sort", "desc")
    .build();
assert_eq!(qs, "limit=20&sort=desc");

Implementations§

Source §

impl QueryBuilder

Source

pub fn new() -> Self

Create an empty QueryBuilder.

Source

pub fn param(self, key: impl Into<String>, value: impl ToString) -> Self

Append a typed query parameter.

The value is converted to a string via Display.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new().param("active", true).build();
assert_eq!(qs, "active=true");

Source

pub fn maybe_param( self, key: impl Into<String>, value: Option<impl ToString>, ) -> Self

Append an optional parameter — skipped if value is None.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new()
    .param("a", 1u32)
    .maybe_param("b", None::<&str>)
    .build();
assert_eq!(qs, "a=1");

Source

pub fn build(&self) -> String

Build the query string (without leading ?).

Returns an empty string when no parameters have been added.

Source

pub fn merge_into(&self, url: &str) -> String

Append the query string to url, using ? if there is no existing query, or & if one already exists.

Returns url unchanged when there are no params.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new().param("page", 2u32);
assert_eq!(qs.merge_into("https://example.com"), "https://example.com?page=2");
assert_eq!(qs.merge_into("https://example.com?limit=20"), "https://example.com?limit=20&page=2");

Source

pub fn set(self, key: impl Into<String>, value: impl ToString) -> Self

Append a key=value pair — alias for param.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new().set("limit", 10u32).set("sort", "asc").build();
assert_eq!(qs, "limit=10&sort=asc");

Source

pub fn set_opt( self, key: impl Into<String>, value: Option<impl ToString>, ) -> Self

Append an optional key=value pair — skipped when value is None.

Alias for maybe_param.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new()
    .set("a", 1u32)
    .set_opt("b", None::<&str>)
    .set_opt("c", Some("yes"))
    .build();
assert_eq!(qs, "a=1&c=yes");

Source

pub fn extend_from_struct<T: Serialize>(self, value: &T) -> Result<Self, Error>

Flatten a serializable struct’s top-level fields as query parameters.

The struct is serialized to a JSON object; each field whose value is not null is appended as a key=value pair. Nested objects and arrays are serialized as their JSON representation.

Returns an error when value cannot be serialized or is not a JSON object.

§Examples

use api_bones::url::QueryBuilder;
use serde::Serialize;

#[derive(Serialize)]
struct Params {
    page: u32,
    sort: &'static str,
    filter: Option<&'static str>,
}

let params = Params { page: 2, sort: "desc", filter: None };
let qs = QueryBuilder::new()
    .extend_from_struct(&params)
    .unwrap()
    .build();
assert_eq!(qs, "page=2&sort=desc");

Source

pub fn merge_into_url(&self, url: &str) -> String

Append the query string to url — alias for merge_into.

Uses ? if the URL has no existing query string, or & otherwise. Returns url unchanged when there are no params.

§Examples

use api_bones::url::QueryBuilder;

let qs = QueryBuilder::new().set("page", 3u32);
assert_eq!(qs.merge_into_url("https://api.example.com/items"), "https://api.example.com/items?page=3");
assert_eq!(qs.merge_into_url("https://api.example.com/items?limit=10"), "https://api.example.com/items?limit=10&page=3");