Skip to content
Topazdocs
6.05.21

Search documentation

Specification 6.0

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

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

    Download →

    Library · Collections

    Range.map

    Call a function once per element in iteration order and collect the results in an array.

    map(f: (int) -> U) -> Array<U>
    Receiver
    Range
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Availability

    Included by default · yes

    These types are provided by the language. No module import is required.

    The declarations below describe the standard operations on built-in values.

    Receiver

    Range

    Parameter constraints

    Additional contracts are Pending.

    Array<T>, Set<T> and Range values provide map, filter and reduce. A range supplies int elements.

    Each call makes one complete pass over the receiver in its iteration order. Arrays use element order. Sets use insertion order. Ranges use the order of their bounds and step.

    map(f) calls f once per element and returns an array of the results in that order.

    filter(f) calls f once per element and returns an array of the elements for which f returned true, in that order. Set and Range receivers also produce an array.

    reduce(initial, f) starts with initial and calls f with the current accumulator and each element in order. It returns the last accumulator. An empty receiver returns initial without calling f.

    Receiver and callback evaluation, chaining and callback propagation follow the callback and comprehension rule.

    Related rule · Transform arrays, sets and ranges with callbacks →

    Result

    Additional contracts are Pending.

    The declared result type is Array<U>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Each element of type int passes to the function once. The results keep the receiver's iteration order.

    Related entries

    Collections →

    Transform arrays, sets and ranges with callbacks

    Ruletopaz.stdlib.contract.iterable-callbacks.rule

    Transform arrays, sets and ranges with callbacks

    Array<T>, Set<T> and Range values provide map, filter and reduce. A range supplies int elements.

    Each call makes one complete pass over the receiver in its iteration order. Arrays use element order. Sets use insertion order. Ranges use the order of their bounds and step.

    map(f) calls f once per element and returns an array of the results in that order.

    filter(f) calls f once per element and returns an array of the elements for which f returned true, in that order. Set and Range receivers also produce an array.

    reduce(initial, f) starts with initial and calls f with the current accumulator and each element in order. It returns the last accumulator. An empty receiver returns initial without calling f.

    Receiver and callback evaluation, chaining and callback propagation follow the callback and comprehension rule.

    Why

    A for loop and a comprehension already accept arrays, sets and ranges in the same way. Callback methods accept the same receivers, so the choice between a callback chain and a comprehension follows intent and not the receiver type. map and filter return arrays for every receiver, so a chain has one result shape.

    Examples Observe one pass per array method →Transform sets and ranges into arrays →Return empty arrays and the initial value for empty receivers →

    Observe one pass per array method

    run · running · Verification · not-run

    main.tpzObserve one pass per array methodOpen in Playground →
    1. import std.io
    3. function scaled(value: int) -> int {
    4. io.writeLine("map {value}")
    5. value * 10
    6. }
    7. function kept(value: int) -> bool {
    8. io.writeLine("filter {value}")
    9. value != 2
    10. }
    12. let values = [1, 2, 3]
    13. let mapped = values.map(scaled)
    14. let selected = values.filter(kept)
    15. let total = values.reduce(100, (sum: int, value: int) => {
    16. io.writeLine("reduce {sum} {value}")
    17. sum - value
    18. })
    19. io.writeLine("{mapped[0]} {mapped[1]} {mapped[2]}")
    20. io.writeLine("{selected.length} {selected[0]} {selected[1]}")
    21. io.writeLine("{total}")
    Expected outputExit code 0
    map 1
map 2
map 3
filter 1
filter 2
filter 3
reduce 100 1
reduce 99 2
reduce 97 3
10 20 30
2 1 3
94
    $ topaz run main.tpz · Target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. map 1
    2. map 2
    3. map 3
    4. filter 1
    5. filter 2
    6. filter 3
    7. reduce 100 1
    8. reduce 99 2
    9. reduce 97 3
    10. 10 20 30
    11. 2 1 3
    12. 94

    This exact example has not been executed.

    Transform sets and ranges into arrays

    run · running · Verification · not-run

    main.tpzTransform sets and ranges into arraysOpen in Playground →
    1. import std.io
    3. let marks = set { 3, 1, 2 }
    4. let doubled: Array<int> = marks.map((value: int) => value * 2)
    5. let large: Array<int> = marks.filter((value: int) => value > 1)
    6. let digits = marks.reduce("", (text: string, value: int) => text + "{value}")
    7. io.writeLine("{doubled[0]} {doubled[1]} {doubled[2]}")
    8. io.writeLine("{large.length} {large[0]} {large[1]}")
    9. io.writeLine(digits)
    11. let squares: Array<int> = (0..<4).map((value: int) => value * value)
    12. let even: Array<int> = (1..6).filter((value: int) => value % 2 == 0)
    13. let number = (1..4).reduce(0, (total: int, value: int) => total * 10 + value)
    14. io.writeLine("{squares.length} {squares[3]}")
    15. io.writeLine("{even.length} {even[0]} {even[2]}")
    16. io.writeLine("{number}")
    Expected outputExit code 0
    6 2 4
2 3 2
312
4 9
3 2 6
1234
    $ topaz run main.tpz · Target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 6 2 4
    2. 2 3 2
    3. 312
    4. 4 9
    5. 3 2 6
    6. 1234

    This exact example has not been executed.

    Return empty arrays and the initial value for empty receivers

    run · running · Verification · not-run

    main.tpzReturn empty arrays and the initial value for empty receiversOpen in Playground →
    1. import std.io
    3. function never(value: int) -> int {
    4. io.writeLine("called {value}")
    5. value
    6. }
    8. let none: Array<int> = []
    9. let nothing: Set<int> = set {}
    10. let mapped = none.map(never)
    11. let selected = nothing.filter((value: int) => never(value) > 0)
    12. let total = (5..<5).reduce(7, (sum: int, value: int) => sum + never(value))
    13. io.writeLine("{mapped.length} {selected.length} {total}")
    Expected outputExit code 0
    0 0 7
    $ topaz run main.tpz · Target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 0 0 7

    This exact example has not been executed.

    Menu

    Download →