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 unordered collection of elements that does not support duplicate elements.
10  * Methods in this interface support only read-only access to the immutable set.
11  *
12  * Modification operations are supported through the [PersistentSet] interface.
13  *
14  * Implementors of this interface take responsibility to be immutable.
15  * Once constructed they must contain the same elements in the same order.
16  *
17  * @param E the type of elements contained in the set. The set is covariant on its element type.
18  */
19 internal interface ImmutableSet<out E>: Set<E>, ImmutableCollection<E>
20 
21 /**
22  * A generic persistent unordered collection of elements that does not support duplicate elements, and supports
23  * adding and removing elements.
24  *
25  * Modification operations return new instances of the persistent set with the modification applied.
26  *
27  * @param E the type of elements contained in the set. The persistent set is covariant on its element type.
28  */
29 internal interface PersistentSet<out E> : ImmutableSet<E>, PersistentCollection<E> {
30     /**
31      * Returns the result of adding the specified [element] to this set.
32      *
33      * @return a new persistent set with the specified [element] added;
34      * or this instance if it already contains the element.
35      */
addnull36     override fun add(element: @UnsafeVariance E): PersistentSet<E>
37 
38     /**
39      * Returns the result of adding all elements of the specified [elements] collection to this set.
40      *
41      * @return a new persistent set with elements of the specified [elements] collection added;
42      * or this instance if it already contains every element of the specified collection.
43      */
44     override fun addAll(elements: Collection<@UnsafeVariance E>): PersistentSet<E>
45 
46     /**
47      * Returns the result of removing the specified [element] from this set.
48      *
49      * @return a new persistent set with the specified [element] removed;
50      * or this instance if there is no such element in this set.
51      */
52     override fun remove(element: @UnsafeVariance E): PersistentSet<E>
53 
54     /**
55      * Returns the result of removing all elements in this set that are also
56      * contained in the specified [elements] collection.
57      *
58      * @return a new persistent set with elements in this set that are also
59      * contained in the specified [elements] collection removed;
60      * or this instance if no modifications were made in the result of this operation.
61      */
62     override fun removeAll(elements: Collection<@UnsafeVariance E>): PersistentSet<E>
63 
64     /**
65      * Returns the result of removing all elements in this set that match the specified [predicate].
66      *
67      * @return a new persistent set with elements matching the specified [predicate] removed;
68      * or this instance if no elements match the predicate.
69      */
70     override fun removeAll(predicate: (E) -> Boolean): PersistentSet<E>
71 
72     /**
73      * Returns all elements in this set that are also
74      * contained in the specified [elements] collection.
75      *
76      * @return a new persistent set with elements in this set that are also
77      * contained in the specified [elements] collection;
78      * or this instance if no modifications were made in the result of this operation.
79      */
80     override fun retainAll(elements: Collection<@UnsafeVariance E>): PersistentSet<E>
81 
82     /**
83      * Returns an empty persistent set.
84      */
85     override fun clear(): PersistentSet<E>
86 
87     /**
88      * A generic builder of the persistent set. Builder exposes its modification operations through the [MutableSet] interface.
89      *
90      * Builders are reusable, that is [build] method can be called multiple times with modifications between these calls.
91      * However, modifications applied do not affect previously built persistent set instances.
92      *
93      * Builder is backed by the same underlying data structure as the persistent set it was created from.
94      * Thus, [builder] and [build] methods take constant time consisting of passing the backing storage to the
95      * new builder and persistent set instances, respectively.
96      *
97      * The builder tracks which nodes in the structure are shared with the persistent set,
98      * and which are owned by it exclusively. It owns the nodes it copied during modification
99      * operations and avoids copying them on subsequent modifications.
100      *
101      * When [build] is called the builder forgets about all owned nodes it had created.
102      */
103     interface Builder<E>: MutableSet<E>, PersistentCollection.Builder<E> {
104         override fun build(): PersistentSet<E>
105     }
106 
buildernull107     override fun builder(): Builder<@UnsafeVariance E>
108 }