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.query

    Returns an independent map of form-decoded query names and ordered value arrays.

    query() -> Map<string, Array<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.query returns a new Map from decoded names to arrays of decoded values. A missing query and an empty query both produce an empty map.

    Query decoding follows application/x-www-form-urlencoded parsing. Ampersands separate fields. Empty fields between separators are skipped. The first equals sign separates each name from its value. A field without that sign has an empty value.

    An explicit empty name is retained. A plus sign decodes to an ASCII space. Valid percent escapes decode to bytes and those bytes decode as UTF-8. Malformed percent escapes remain literal text and invalid UTF-8 sequences use the replacement character.

    Repeated names are grouped after decoding. Values retain encounter order. Map keys retain the order in which their decoded names first appear. No sorting, deduplication, or comma splitting occurs.

    The returned Map and its value arrays follow collection value semantics. URL.toString preserves the stored serialized query rather than serializing this map.

    Reading a query evaluates its receiver once and performs no external operation. A constructed URL can always produce its query map. Query decoding does not return a diagnostic or a Result error.

    Related rule: Decode query fields into an independent map

    Result

    Additional contracts are Pending.

    The declared result type is Map<string, Array<string>>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Returns an independent map of form-decoded query names and ordered value arrays.

    Resolved contracts

    Link

    Related entries

    Link

    std.url

    Decode query fields into an independent map

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

    Decode query fields into an independent map

    URL.query returns a new Map from decoded names to arrays of decoded values. A missing query and an empty query both produce an empty map.

    Query decoding follows application/x-www-form-urlencoded parsing. Ampersands separate fields. Empty fields between separators are skipped. The first equals sign separates each name from its value. A field without that sign has an empty value.

    An explicit empty name is retained. A plus sign decodes to an ASCII space. Valid percent escapes decode to bytes and those bytes decode as UTF-8. Malformed percent escapes remain literal text and invalid UTF-8 sequences use the replacement character.

    Repeated names are grouped after decoding. Values retain encounter order. Map keys retain the order in which their decoded names first appear. No sorting, deduplication, or comma splitting occurs.

    The returned Map and its value arrays follow collection value semantics. URL.toString preserves the stored serialized query rather than serializing this map.

    Reading a query evaluates its receiver once and performs no external operation. A constructed URL can always produce its query map. Query decoding does not return a diagnostic or a Result error.

    Why

    Query syntax has its own escaping rules and permits repeated names. Grouped arrays preserve every value while immutable URLs keep query inspection from silently rewriting a link.

    Examples Decode repeated query fields and preserve their value orderSkip empty separators while retaining an explicit empty fieldKeep malformed percent escapes as query dataReplace an invalid decoded UTF-8 byte in a query fieldMutate a query snapshot without changing its URL

    Source evidence

    Decode repeated query fields and preserve their value order

    Link

    run · running · Verification: not-run

    main.tpzDecode repeated query fields and preserve their value orderOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("https://example.com/?q=a+b&q=%ED%95%9C&empty&x=a=b&=blank")) {
    5. case Ok(value) => {
    6. let fields = value.query()
    7. for name in (["q", "empty", "x", ""]) {
    8. match (fields.get(name)) {
    9. case Some(values) => {
    10. for item in (values) {
    11. io.writeLine("{name}={item}")
    12. }
    13. }
    14. case None() => io.writeLine("missing")
    15. }
    16. }
    17. }
    18. case Err(_) => io.writeLine("parse failed")
    19. }
    Expected outputexit 0
    q=a b
q=한
empty=
x=a=b
=blank
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. q=a b
    2. q=한
    3. empty=
    4. x=a=b
    5. =blank

    This exact example has not been executed.

    Source evidence

    Skip empty separators while retaining an explicit empty field

    Link

    run · running · Verification: not-run

    main.tpzSkip empty separators while retaining an explicit empty fieldOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["https://example.com/", "https://example.com/?", "https://example.com/?&&a=1&&", "https://example.com/?="]) {
    5. match (URL.parse(text)) {
    6. case Ok(value) => {
    7. let fields = value.query()
    8. let hasEmptyName = fields.containsKey("")
    9. io.writeLine("{fields.length}:{hasEmptyName}")
    10. }
    11. case Err(_) => io.writeLine("parse failed")
    12. }
    13. }
    Expected outputexit 0
    0:false
0:false
1:false
1:true
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0:false
    2. 0:false
    3. 1:false
    4. 1:true

    This exact example has not been executed.

    Source evidence

    Keep malformed percent escapes as query data

    Link

    run · running · Verification: not-run

    main.tpzKeep malformed percent escapes as query dataOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. for text in (["https://example.com/?x=%", "https://example.com/?x=%GG"]) {
    5. match (URL.parse(text)) {
    6. case Ok(value) => {
    7. match (value.query().get("x")) {
    8. case Some(values) => io.writeLine(values[0])
    9. case None() => io.writeLine("missing")
    10. }
    11. }
    12. case Err(_) => io.writeLine("parse failed")
    13. }
    14. }
    Expected outputexit 0
    %
%GG
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. %
    2. %GG

    This exact example has not been executed.

    Source evidence

    Replace an invalid decoded UTF-8 byte in a query field

    Link

    run · running · Verification: not-run

    main.tpzReplace an invalid decoded UTF-8 byte in a query fieldOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("https://example.com/?x=%ff")) {
    5. case Ok(value) => {
    6. match (value.query().get("x")) {
    7. case Some(values) => io.writeLine(values[0])
    8. case None() => io.writeLine("missing")
    9. }
    10. io.writeLine(value.toString())
    11. }
    12. case Err(_) => io.writeLine("parse failed")
    13. }
    Expected outputexit 0
    �
https://example.com/?x=%ff
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. �
    2. https://example.com/?x=%ff

    This exact example has not been executed.

    Source evidence

    Mutate a query snapshot without changing its URL

    Link

    run · running · Verification: not-run

    main.tpzMutate a query snapshot without changing its URLOpen in Playground
    1. import std.url { URL }
    2. import std.io
    4. match (URL.parse("https://example.com/?k=first")) {
    5. case Ok(value) => {
    6. let mut snapshot = value.query()
    7. snapshot.insert("k", ["changed", "again"])
    8. snapshot.insert("extra", ["local"])
    9. let reread = value.query()
    10. io.writeLine("{reread.length}")
    11. match (reread.get("k")) {
    12. case Some(values) => {
    13. for item in (values) {
    14. io.writeLine(item)
    15. }
    16. }
    17. case None() => io.writeLine("missing")
    18. }
    19. io.writeLine(value.toString())
    20. }
    21. case Err(_) => io.writeLine("parse failed")
    22. }
    Expected outputexit 0
    1
first
https://example.com/?k=first
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 1
    2. first
    3. https://example.com/?k=first

    This exact example has not been executed.

    Source evidence

    Menu

    Download