Struct HttpUrlBuilder 

pub struct HttpUrlBuilder { /* private fields */ }

Builder for constructing HTTP/HTTPS URLs programmatically.

HttpUrlBuilder is the focus of this crate. It accumulates URL components as decoded Rust strings and, on build / build_url, hands them to the url crate, which performs all percent-encoding, normalization and validation according to the WHATWG URL Standard.

Example

use http_url::{HttpUrl, Scheme};

let url = HttpUrl::builder()
    .scheme(Scheme::Https)
    .host("example.com")
    .add_path_segment("api")
    .add_path_segment("v1")
    .add_query_parameter("key", "value")
    .fragment("section")
    .build()
    .unwrap();

assert_eq!(url.to_string(), "https://example.com/api/v1?key=value#section");

Implementations

impl HttpUrlBuilder

pub fn new() -> Self

Create a new empty builder.

pub fn from_url(url: Url) -> Result<Self>

Create a builder pre-populated from an existing url::Url.

The URL must have an http or https scheme. The returned builder is ready to be modified and rebuilt via build or build_url.

Example

use http_url::HttpUrlBuilder;

let u = url::Url::parse("https://example.com/a/b?q=1").unwrap();
let url = HttpUrlBuilder::from_url(u)
    .unwrap()
    .add_path_segment("c")
    .build()
    .unwrap();
assert_eq!(url.as_url().path(), "/a/b/c");

pub fn parse(url: &str) -> Result<Self>

Create a builder pre-populated by parsing a URL string.

Equivalent to HttpUrlBuilder::from_url applied to the result of url::Url::parse.

pub fn scheme(self, scheme: Scheme) -> Self

Set the scheme.

pub fn username(self, username: &str) -> Self

Set the username for basic auth.

pub fn password(self, password: &str) -> Self

Set the password for basic auth.

pub fn host(self, host: &str) -> Self

Set the host (domain name or IP address literal, including bracketed IPv6 such as [::1]).

pub fn port(self, port: u16) -> Self

Set the port. Use remove_port to revert to the scheme’s default.

pub fn remove_port(self) -> Self

Revert to the scheme’s default port.

pub fn add_path_segment(self, segment: &str) -> Self

Add a single path segment (decoded form; it is percent-encoded on build).

pub fn add_path_segments(self, segments: &[&str]) -> Self

Add multiple path segments at once (decoded form).

pub fn set_path(self, path: &str) -> Self

Replace the entire path with the segments of path (decoded form).

path is split on /; a leading / is ignored and empty segments are dropped. Each segment is stored as-is (decoded) and re-encoded on build. No percent-decoding is applied to the input — pass a decoded path.

pub fn add_query_parameter(self, name: &str, value: &str) -> Self

Add a query parameter (name and value in decoded form). Both are percent-encoded on build using application/x-www-form-urlencoded semantics (space becomes +).

pub fn remove_query_parameter(self, name: &str) -> Self

Remove all query parameters with the given name.

pub fn clear_query_parameters(self) -> Self

Clear all query parameters.

pub fn fragment(self, fragment: &str) -> Self

Set the fragment (decoded form).

pub fn remove_fragment(self) -> Self

Remove the fragment.

pub fn build_url(self) -> Result<Url>

Consume the builder and produce a url::Url.

The scheme is always http or https (it is a typed Scheme field), so the result is always a valid HTTP(S) URL. Returns an error only if required components (scheme, host) are missing or the url crate rejects the assembled URL (e.g. an invalid host).

Use build instead if you want an HttpUrl wrapper.

pub fn build(self) -> Result<HttpUrl>

Consume the builder and produce an HttpUrl — a newtype over url::Url enforcing the http/https invariant.

Equivalent to HttpUrl::from_url applied to build_url.

Trait Implementations

impl Clone for HttpUrlBuilder

fn clone(&self) -> HttpUrlBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HttpUrlBuilder

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

Formats the value using the given formatter.

impl Default for HttpUrlBuilder

fn default() -> Self

Returns the “default value” for a type.

impl FromStr for HttpUrlBuilder

type Err = HttpUrlError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self>

Parses a string s to return a value of this type.