1 // Licensed to the .NET Foundation under one or more agreements.
2 // The .NET Foundation licenses this file to you under the MIT license.
3 // See the LICENSE file in the project root for more information.
4 
5 using System.Collections.Generic;
6 
7 namespace System.Collections.Immutable
8 {
9     /// <summary>
10     /// An interface that describes the methods that the <see cref="ImmutableList{T}"/> and <see cref="ImmutableList{T}.Builder"/> types have in common.
11     /// </summary>
12     /// <typeparam name="T">The type of element in the collection.</typeparam>
13     internal interface IImmutableListQueries<T> : IReadOnlyList<T>
14     {
15         /// <summary>
16         /// Converts the elements in the current <see cref="ImmutableList{T}"/> to
17         /// another type, and returns a list containing the converted elements.
18         /// </summary>
19         /// <param name="converter">
20         /// A <see cref="Func{T, TResult}"/> delegate that converts each element from
21         /// one type to another type.
22         /// </param>
23         /// <typeparam name="TOutput">
24         /// The type of the elements of the target array.
25         /// </typeparam>
26         /// <returns>
27         /// A <see cref="ImmutableList{T}"/> of the target type containing the converted
28         /// elements from the current <see cref="ImmutableList{T}"/>.
29         /// </returns>
ConvertAll(Func<T, TOutput> converter)30         ImmutableList<TOutput> ConvertAll<TOutput>(Func<T, TOutput> converter);
31 
32         /// <summary>
33         /// Performs the specified action on each element of the list.
34         /// </summary>
35         /// <param name="action">The <see cref="Action{T}"/> delegate to perform on each element of the list.</param>
ForEach(Action<T> action)36         void ForEach(Action<T> action);
37 
38         /// <summary>
39         /// Creates a shallow copy of a range of elements in the source <see cref="ImmutableList{T}"/>.
40         /// </summary>
41         /// <param name="index">
42         /// The zero-based <see cref="ImmutableList{T}"/> index at which the range
43         /// starts.
44         /// </param>
45         /// <param name="count">
46         /// The number of elements in the range.
47         /// </param>
48         /// <returns>
49         /// A shallow copy of a range of elements in the source <see cref="ImmutableList{T}"/>.
50         /// </returns>
GetRange(int index, int count)51         ImmutableList<T> GetRange(int index, int count);
52 
53         /// <summary>
54         /// Copies the entire <see cref="ImmutableList{T}"/> to a compatible one-dimensional
55         /// array, starting at the beginning of the target array.
56         /// </summary>
57         /// <param name="array">
58         /// The one-dimensional <see cref="Array"/> that is the destination of the elements
59         /// copied from <see cref="ImmutableList{T}"/>. The <see cref="Array"/> must have
60         /// zero-based indexing.
61         /// </param>
CopyTo(T[] array)62         void CopyTo(T[] array);
63 
64         /// <summary>
65         /// Copies the entire <see cref="ImmutableList{T}"/> to a compatible one-dimensional
66         /// array, starting at the specified index of the target array.
67         /// </summary>
68         /// <param name="array">
69         /// The one-dimensional <see cref="Array"/> that is the destination of the elements
70         /// copied from <see cref="ImmutableList{T}"/>. The <see cref="Array"/> must have
71         /// zero-based indexing.
72         /// </param>
73         /// <param name="arrayIndex">
74         /// The zero-based index in <paramref name="array"/> at which copying begins.
75         /// </param>
CopyTo(T[] array, int arrayIndex)76         void CopyTo(T[] array, int arrayIndex);
77 
78         /// <summary>
79         /// Copies a range of elements from the <see cref="ImmutableList{T}"/> to
80         /// a compatible one-dimensional array, starting at the specified index of the
81         /// target array.
82         /// </summary>
83         /// <param name="index">
84         /// The zero-based index in the source <see cref="ImmutableList{T}"/> at
85         /// which copying begins.
86         /// </param>
87         /// <param name="array">
88         /// The one-dimensional <see cref="Array"/> that is the destination of the elements
89         /// copied from <see cref="ImmutableList{T}"/>. The <see cref="Array"/> must have
90         /// zero-based indexing.
91         /// </param>
92         /// <param name="arrayIndex">The zero-based index in <paramref name="array"/> at which copying begins.</param>
93         /// <param name="count">The number of elements to copy.</param>
CopyTo(int index, T[] array, int arrayIndex, int count)94         void CopyTo(int index, T[] array, int arrayIndex, int count);
95 
96         /// <summary>
97         /// Determines whether the <see cref="ImmutableList{T}"/> contains elements
98         /// that match the conditions defined by the specified predicate.
99         /// </summary>
100         /// <param name="match">
101         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the elements
102         /// to search for.
103         /// </param>
104         /// <returns>
105         /// true if the <see cref="ImmutableList{T}"/> contains one or more elements
106         /// that match the conditions defined by the specified predicate; otherwise,
107         /// false.
108         /// </returns>
Exists(Predicate<T> match)109         bool Exists(Predicate<T> match);
110 
111         /// <summary>
112         /// Searches for an element that matches the conditions defined by the specified
113         /// predicate, and returns the first occurrence within the entire <see cref="ImmutableList{T}"/>.
114         /// </summary>
115         /// <param name="match">
116         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the element
117         /// to search for.
118         /// </param>
119         /// <returns>
120         /// The first element that matches the conditions defined by the specified predicate,
121         /// if found; otherwise, the default value for type <typeparamref name="T"/>.
122         /// </returns>
Find(Predicate<T> match)123         T Find(Predicate<T> match);
124 
125         /// <summary>
126         /// Retrieves all the elements that match the conditions defined by the specified
127         /// predicate.
128         /// </summary>
129         /// <param name="match">
130         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the elements
131         /// to search for.
132         /// </param>
133         /// <returns>
134         /// A <see cref="ImmutableList{T}"/> containing all the elements that match
135         /// the conditions defined by the specified predicate, if found; otherwise, an
136         /// empty <see cref="ImmutableList{T}"/>.
137         /// </returns>
FindAll(Predicate<T> match)138         ImmutableList<T> FindAll(Predicate<T> match);
139 
140         /// <summary>
141         /// Searches for an element that matches the conditions defined by the specified
142         /// predicate, and returns the zero-based index of the first occurrence within
143         /// the entire <see cref="ImmutableList{T}"/>.
144         /// </summary>
145         /// <param name="match">
146         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the element
147         /// to search for.
148         /// </param>
149         /// <returns>
150         /// The zero-based index of the first occurrence of an element that matches the
151         /// conditions defined by <paramref name="match"/>, if found; otherwise, -1.
152         /// </returns>
FindIndex(Predicate<T> match)153         int FindIndex(Predicate<T> match);
154 
155         /// <summary>
156         /// Searches for an element that matches the conditions defined by the specified
157         /// predicate, and returns the zero-based index of the first occurrence within
158         /// the range of elements in the <see cref="ImmutableList{T}"/> that extends
159         /// from the specified index to the last element.
160         /// </summary>
161         /// <param name="startIndex">The zero-based starting index of the search.</param>
162         /// <param name="match">The <see cref="Predicate{T}"/> delegate that defines the conditions of the element to search for.</param>
163         /// <returns>
164         /// The zero-based index of the first occurrence of an element that matches the
165         /// conditions defined by <paramref name="match"/>, if found; otherwise, -1.
166         /// </returns>
FindIndex(int startIndex, Predicate<T> match)167         int FindIndex(int startIndex, Predicate<T> match);
168 
169         /// <summary>
170         /// Searches for an element that matches the conditions defined by the specified
171         /// predicate, and returns the zero-based index of the first occurrence within
172         /// the range of elements in the <see cref="ImmutableList{T}"/> that starts
173         /// at the specified index and contains the specified number of elements.
174         /// </summary>
175         /// <param name="startIndex">The zero-based starting index of the search.</param>
176         /// <param name="count">The number of elements in the section to search.</param>
177         /// <param name="match">The <see cref="Predicate{T}"/> delegate that defines the conditions of the element to search for.</param>
178         /// <returns>
179         /// The zero-based index of the first occurrence of an element that matches the
180         /// conditions defined by <paramref name="match"/>, if found; otherwise, -1.
181         /// </returns>
FindIndex(int startIndex, int count, Predicate<T> match)182         int FindIndex(int startIndex, int count, Predicate<T> match);
183 
184         /// <summary>
185         /// Searches for an element that matches the conditions defined by the specified
186         /// predicate, and returns the last occurrence within the entire <see cref="ImmutableList{T}"/>.
187         /// </summary>
188         /// <param name="match">
189         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the element
190         /// to search for.
191         /// </param>
192         /// <returns>
193         /// The last element that matches the conditions defined by the specified predicate,
194         /// if found; otherwise, the default value for type <typeparamref name="T"/>.
195         /// </returns>
FindLast(Predicate<T> match)196         T FindLast(Predicate<T> match);
197 
198         /// <summary>
199         /// Searches for an element that matches the conditions defined by the specified
200         /// predicate, and returns the zero-based index of the last occurrence within
201         /// the entire <see cref="ImmutableList{T}"/>.
202         /// </summary>
203         /// <param name="match">
204         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the element
205         /// to search for.
206         /// </param>
207         /// <returns>
208         /// The zero-based index of the last occurrence of an element that matches the
209         /// conditions defined by <paramref name="match"/>, if found; otherwise, -1.
210         /// </returns>
FindLastIndex(Predicate<T> match)211         int FindLastIndex(Predicate<T> match);
212 
213         /// <summary>
214         /// Searches for an element that matches the conditions defined by the specified
215         /// predicate, and returns the zero-based index of the last occurrence within
216         /// the range of elements in the <see cref="ImmutableList{T}"/> that extends
217         /// from the first element to the specified index.
218         /// </summary>
219         /// <param name="startIndex">The zero-based starting index of the backward search.</param>
220         /// <param name="match">The <see cref="Predicate{T}"/> delegate that defines the conditions of the element
221         /// to search for.</param>
222         /// <returns>
223         /// The zero-based index of the last occurrence of an element that matches the
224         /// conditions defined by <paramref name="match"/>, if found; otherwise, -1.
225         /// </returns>
FindLastIndex(int startIndex, Predicate<T> match)226         int FindLastIndex(int startIndex, Predicate<T> match);
227 
228         /// <summary>
229         /// Searches for an element that matches the conditions defined by the specified
230         /// predicate, and returns the zero-based index of the last occurrence within
231         /// the range of elements in the <see cref="ImmutableList{T}"/> that contains
232         /// the specified number of elements and ends at the specified index.
233         /// </summary>
234         /// <param name="startIndex">The zero-based starting index of the backward search.</param>
235         /// <param name="count">The number of elements in the section to search.</param>
236         /// <param name="match">
237         /// The <see cref="Predicate{T}"/> delegate that defines the conditions of the element
238         /// to search for.
239         /// </param>
240         /// <returns>
241         /// The zero-based index of the last occurrence of an element that matches the
242         /// conditions defined by <paramref name="match"/>, if found; otherwise, -1.
243         /// </returns>
FindLastIndex(int startIndex, int count, Predicate<T> match)244         int FindLastIndex(int startIndex, int count, Predicate<T> match);
245 
246         /// <summary>
247         /// Determines whether every element in the <see cref="ImmutableList{T}"/>
248         /// matches the conditions defined by the specified predicate.
249         /// </summary>
250         /// <param name="match">
251         /// The <see cref="Predicate{T}"/> delegate that defines the conditions to check against
252         /// the elements.
253         /// </param>
254         /// <returns>
255         /// true if every element in the <see cref="ImmutableList{T}"/> matches the
256         /// conditions defined by the specified predicate; otherwise, false. If the list
257         /// has no elements, the return value is true.
258         /// </returns>
TrueForAll(Predicate<T> match)259         bool TrueForAll(Predicate<T> match);
260 
261         /// <summary>
262         /// Searches the entire sorted <see cref="IReadOnlyList{T}"/> for an element
263         /// using the default comparer and returns the zero-based index of the element.
264         /// </summary>
265         /// <param name="item">The object to locate. The value can be null for reference types.</param>
266         /// <returns>
267         /// The zero-based index of <paramref name="item"/> in the sorted <see cref="IReadOnlyList{T}"/>,
268         /// if <paramref name="item"/> is found; otherwise, a negative number that is the bitwise complement
269         /// of the index of the next element that is larger than <paramref name="item"/> or, if there is
270         /// no larger element, the bitwise complement of <see cref="IReadOnlyCollection{T}.Count"/>.
271         /// </returns>
272         /// <exception cref="InvalidOperationException">
273         /// The default comparer <see cref="Comparer{T}.Default"/> cannot
274         /// find an implementation of the <see cref="IComparable{T}"/> generic interface or
275         /// the <see cref="IComparable"/> interface for type <typeparamref name="T"/>.
276         /// </exception>
BinarySearch(T item)277         int BinarySearch(T item);
278 
279         /// <summary>
280         ///  Searches the entire sorted <see cref="IReadOnlyList{T}"/> for an element
281         ///  using the specified comparer and returns the zero-based index of the element.
282         /// </summary>
283         /// <param name="item">The object to locate. The value can be null for reference types.</param>
284         /// <param name="comparer">
285         /// The <see cref="IComparer{T}"/> implementation to use when comparing
286         /// elements.-or-null to use the default comparer <see cref="Comparer{T}.Default"/>.
287         /// </param>
288         /// <returns>
289         /// The zero-based index of <paramref name="item"/> in the sorted <see cref="IReadOnlyList{T}"/>,
290         /// if <paramref name="item"/> is found; otherwise, a negative number that is the bitwise complement
291         /// of the index of the next element that is larger than <paramref name="item"/> or, if there is
292         /// no larger element, the bitwise complement of <see cref="IReadOnlyCollection{T}.Count"/>.
293         /// </returns>
294         /// <exception cref="InvalidOperationException">
295         /// <paramref name="comparer"/> is null, and the default comparer <see cref="Comparer{T}.Default"/>
296         /// cannot find an implementation of the <see cref="IComparable{T}"/> generic interface
297         /// or the <see cref="IComparable"/> interface for type <typeparamref name="T"/>.
298         /// </exception>
BinarySearch(T item, IComparer<T> comparer)299         int BinarySearch(T item, IComparer<T> comparer);
300 
301         /// <summary>
302         /// Searches a range of elements in the sorted <see cref="IReadOnlyList{T}"/>
303         /// for an element using the specified comparer and returns the zero-based index
304         /// of the element.
305         /// </summary>
306         /// <param name="index">The zero-based starting index of the range to search.</param>
307         /// <param name="count"> The length of the range to search.</param>
308         /// <param name="item">The object to locate. The value can be null for reference types.</param>
309         /// <param name="comparer">
310         /// The <see cref="IComparer{T}"/> implementation to use when comparing
311         /// elements, or null to use the default comparer <see cref="Comparer{T}.Default"/>.
312         /// </param>
313         /// <returns>
314         /// The zero-based index of <paramref name="item"/> in the sorted <see cref="IReadOnlyList{T}"/>,
315         /// if <paramref name="item"/> is found; otherwise, a negative number that is the bitwise complement
316         /// of the index of the next element that is larger than <paramref name="item"/> or, if there is
317         /// no larger element, the bitwise complement of <see cref="IReadOnlyCollection{T}.Count"/>.
318         /// </returns>
319         /// <exception cref="ArgumentOutOfRangeException">
320         /// <paramref name="index"/> is less than 0.-or-<paramref name="count"/> is less than 0.
321         /// </exception>
322         /// <exception cref="ArgumentException">
323         /// <paramref name="index"/> and <paramref name="count"/> do not denote a valid range in the <see cref="IReadOnlyList{T}"/>.
324         /// </exception>
325         /// <exception cref="InvalidOperationException">
326         /// <paramref name="comparer"/> is null, and the default comparer <see cref="Comparer{T}.Default"/>
327         /// cannot find an implementation of the <see cref="IComparable{T}"/> generic interface
328         /// or the <see cref="IComparable"/> interface for type <typeparamref name="T"/>.
329         /// </exception>
BinarySearch(int index, int count, T item, IComparer<T> comparer)330         int BinarySearch(int index, int count, T item, IComparer<T> comparer);
331     }
332 }
333