Documentation

Url

A Uniform Resource Locator.

It could be an absolute address, such as https://roc-lang.org/authors or a relative address, such as /authors. You can create one using Url.fromStr.

reserve : Url, U64 -> Url

Reserve the given number of bytes as extra capacity. This can avoid reallocation when calling multiple functions that increase the length of the URL.

The following example reserves 50 bytes, then builds the url https://example.com/stuff?caf%C3%A9=du%20Monde&email=hi%40example.com;

Url.fromStr "https://example.com"
|> Url.reserve 50
|> Url.append "stuff"
|> Url.appendParam "café" "du Monde"
|> Url.appendParam "email" "hi@example.com"

The Str.countUtf8Bytes function can be helpful in finding out how many bytes to reserve.

There is no Url.withCapacity because it's better to reserve extra capacity on a Str first, and then pass that string to Url.fromStr. This function will make use of the extra capacity.

fromStr : Str -> Url

Create a Url without validating or percent-encoding anything.

Url.fromStr "https://example.com#stuff"

URLs can be absolute, like https://example.com, or they can be relative, like /blah.

Url.fromStr "/this/is#relative"

Since nothing is validated, this can return invalid URLs.

Url.fromStr "https://this is not a valid URL, not at all!"

Naturally, passing invalid URLs to functions that need valid ones will tend to result in errors.

toStr : Url -> Str

Return a Str representation of this URL.

# Gives "https://example.com/two%20words"
Url.fromStr "https://example.com"
|> Url.append "two words"
|> Url.toStr

append : Url, Str -> Url

Percent-encodes a path component and appends to the end of the URL's path.

This will be appended before any queries and fragments. If the given path string begins with / and the URL already ends with /, one will be ignored. This avoids turning a single slash into a double slash. If either the given URL or the given string is empty, no / will be added.

# Gives https://example.com/some%20stuff
Url.fromStr "https://example.com"
|> Url.append "some stuff"

# Gives https://example.com/stuff?search=blah#fragment
Url.fromStr "https://example.com?search=blah#fragment"
|> Url.append "stuff"

# Gives https://example.com/things/stuff/more/etc/"
Url.fromStr "https://example.com/things/"
|> Url.append "/stuff/"
|> Url.append "/more/etc/"

# Gives https://example.com/things
Url.fromStr "https://example.com/things"
|> Url.append ""

appendParam : Url, Str, Str -> Url

Adds a Str query parameter to the end of the Url.

The key and value both get percent-encoded.

# Gives https://example.com?email=someone%40example.com
Url.fromStr "https://example.com"
|> Url.appendParam "email" "someone@example.com"

This can be called multiple times on the same URL.

# Gives https://example.com?caf%C3%A9=du%20Monde&email=hi%40example.com
Url.fromStr "https://example.com"
|> Url.appendParam "café" "du Monde"
|> Url.appendParam "email" "hi@example.com"

withQuery : Url, Str -> Url

Replaces the URL's query—the part after the ?, if it has one, but before any # it might have.

Passing "" removes the ? (if there was one).

# Gives https://example.com?newQuery=thisRightHere#stuff
Url.fromStr "https://example.com?key1=val1&key2=val2#stuff"
|> Url.withQuery "newQuery=thisRightHere"

# Gives https://example.com#stuff
Url.fromStr "https://example.com?key1=val1&key2=val2#stuff"
|> Url.withQuery ""

query : Url -> Str

Returns the URL's query—the part after the ?, if it has one, but before any # it might have.

Returns "" if the URL has no query.

# Gives "key1=val1&key2=val2&key3=val3"
Url.fromStr "https://example.com?key1=val1&key2=val2&key3=val3#stuff"
|> Url.query

# Gives ""
Url.fromStr "https://example.com#stuff"
|> Url.query

hasQuery : Url -> Bool

Returns Bool.true if the URL has a ? in it.

# Gives Bool.true
Url.fromStr "https://example.com?key=value#stuff"
|> Url.hasQuery

# Gives Bool.false
Url.fromStr "https://example.com#stuff"
|> Url.hasQuery

fragment : Url -> Str

Returns the URL's fragment—the part after the #, if it has one.

Returns "" if the URL has no fragment.

# Gives "stuff"
Url.fromStr "https://example.com#stuff"
|> Url.fragment

# Gives ""
Url.fromStr "https://example.com"
|> Url.fragment

withFragment : Url, Str -> Url

Replaces the URL's fragment.

If the URL didn't have a fragment, adds one. Passing "" removes the fragment.

# Gives https://example.com#things
Url.fromStr "https://example.com#stuff"
|> Url.withFragment "things"

# Gives https://example.com#things
Url.fromStr "https://example.com"
|> Url.withFragment "things"

# Gives https://example.com
Url.fromStr "https://example.com#stuff"
|> Url.withFragment ""

hasFragment : Url -> Bool

Returns Bool.true if the URL has a # in it.

# Gives Bool.true
Url.fromStr "https://example.com?key=value#stuff"
|> Url.hasFragment

# Gives Bool.false
Url.fromStr "https://example.com?key=value"
|> Url.hasFragment