How do I merge two lists or two dicts in EK9?

EK9 provides the :~: merge operator for in-place merging and the + operator for creating new merged collections.

LIST MERGE (:~:)

Append all items from source to target:

  target :~: source

Modifies target in place.

LIST PLUS (+)

Create a new combined list:

  combined <- list1 + list2

Both originals unchanged.

DICT MERGE (:~:)

Merge entries from source into target:

  target :~: source

When keys overlap, the source values win.

DICT PLUS (+)

Create a new merged dict:

  combined <- dict1 + dict2

COPY (:=:)

Deep copy one collection into another:

  target :=: source

Replaces the target contents entirely.

See Q88 for List operations. See Q90 for Dict operations. See Q130 for mutating vs non-mutating operators.

Example

defines module qa.collectiontasks.mergecollections

  defines program
    MergeCollectionsDemo()
      stdout <- Stdout()

      // === LIST MERGE (:~:) ===

      list1 <- [1, 2, 3]
      list2 <- [4, 5, 6]
      list1 :~: list2
      stdout.println(`List merge: ${list1}`)

      // === LIST PLUS (+) ===

      left <- [10, 20]
      right <- [30, 40]
      combined <- left + right
      stdout.println(`List +: ${combined}`)
      stdout.println(`Left unchanged: ${left}`)

      // === DICT MERGE (:~:) ===

      d1 <- {"a": 1, "b": 2}
      d2 <- {"b": 99, "c": 3}
      d1 :~: d2
      stdout.println(`Dict merge: ${d1}`)

      // === DICT PLUS (+) ===

      base <- {"x": 10}
      extra <- {"y": 20, "z": 30}
      merged <- base + extra
      stdout.println(`Dict +: ${merged}`)
      stdout.println(`Base unchanged: ${base}`)

      // === COPY (:=:) ===

      source <- [100, 200, 300]
      target <- List() of Integer
      target :=: source
      stdout.println(`Copied list: ${target}`)

      srcDict <- {"key": 42}
      tgtDict <- Dict() of (String, Integer)
      tgtDict :=: srcDict
      stdout.println(`Copied dict: ${tgtDict}`)

      // === MERGE SINGLE ITEM ===

      names <- ["Alice", "Bob"]
      names :~: "Charlie"
      stdout.println(`After merge single: ${names}`)

Common mistakes

E50060 — EK9 uses the :~: merge operator for in-place collection merging, not an addAll() method. See ek9 -h E50060 for details.

Incorrect:

list1.addAll(list2)

Correct:

list1 :~: list2

E50060 — EK9 uses the :~: merge operator for merging Dict entries, not a putAll() method. When keys overlap, source values win. See ek9 -h E50060 for details.

Incorrect:

d1.putAll(d2)

Correct:

d1 :~: d2

Other ways to ask this

How do I combine two collections in EK9?
What is the EK9 equivalent of addAll() or putAll()?
How do I join or concatenate two lists in EK9?

Coming from another language?

Java: list.addAll(other), map.putAll(other), no operator syntax. Python: list.extend(other), dict.update(other), | for dict union. Rust: vec.extend(other), map.extend(other). Go: append(slice1, slice2...), manual loop for maps. JavaScript: [...arr1, ...arr2], Object.assign(). Kotlin: list + other, map + other. EK9: :~: merge operator, + for new combined collection, :=: for deep copy.

Keywords: collection, append, combine, join, dict, merge, task, concatenate, list, union, copy