@@ -22,14 +22,14 @@ Provide implementation of those interfaces.
22
22
There are two families of collection interfaces in the Standard Library:
23
23
24
24
* read-only interfaces, which only allow to read elements from a collection;
25
- * mutable interfaces, which additionally allows to modify elements in a collection.
25
+ * mutable interfaces, which additionally allow to modify elements in a collection.
26
26
27
27
Kotlin mostly doesn't provide its own collection implementations.
28
28
Its collection interfaces are mapped to the standard JDK collection interfaces
29
29
and implemented by the JDK collection implementations, such as ` ArrayList ` , ` HashSet ` , ` HashMap ` and other
30
30
classes from ` java.util ` package.
31
31
32
- It is proposed to provide immutable collection interfaces which extend read-only interfaces
32
+ It is proposed to provide immutable collection interfaces which extend read-only collection interfaces
33
33
and specify by the contract the real immutability of their implementors.
34
34
35
35
### Modification operations
@@ -39,20 +39,24 @@ Immutable collections could have same modification operations as their mutable c
39
39
return new immutable collection instance with the modification applied.
40
40
41
41
In case if no modification is made during the operation, for example, adding an existing element to a set or clearing
42
- already empty collection, it should return the same instance of the immutable collection.
42
+ already empty collection, the operation should return the same instance of the immutable collection.
43
43
44
44
### Builders
45
45
46
46
Often there is a need to perform several subsequent modification operations on an immutable collection. It can be done by
47
47
- chaining operations together:
48
+
48
49
```
49
50
collection = collection.add(element).add(anotherElement)
50
51
```
52
+
51
53
- applying operations one by one:
54
+
52
55
```
53
56
collection += element
54
57
collection += anotherElement
55
58
```
59
+
56
60
- using collection builders.
57
61
58
62
An immutable collection builder is a wrapper around an immutable collection, which exposes its modification operations
@@ -70,6 +74,9 @@ if (builder.isEmpty()) {
70
74
return builder.build()
71
75
```
72
76
77
+ When mutating operation is invoked on a builder, it doesn't mutate the original immutable collection it was built from,
78
+ but instead it gradually builds new immutable collection with the requested modifications applied.
79
+
73
80
In case if each operation invoked on a builder causes no modifications,
74
81
the collection returned by `build()` method is the same collection the builder was obtained from.
75
82
0 commit comments