Add immutable collections hierarchy with runtime/compiler/docs/tests

docs/Array.md

@@ -1,8 +1,8 @@
 # Array
 
 It's an interface if the [Collection] that provides indexing access, like `array[3] = 0`.
-Array therefore implements [Iterable] too. The well known implementatino of the `Array` is
-[List].
+Array therefore implements [Iterable] too. Well known implementations of `Array` are
+[List] and [ImmutableList].
 
 Array adds the following methods:
 
@@ -35,3 +35,4 @@ To pre-sort and array use `Iterable.sorted*` or in-place `List.sort*` families,
 [Collection]: Collection.md
 [Iterable]: Iterable.md
 [List]: List.md
+[ImmutableList]: ImmutableList.md

docs/Collection.md

@@ -6,6 +6,12 @@ Is a [Iterable] with known `size`, a finite [Iterable]:
         val size
     }
 
+`Collection` is a read/traversal contract shared by mutable and immutable collections.
+Concrete collection classes:
+
+- Mutable: [List], [Set], [Map]
+- Immutable: [ImmutableList], [ImmutableSet], [ImmutableMap]
+
 | name                   | description                                          |
 |------------------------|------------------------------------------------------|
 
@@ -16,4 +22,8 @@ See [List], [Set], [Iterable] and [Efficient Iterables in Kotlin Interop](Effici
 
 [Iterable]: Iterable.md
 [List]: List.md
-[Set]: Set.md
+[Set]: Set.md
+[Map]: Map.md
+[ImmutableList]: ImmutableList.md
+[ImmutableSet]: ImmutableSet.md
+[ImmutableMap]: ImmutableMap.md

docs/ImmutableList.md

@@ -0,0 +1,37 @@
+# ImmutableList built-in class
+
+`ImmutableList` is an immutable, indexable list value.
+It implements [Array], therefore [Collection] and [Iterable].
+
+Use it when API contracts require a list that cannot be mutated through aliases.
+
+## Creating
+
+    val a = ImmutableList(1,2,3)
+    val b = [1,2,3].toImmutable()
+    val c = (1..3).toImmutableList()
+    >>> void
+
+## Converting
+
+    val i = ImmutableList(1,2,3)
+    val m = i.toMutable()
+    m += 4
+    assertEquals( ImmutableList(1,2,3), i )
+    assertEquals( [1,2,3,4], m )
+    >>> void
+
+## Members
+
+| name          | meaning                                 |
+|---------------|-----------------------------------------|
+| `size`        | number of elements                      |
+| `[index]`     | element access by index                 |
+| `[Range]`     | immutable slice                         |
+| `+`           | append element(s), returns new immutable list |
+| `-`           | remove element(s), returns new immutable list |
+| `toMutable()` | create mutable copy                     |
+
+[Array]: Array.md
+[Collection]: Collection.md
+[Iterable]: Iterable.md

docs/ImmutableMap.md

@@ -0,0 +1,36 @@
+# ImmutableMap built-in class
+
+`ImmutableMap` is an immutable map of key-value pairs.
+It implements [Collection] and [Iterable] of [MapEntry].
+
+## Creating
+
+    val a = ImmutableMap("a" => 1, "b" => 2)
+    val b = Map("a" => 1, "b" => 2).toImmutable()
+    val c = ["a" => 1, "b" => 2].toImmutableMap
+    >>> void
+
+## Converting
+
+    val i = ImmutableMap("a" => 1)
+    val m = i.toMutable()
+    m["a"] = 2
+    assertEquals( 1, i["a"] )
+    assertEquals( 2, m["a"] )
+    >>> void
+
+## Members
+
+| name            | meaning                                  |
+|-----------------|------------------------------------------|
+| `size`          | number of entries                        |
+| `[key]`         | get value by key, or `null` if absent    |
+| `getOrNull(key)`| same as `[key]`                          |
+| `keys`          | list of keys                             |
+| `values`        | list of values                           |
+| `+`             | merge (rightmost wins), returns new immutable map |
+| `toMutable()`   | create mutable copy                      |
+
+[Collection]: Collection.md
+[Iterable]: Iterable.md
+[MapEntry]: Map.md

docs/ImmutableSet.md

@@ -0,0 +1,34 @@
+# ImmutableSet built-in class
+
+`ImmutableSet` is an immutable set of unique elements.
+It implements [Collection] and [Iterable].
+
+## Creating
+
+    val a = ImmutableSet(1,2,3)
+    val b = Set(1,2,3).toImmutable()
+    val c = [1,2,3].toImmutableSet
+    >>> void
+
+## Converting
+
+    val i = ImmutableSet(1,2,3)
+    val m = i.toMutable()
+    m += 4
+    assertEquals( ImmutableSet(1,2,3), i )
+    assertEquals( Set(1,2,3,4), m )
+    >>> void
+
+## Members
+
+| name          | meaning                                             |
+|---------------|-----------------------------------------------------|
+| `size`        | number of elements                                  |
+| `contains(x)` | membership test                                     |
+| `+`, `union`  | union, returns new immutable set                    |
+| `-`, `subtract` | subtraction, returns new immutable set            |
+| `*`, `intersect` | intersection, returns new immutable set         |
+| `toMutable()` | create mutable copy                                 |
+
+[Collection]: Collection.md
+[Iterable]: Iterable.md

docs/Iterable.md

@@ -147,12 +147,15 @@ Search for the first element that satisfies the given predicate:
 | fun/method             | description                                                                     |
 |------------------------|---------------------------------------------------------------------------------|
 | toList()               | create a list from iterable                                                     |
+| toImmutableList()      | create an immutable list from iterable                                          |
 | toSet()                | create a set from iterable                                                      |
+| toImmutableSet         | create an immutable set from iterable                                           |
 | contains(i)            | check that iterable contains `i`                                                |
 | `i in iterable`        | same as `contains(i)`                                                           |
 | isEmpty()              | check iterable is empty                                                         |
 | forEach(f)             | call f for each element                                                         |
 | toMap()                | create a map from list of key-value pairs (arrays of 2 items or like)           |
+| toImmutableMap         | create an immutable map from list of key-value pairs                             |
 | any(p)                 | true if any element matches predicate `p`                        |
 | all(p)                 | true if all elements match predicate `p`                         |
 | map(f)                 | create a list of values returned by `f` called for each element of the iterable |
@@ -206,16 +209,20 @@ For high-performance Kotlin-side interop and custom iterable implementation deta
 
 ## Implemented in classes:
 
-- [List], [Range], [Buffer](Buffer.md), [BitBuffer], [Buffer], [Set], [RingBuffer]
+- [List], [ImmutableList], [Range], [Buffer](Buffer.md), [BitBuffer], [Buffer], [Set], [ImmutableSet], [Map], [ImmutableMap], [RingBuffer]
 
 [Collection]: Collection.md
 
 [List]: List.md
+[ImmutableList]: ImmutableList.md
 
 [Flow]: parallelism.md#flow
 
 [Range]: Range.md
 
 [Set]: Set.md
+[ImmutableSet]: ImmutableSet.md
+[Map]: Map.md
+[ImmutableMap]: ImmutableMap.md
 
 [RingBuffer]: RingBuffer.md

docs/List.md

@@ -1,6 +1,7 @@
 # List built-in class
 
 Mutable list of any objects.
+For immutable list values, see [ImmutableList].
 
 It's class in Lyng is `List`:
 
@@ -196,4 +197,5 @@ It inherits from [Iterable] too and thus all iterable methods are applicable to
 
 [Range]: Range.md
 
-[Iterable]: Iterable.md
+[Iterable]: Iterable.md
+[ImmutableList]: ImmutableList.md

docs/Map.md

@@ -3,6 +3,7 @@
 Map is a mutable collection of key-value pairs, where keys are unique. You can create maps in two ways:
 - with the constructor `Map(...)` or `.toMap()` helpers; and
 - with map literals using braces: `{ "key": value, id: expr, id: }`.
+For immutable map values, see [ImmutableMap].
 
 When constructing from a list, each list item must be a [Collection] with exactly 2 elements, for example, a [List].
 
@@ -177,3 +178,4 @@ Notes:
 - When you need computed or non-string keys, use the constructor form `Map(...)`, map literals with computed keys (if supported), or build entries with `=>` and then merge.
 
 [Collection](Collection.md)
+[ImmutableMap]: ImmutableMap.md

docs/Set.md

@@ -1,7 +1,8 @@
-# List built-in class
+# Set built-in class
 
 Mutable set of any objects: a group of different objects, no repetitions.
 Sets are not ordered, order of appearance does not matter.
+For immutable set values, see [ImmutableSet].
 
     val set = Set(1,2,3, "foo")
     assert( 1 in set )
@@ -92,3 +93,4 @@ Also, it inherits methods from [Iterable].
 
 
 [Range]: Range.md
+[ImmutableSet]: ImmutableSet.md

docs/tutorial.md

@@ -14,7 +14,7 @@ __Other documents to read__ maybe after this one:
 - [time](time.md) and [parallelism](parallelism.md)
 - [parallelism] - multithreaded code, coroutines, etc.
 - Some class
-  references: [List], [Set], [Map], [Real], [Range], [Iterable], [Iterator], [time manipulation](time.md), [Array], [RingBuffer], [Buffer].
+  references: [List], [ImmutableList], [Set], [ImmutableSet], [Map], [ImmutableMap], [Real], [Range], [Iterable], [Iterator], [time manipulation](time.md), [Array], [RingBuffer], [Buffer].
 - Some samples: [combinatorics](samples/combinatorics.lyng.md), national vars and
   loops: [сумма ряда](samples/сумма_ряда.lyng.md). More at [samples folder](samples)
 
@@ -785,6 +785,7 @@ Lyng has built-in mutable array class `List` with simple literals:
 
 [List] is an implementation of the type `Array`, and through it `Collection` and [Iterable]. Please read [Iterable],
 many collection based methods are implemented there.
+For immutable list values, use `list.toImmutable()` and [ImmutableList].
 
 Lists can contain any type of objects, lists too:
 
@@ -967,6 +968,7 @@ Set are unordered collection of unique elements, see [Set]. Sets are [Iterable]
     >>> void
 
 Please see [Set] for detailed description.
+For immutable set values, use `set.toImmutable()` and [ImmutableSet].
 
 # Maps
 
@@ -1027,6 +1029,7 @@ Notes:
 - When you need computed (expression) keys or non-string keys, use `Map(...)` constructor with entries, e.g. `Map( ("a" + "b") => 1 )`, then merge with a literal if needed: `{ base: } + (computedKey => 42)`.
 
 Please see the [Map] reference for a deeper guide.
+For immutable map values, use `map.toImmutable()` and [ImmutableMap].
 
 # Flow control operators
 
@@ -1750,6 +1753,7 @@ Lambda avoid unnecessary execution if assertion is not failed. for example:
 | π                                   | See [math](math.md)          |
 
 [List]: List.md
+[ImmutableList]: ImmutableList.md
 
 [Testing]: Testing.md
 
@@ -1766,8 +1770,10 @@ Lambda avoid unnecessary execution if assertion is not failed. for example:
 [string formatting]: https://github.com/sergeych/mp_stools?tab=readme-ov-file#sprintf-syntax-summary
 
 [Set]: Set.md
+[ImmutableSet]: ImmutableSet.md
 
 [Map]: Map.md
+[ImmutableMap]: ImmutableMap.md
 
 [Buffer]: Buffer.md