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

    Collections

    Look up and inspect built-in collection values.

    APIs in this module

    3 APIs

    NameModule
    Map.getCollections
    Map.lengthCollections
    Set.lengthCollections

    Built-in types

    Link

    Array, Map, and Set values are available without a module import. Their members provide collection operations alongside the language rules for literals, membership, and iteration. Assignment and transfer follow collection value semantics. Map and Set observations follow insertion order.

    Why

    Link

    Array preserves element order, Set models membership, and Map associates keys with values. Shared lookup and observation rules make their operations consistent.

    Availability

    Link

    These types are provided by the language. No module import is required. The declarations below describe the standard operations on built-in values.

    Public API

    Link

    Map.get for K, V

    Map.length for K, V

    Set.length for T

    Pending contracts

    Link

    Use Map.get with optional fallback

    Link
    Ruletopaz.stdlib.contract.map-get-fallback.rule

    Use Map.get with optional fallback

    Map<K, V>.get(k) accepts a key of type K and returns Option<V>. A present key produces Some(value), and an absent key produces None(). Lookup does not insert an entry.

    Use map.get(key) ?? fallback to supply a value for an absent key. Evaluate the receiver and key once, then perform the lookup once. A present value skips the fallback. An absent key evaluates the fallback once.

    The fallback must be compatible with V. A stored Option or nullable value remains the payload of a present key. Its inner None() or null does not make that key absent.

    Map.getOr is absent. Its former eager default evaluation is expressed with ordinary bindings when those effects are needed.

    To preserve eager effects, bind the receiver, key, and default in that order. Perform receiver.get(key) ?? default after those bindings. This preserves default evaluation before lookup, including effects that change the map.

    Why

    Map lookup represents absence with Option. The shared coalescing operator supplies defaults with one evaluation rule. Explicit bindings preserve eager effects without a second lookup API.

    Examples Evaluate a fallback for a missing keyReject the removed Map.getOr memberSupply the default with get and ??Preserve eager default effects with ordered bindings

    Diagnostics TPZ5006

    Source evidence

    Evaluate a fallback for a missing key

    Link

    run · running · Verification: not-run

    main.tpzEvaluate a fallback for a missing keyOpen in Playground
    1. import std.io
    3. function fallback() -> int {
    4. io.writeLine("fallback")
    5. 9
    6. }
    8. let values: Map<string, int> = map { "present": 7 }
    9. let present = values.get("present") ?? fallback()
    10. io.writeLine("{present}")
    11. let missing = values.get("missing") ?? fallback()
    12. io.writeLine("{missing}")
    Expected outputexit 0
    7
fallback
9
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 7
    2. fallback
    3. 9

    This exact example has not been executed.

    Source evidence

    Reject the removed Map.getOr member

    Link

    reject · checking · Verification: not-run

    main.tpzReject the removed Map.getOr memberOpen in Playground
    1. let m: Map<string, int> = map { "present": 7 }
    2. m.getOr("present", 9)
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:3

    No stdout.

    This exact example has not been executed.

    Source evidence

    Supply the default with get and ??

    Link

    check · checking · Verification: not-run

    main.tpzSupply the default with get and ??Open in Playground
    1. let m: Map<string, int> = map { "present": 7 }
    2. m.get("present") ?? 9
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Preserve eager default effects with ordered bindings

    Link

    run · running · Verification: not-run

    main.tpzPreserve eager default effects with ordered bindingsOpen in Playground
    1. import std.io
    3. function makeMap() -> Map<string, int> {
    4. io.writeLine("receiver")
    5. map { "present": 7 }
    6. }
    7. function makeKey() -> string {
    8. io.writeLine("key")
    9. "present"
    10. }
    11. function makeFallback() -> int {
    12. io.writeLine("fallback")
    13. 9
    14. }
    16. let receiver = makeMap()
    17. let key = makeKey()
    18. let fallback = makeFallback()
    19. let value = receiver.get(key) ?? fallback
    20. io.writeLine("{value}")
    Expected outputexit 0
    receiver
