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