1 /*
2  * Copyright 2016-2019 JetBrains s.r.o.
3  * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
4  */
5 
6 package androidx.compose.runtime.external.kotlinx.collections.immutable
7 
8 /**
9  * A generic immutable collection of elements. Methods in this interface support only read-only access to the collection.
10  *
11  * Modification operations are supported through the [PersistentCollection] interface.
12  *
13  * Implementors of this interface take responsibility to be immutable.
14  * Once constructed they must contain the same elements in the same order.
15  *
16  * @param E the type of elements contained in the collection. The immutable collection is covariant on its element type.
17  */
18 internal interface ImmutableCollection<out E>: Collection<E>
19 
20 /**
21  * A generic persistent collection of elements that supports adding and removing elements.
22  *
23  * Modification operations return new instances of the persistent collection with the modification applied.
24  *
25  * @param E the type of elements contained in the collection. The persistent collection is covariant on its element type.
26  */
27 internal interface PersistentCollection<out E> : ImmutableCollection<E> {
28     /**
29      * Returns the result of adding the specified [element] to this collection.
30      *
31      * @returns a new persistent collection with the specified [element] added;
32      * or this instance if this collection does not support duplicates and it already contains the element.
33      */
addnull34     fun add(element: @UnsafeVariance E): PersistentCollection<E>
35 
36     /**
37      * Returns the result of adding all elements of the specified [elements] collection to this collection.
38      *
39      * @return a new persistent collection with elements of the specified [elements] collection added;
40      * or this instance if no modifications were made in the result of this operation.
41      */
42     fun addAll(elements: Collection<@UnsafeVariance E>): PersistentCollection<E>
43 
44     /**
45      * Returns the result of removing a single appearance of the specified [element] from this collection.
46      *
47      * @return a new persistent collection with a single appearance of the specified [element] removed;
48      * or this instance if there is no such element in this collection.
49      */
50     fun remove(element: @UnsafeVariance E): PersistentCollection<E>
51 
52     /**
53      * Returns the result of removing all elements in this collection that are also
54      * contained in the specified [elements] collection.
55      *
56      * @return a new persistent collection with elements in this collection that are also
57      * contained in the specified [elements] collection removed;
58      * or this instance if no modifications were made in the result of this operation.
59      */
60     fun removeAll(elements: Collection<@UnsafeVariance E>): PersistentCollection<E>
61 
62     /**
63      * Returns the result of removing all elements in this collection that match the specified [predicate].
64      *
65      * @return a new persistent collection with elements matching the specified [predicate] removed;
66      * or this instance if no elements match the predicate.
67      */
68     fun removeAll(predicate: (E) -> Boolean): PersistentCollection<E>
69 
70     /**
71      * Returns all elements in this collection that are also
72      * contained in the specified [elements] collection.
73      *
74      * @return a new persistent set with elements in this set that are also
75      * contained in the specified [elements] collection;
76      * or this instance if no modifications were made in the result of this operation.
77      */
78     fun retainAll(elements: Collection<@UnsafeVariance E>): PersistentCollection<E>
79 
80     /**
81      * Returns an empty persistent collection.
82      */
83     fun clear(): PersistentCollection<E>
84 
85     /**
86      * A generic builder of the persistent collection. Builder exposes its modification operations through the [MutableCollection] interface.
87      *
88      * Builders are reusable, that is [build] method can be called multiple times with modifications between these calls.
89      * However, modifications applied do not affect previously built persistent collection instances.
90      *
91      * Builder is backed by the same underlying data structure as the persistent collection it was created from.
92      * Thus, [builder] and [build] methods take constant time consisting of passing the backing storage to the
93      * new builder and persistent collection instances, respectively.
94      *
95      * The builder tracks which nodes in the structure are shared with the persistent collection,
96      * and which are owned by it exclusively. It owns the nodes it copied during modification
97      * operations and avoids copying them on subsequent modifications.
98      *
99      * When [build] is called the builder forgets about all owned nodes it had created.
100      */
101     interface Builder<E>: MutableCollection<E> {
102         /**
103          * Returns a persistent collection with the same contents as this builder.
104          *
105          * This method can be called multiple times.
106          *
107          * If operations applied on this builder have caused no modifications:
108          * - on the first call it returns the same persistent collection instance this builder was obtained from.
109          * - on subsequent calls it returns the same previously returned persistent collection instance.
110          */
111         fun build(): PersistentCollection<E>
112     }
113 
114     /**
115      * Returns a new builder with the same contents as this collection.
116      *
117      * The builder can be used to efficiently perform multiple modification operations.
118      */
buildernull119     fun builder(): Builder<@UnsafeVariance E>
120 }
121