Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.url

    URL.scheme

    Returns the lowercase scheme without its delimiter.

    scheme() -> string
    Module
    std.url
    Receiver
    URL
    Minimum arity
    0
    Maximum arity
    0

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.url in language mode 5.21.

    The current compiler selects std/url.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    URL

    Parameter constraints

    Additional contracts are Pending.

    URL.scheme returns the lowercase scheme without its delimiter. URL.host returns Some containing the serialized host without user information or a port. IPv6 hosts include their square brackets.

    A URL whose host is absent returns None() from URL.host. A present empty host returns Some containing an empty string. A local file URL can have that empty host.

    URL.path returns the serialized path without the query or fragment. A hierarchical path retains its leading slash. An opaque path has no implied slash. Percent escapes stay encoded so an escaped slash remains path data.

    URL.fragment returns None() when there is no fragment delimiter. An explicit empty fragment returns Some containing an empty string. A present fragment excludes its delimiter and retains percent encoding.

    Scheme, host, path, and fragment inspection cannot fail after construction. Each receiver is evaluated once. The returned strings are immutable and inspection has no external effects.

    Read URL.query for decoded query fields. URL.path and URL.fragment do not apply query decoding. In particular, a plus sign in those components remains a plus sign.

    Related rule: Read serialized URL components and their absence

    Result

    Additional contracts are Pending.

    The declared result type is string.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Returns the lowercase scheme without its delimiter.

    Resolved contracts

    Link

    Related entries

    Link

    std.url

    Read serialized URL components and their absence

    Link
    Ruletopaz.stdlib.contract.url-components.rule

    Read serialized URL components and their absence

    URL.scheme returns the lowercase scheme without its delimiter. URL.host returns Some containing the serialized host without user information or a port. IPv6 hosts include their square brackets.

    A URL whose host is absent returns None() from URL.host. A present empty host returns Some containing an empty string. A local file URL can have that empty host.

    URL.path returns the serialized path without the query or fragment. A hierarchical path retains its leading slash. An opaque path has no implied slash. Percent escapes stay encoded so an escaped slash remains path data.

    URL.fragment returns None() when there is no fragment delimiter. An explicit empty fragment returns Some containing an empty string. A present fragment excludes its delimiter and retains percent encoding.

    Scheme, host, path, and fragment inspection cannot fail after construction. Each receiver is evaluated once. The returned strings are immutable and inspection has no external effects.

    Read URL.query for decoded query fields. URL.path and URL.fragment do not apply query decoding. In particular, a plus sign in those components remains a plus sign.

    Why

    Component access must preserve delimiters as data and distinguish absence from an empty component. Encoded path and fragment values can be placed back into a URL without turning an escaped separator into structure.

    Examples Read encoded URL components without decoding delimitersDistinguish an absent fragment from an empty fragmentRead IPv6 and file hosts without losing authority dataSerialize a Unicode domain, path, and fragment

    Source evidence

    Read encoded URL components without decoding delimiters

    Link

    run · running · Verification: not-run

    main.tpzRead encoded URL components without decoding delimitersOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("HTTPS://EXAMPLE.COM:8443/a%2Fb?q=a+b#x%20y")) {
    5. case Ok(value) => {
    6. io.writeLine(value.scheme())
    7. match (value.host()) {
    8. case Some(host) => io.writeLine(host)
    9. case None() => io.writeLine("no host")
    10. }
    11. io.writeLine(value.path())
    12. match (value.fragment()) {
    13. case Some(fragment) => io.writeLine(fragment)
    14. case None() => io.writeLine("no fragment")
    15. }
    16. io.writeLine(value.toString())
    17. }
    18. case Err(_) => io.writeLine("parse failed")
    19. }
    Expected outputexit 0
    https
example.com
/a%2Fb
x%20y
https://example.com:8443/a%2Fb?q=a+b#x%20y
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. https
    2. example.com
    3. /a%2Fb
    4. x%20y
    5. https://example.com:8443/a%2Fb?q=a+b#x%20y

    This exact example has not been executed.

    Source evidence

    Distinguish an absent fragment from an empty fragment

    Link

    run · running · Verification: not-run

    main.tpzDistinguish an absent fragment from an empty fragmentOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["mailto:reader@example.com", "mailto:reader@example.com#"]) {
    5. match (URL.parse(text)) {
    6. case Ok(value) => {
    7. io.writeLine(value.scheme())
    8. match (value.host()) {
    9. case None() => io.writeLine("no host")
    10. case Some(host) => io.writeLine("host={host}")
    11. }
    12. io.writeLine(value.path())
    13. match (value.fragment()) {
    14. case None() => io.writeLine("no fragment")
    15. case Some(fragment) => io.writeLine("fragment={fragment}")
    16. }
    17. io.writeLine("{value.query().length}")
    18. }
    19. case Err(_) => io.writeLine("parse failed")
    20. }
    21. }
    Expected outputexit 0
    mailto
no host
reader@example.com
no fragment
0
mailto
no host
reader@example.com
fragment=
0
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. mailto
    2. no host
    3. reader@example.com
    4. no fragment
    5. 0
    6. mailto
    7. no host
    8. reader@example.com
    9. fragment=
    10. 0

    This exact example has not been executed.

    Source evidence

    Read IPv6 and file hosts without losing authority data

    Link

    run · running · Verification: not-run

    main.tpzRead IPv6 and file hosts without losing authority dataOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["https://u:p@[2001:DB8::1]:443/", "file:///tmp/a"]) {
    5. match (URL.parse(text)) {
    6. case Ok(value) => {
    7. match (value.host()) {
    8. case Some(host) => io.writeLine("host={host}")
    9. case None() => io.writeLine("no host")
    10. }
    11. io.writeLine(value.toString())
    12. }
    13. case Err(_) => io.writeLine("parse failed")
    14. }
    15. }
    Expected outputexit 0
    host=[2001:db8::1]
https://u:p@[2001:db8::1]/
host=
file:///tmp/a
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. host=[2001:db8::1]
    2. https://u:p@[2001:db8::1]/
    3. host=
    4. file:///tmp/a

    This exact example has not been executed.

    Source evidence

    Serialize a Unicode domain, path, and fragment

    Link

    run · running · Verification: not-run

    main.tpzSerialize a Unicode domain, path, and fragmentOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("https://bücher.example/한#α")) {
    5. case Ok(value) => {
    6. match (value.host()) {
    7. case Some(host) => io.writeLine(host)
    8. case None() => io.writeLine("no host")
    9. }
    10. io.writeLine(value.path())
    11. match (value.fragment()) {
    12. case Some(fragment) => io.writeLine(fragment)
    13. case None() => io.writeLine("no fragment")
    14. }
    15. io.writeLine(value.toString())
    16. }
    17. case Err(_) => io.writeLine("parse failed")
    18. }
    Expected outputexit 0
    xn--bcher-kva.example
/%ED%95%9C
%CE%B1
https://xn--bcher-kva.example/%ED%95%9C#%CE%B1
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. xn--bcher-kva.example
    2. /%ED%95%9C
    3. %CE%B1
    4. https://xn--bcher-kva.example/%ED%95%9C#%CE%B1

    This exact example has not been executed.

    Source evidence

    Menu

    Download