Url
Url
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
queryParams : Url -> Dict Str Str
path : Url -> Str
Returns the URL's path—the part after
the scheme and authority (e.g. https://) but before any ? or # it might have.
Returns "" if the URL has no path.
# Gives "example.com/" Url.fromStr "https://example.com/?key1=val1&key2=val2&key3=val3#stuff" |> Url.path
# Gives "/foo/" Url.fromStr "/foo/?key1=val1&key2=val2&key3=val3#stuff" |> Url.path
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