Struct imgix::url::Url

pub struct Url { /* fields omitted */ }

Primary structure used to generate imgix URLs.

An imgix URL is comprised of four components:

• scheme - the scheme being used (https by default).
• domain - the domain, i.e. example.domain.net.
• path - the path to the image file.
• query - the query string constructed from params.

            domain
        ┌──────┴──────┐
https://www.example.com/image/path.png/?w=320&h=640
└─┬─┘                  └──────┬───────┘ └────┬────┘
scheme                      path           params

This structure is meant to be a crate primitive that crate users and contributors can use to build on. This is part of the reason why many of the building functions can panic. They panic to try to ensure invalid urls are never constructed. This is to provide higher-level structures certain guarantees about the representation of a Url.

Implementations

impl Url

pub fn new(domain: &str) -> Self

Construct a new Url given a domain.

Panics

This constructor will fail if the domain is an empty string.

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

Set the domain value (i.e. "example.domain.net").

Panics

This method panics if passed an empty string.

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

Set the path value to the image file (i.e. 'image/path.png').

Panics

This method panics if passed an empty string.

pub fn param(self, k: &'static str, v: &'static str) -> Self

Set an arbitrary key-value parameter (i.e. k='w', v='100' or k='fit', v='crop').

Examples

use imgix::Url;
let url = Url::new("example.domain.net").param("w", "320").path("test").lib("");
let right = "https://example.domain.net/test?w=320";
assert_eq!(url.join(), "https://example.domain.net/test?w=320")

Panics

This method panics if any key k or any value v is an empty string, where k and v represent string literals.

pub fn params(self, p: &[(&'static str, &'static str)]) -> Self

Set an arbitrary number of key-value parameters.

Examples

use imgix::Url;

let url = Url::new("example.domain.net")
    .path("test")
    .params(&[("w", "320"), ("h", "640"), ("fit", "crop")]);

let right = "https://example.domain.net/test?w=320&h=640&fit=crop";
assert_eq!(url.join(), right);

Panics

This method panics if any key k or any value v is an empty string.

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

Set the library version explicitly, see Url::ix() for the implicit default.

The Url's lib value can be set to any String by passing the desired string literal. If the lib is a valid ix-lib parameter if will be considered on the server. However, if an invalid lib-parameter is passed, e.g. "rust-is-cool", it will be ignored (appreciated ;) but ignored).

Examples

use imgix::{lib_version, Scheme, Url};

const DOMAIN: &str = "example.domain.net";
const PATH: &str = "image.png";

let url = Url::new(DOMAIN)
    .lib(&lib_version())
    .path("image.png");

let right = format!(
    "{scheme}://{domain}/{path}?{lib}",
    scheme = Scheme::Https,
    domain = DOMAIN,
    path = PATH,
    lib = lib_version()
);

assert_eq!(url.join(), right);

let url = url.lib("rust-is-cool");
assert_ne!(url.join(), right);

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

Set the signing token. TODO: Test token post md5 implementation.

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

pub fn ix(self) -> Self

pub fn join(&self) -> String

Join the components of a Url (i.e. scheme + domain + path + params) where the resulting string has the following form:

{scheme}://{domain}/{path}?{lib}{query}

This function will only join the components of a Url if a path has been specified.

Panics

This function will panic if the image path has not been specified. (i.e. if the path is None). This is to ensure that a Url is joined if it is in a valid state.

pub fn join_params(p: &[(&'static str, &'static str)]) -> String

Join a list of key-value parameter pairs.

This associated function joins a list of key-value pairs. It is internal to Url and doesn't do much validation. This is to avoid duplicate validations as these parameters are valid at the time of construction.

Examples

Panics

This function panics if any key k or any value v is an empty string.

pub fn get_scheme(&self) -> &Scheme

pub fn get_domain(&self) -> &str

pub fn get_lib(&self) -> &str

pub fn get_params(&self) -> &[(&'static str, &'static str)]

pub fn get_path(&self) -> &str

pub fn get_token(&self) -> &str

pub fn has_params(&self) -> bool

pub fn to_srcset(&self) -> String

Trait Implementations

impl Debug for Url

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

Formats the value using the given formatter.

impl Default for Url

fn default() -> Self

By default a URL is created with its scheme set to Scheme::Https and the lib value set to the version specified in this library's Cargo.toml

impl From<Url> for SourceSet

fn from(url: Url) -> Self

Performs the conversion.