Skip to content

Commit 59cdbbb

Browse files
committed
Clarify builders behavior, minor edits.
1 parent 7d427bd commit 59cdbbb

File tree

1 file changed

+10
-3
lines changed

1 file changed

+10
-3
lines changed

proposal.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,14 @@ Provide implementation of those interfaces.
2222
There are two families of collection interfaces in the Standard Library:
2323

2424
* 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.
2626

2727
Kotlin mostly doesn't provide its own collection implementations.
2828
Its collection interfaces are mapped to the standard JDK collection interfaces
2929
and implemented by the JDK collection implementations, such as `ArrayList`, `HashSet`, `HashMap` and other
3030
classes from `java.util` package.
3131

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
3333
and specify by the contract the real immutability of their implementors.
3434

3535
### Modification operations
@@ -39,20 +39,24 @@ Immutable collections could have same modification operations as their mutable c
3939
return new immutable collection instance with the modification applied.
4040

4141
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.
4343

4444
### Builders
4545

4646
Often there is a need to perform several subsequent modification operations on an immutable collection. It can be done by
4747
- chaining operations together:
48+
4849
```
4950
collection = collection.add(element).add(anotherElement)
5051
```
52+
5153
- applying operations one by one:
54+
5255
```
5356
collection += element
5457
collection += anotherElement
5558
```
59+
5660
- using collection builders.
5761
5862
An immutable collection builder is a wrapper around an immutable collection, which exposes its modification operations
@@ -70,6 +74,9 @@ if (builder.isEmpty()) {
7074
return builder.build()
7175
```
7276
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+
7380
In case if each operation invoked on a builder causes no modifications,
7481
the collection returned by `build()` method is the same collection the builder was obtained from.
7582

0 commit comments

Comments
 (0)