key
fallback
7
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. receiver
    2. key
    3. fallback
    4. 7

    This exact example has not been executed.

    Source evidence

    Diagnostics

    Link

    Unknown member or field

    Test collection emptiness with length

    Link
    Ruletopaz.stdlib.contract.collection-emptiness.rule

    Test collection emptiness with length

    Test whether a Bytes, Map, or Set value is empty by comparing its length property with zero. The comparison is true exactly when the collection has no bytes, entries, or elements.

    Bytes, Map, and Set do not expose an isEmpty member. Read the length property and use the ordinary equality operator.

    Why

    A collection already exposes its count through length. Comparing that value with zero expresses emptiness for every collection without another query name or a type-specific method.

    Examples Test empty and nonempty maps with lengthTest empty and nonempty sets with lengthTest empty and nonempty byte sequences with lengthReject Bytes.isEmptyReject Map.isEmptyReject Set.isEmpty

    Diagnostics TPZ5006

    Source evidence

    Test empty and nonempty maps with length

    Link

    run · running · Verification: not-run

    main.tpzTest empty and nonempty maps with lengthOpen in Playground
    1. import std.io
    3. let empty: Map<string, int> = map {}
    4. let filled = map { "one": 1 }
    5. io.writeLine("{empty.length == 0}:{filled.length == 0}")
    Expected outputexit 0
    true:false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:false

    This exact example has not been executed.

    Source evidence

    Test empty and nonempty sets with length

    Link

    run · running · Verification: not-run

    main.tpzTest empty and nonempty sets with lengthOpen in Playground
    1. import std.io
    3. let empty: Set<int> = set {}
    4. let filled = set { 1 }
    5. io.writeLine("{empty.length == 0}:{filled.length == 0}")
    Expected outputexit 0
    true:false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:false

    This exact example has not been executed.

    Source evidence

    Test empty and nonempty byte sequences with length

    Link

    run · running · Verification: not-run

    main.tpzTest empty and nonempty byte sequences with lengthOpen in Playground
    1. import std.bytes { Bytes }
    2. import std.test
    3. import std.io
    5. let empty = Bytes.empty()
    6. let filled = test.assertOk(Bytes.fromArray([1]))
    7. io.writeLine("{empty.length == 0}:{filled.length == 0}")
    Expected outputexit 0
    true:false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true:false

    This exact example has not been executed.

    Source evidence

    Reject Bytes.isEmpty

    Link

    reject · checking · Verification: not-run

    main.tpzReject Bytes.isEmptyOpen in Playground
    1. import std.bytes { Bytes }
    2. function inspect(value: Bytes) -> () {
    3. let result = value.isEmpty()
    4. return ()
    5. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:3:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject Map.isEmpty

    Link

    reject · checking · Verification: not-run

    main.tpzReject Map.isEmptyOpen in Playground
    1. function inspect(value: Map<string, int>) -> () {
    2. let result = value.isEmpty()
    3. return ()
    4. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject Set.isEmpty

    Link

    reject · checking · Verification: not-run

    main.tpzReject Set.isEmptyOpen in Playground
    1. function inspect(value: Set<int>) -> () {
    2. let result = value.isEmpty()
    3. return ()
    4. }
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:22

    No stdout.

    This exact example has not been executed.

    Source evidence

    Use in for element membership

    Link
    Ruletopaz.stdlib.contract.membership.rule

    Use in for element membership

    Use x in values for membership in Array<T>, Set<T>, and Range<int>. The element must be compatible with the collection element type. Range membership checks its bounds and step alignment.

    Set.contains is absent. Array does not declare a contains member. Use the membership operator with either collection.

    string.contains(sub) remains a substring query and returns bool. It searches for the contiguous text sub. Strings do not become element-membership operands.

    Map.containsKey(k) remains a query for key presence. A Map is not an element-membership operand. Key presence does not depend on the value stored for that key.

    Why

    One membership operator works across arrays, sets, and ranges. Substring search examines contiguous text, and keyed lookup addresses associations. These queries retain their distinct argument and result contracts.

    Examples Query membership in arrays, sets, and rangesReject the removed Set.contains memberExpress set membership with inReject an undeclared Array.contains memberKeep substring and key-presence queries explicit

    Diagnostics TPZ5006

    Source evidence

    Query membership in arrays, sets, and ranges

    Link

    run · running · Verification: not-run

    main.tpzQuery membership in arrays, sets, and rangesOpen in Playground
    1. import std.io
    3. let values = [1, 2, 3]
    4. let members = set { 1, 3 }
    5. let odd = 1..<6 by 2
    6. io.writeLine("{2 in values}")
    7. io.writeLine("{2 in members}")
    8. io.writeLine("{3 in members}")
    9. io.writeLine("{5 in odd}")
    10. io.writeLine("{4 in odd}")
    Expected outputexit 0
    true
false
true
true
false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. true
    2. false
    3. true
    4. true
    5. false

    This exact example has not been executed.

    Source evidence

    Reject the removed Set.contains member

    Link

    reject · checking · Verification: not-run

    main.tpzReject the removed Set.contains memberOpen in Playground
    1. let s: Set<int> = set { 1, 2 }
    2. s.contains(1)
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:3

    No stdout.

    This exact example has not been executed.

    Source evidence

    Express set membership with in

    Link

    check · checking · Verification: not-run

    main.tpzExpress set membership with inOpen in Playground
    1. let s: Set<int> = set { 1, 2 }
    2. 1 in s
    Expected outputexit 0
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    No stdout.

    This exact example has not been executed.

    Source evidence

    Reject an undeclared Array.contains member

    Link

    reject · checking · Verification: not-run

    main.tpzReject an undeclared Array.contains memberOpen in Playground
    1. let a: Array<int> = [1, 2]
    2. a.contains(1)
    Expected outputNonzero exit
    No stdout.
    $ topaz check main.tpz --format json · target product 5.21.3
    Expected result

    Expected result

    Rejection during check. Nonzero exit.

    • TPZ5006 stdlib-removed-member at main.tpz:2:3

    No stdout.

    This exact example has not been executed.

    Source evidence

    Keep substring and key-presence queries explicit

    Link

    run · running · Verification: not-run

    main.tpzKeep substring and key-presence queries explicitOpen in Playground
    1. import std.io
    3. let substring = "Topaz".contains("opa")
    4. let separated = "Topaz".contains("Tp")
    5. let values: Map<string, int> = map { "key": 1 }
    6. let present = values.containsKey("key")
    7. let absent = values.containsKey("other")
    8. io.writeLine("{substring}")
    9. io.writeLine("{separated}")
    10. io.writeLine("{present}")
    11. io.writeLine("{absent}")
    Expected outputexit 0
    true
false
true
false
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

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

    This exact example has not been executed.

    Source evidence

    Menu

    Download