001/* 002 * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved. 003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 004 * 005 * This code is free software; you can redistribute it and/or modify it 006 * under the terms of the GNU General Public License version 2 only, as 007 * published by the Free Software Foundation. Oracle designates this 008 * particular file as subject to the "Classpath" exception as provided 009 * by Oracle in the LICENSE file that accompanied this code. 010 * 011 * This code is distributed in the hope that it will be useful, but WITHOUT 012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 014 * version 2 for more details (a copy is included in the LICENSE file that 015 * accompanied this code). 016 * 017 * You should have received a copy of the GNU General Public License version 018 * 2 along with this work; if not, write to the Free Software Foundation, 019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 020 * 021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 022 * or visit www.oracle.com if you need additional information or have any 023 * questions. 024 */ 025 026package Torello.Java.ReadOnly; 027 028import Torello.Java.Additional.RemoveUnsupportedIterator; 029 030import java.util.function.UnaryOperator; 031 032import java.util.Spliterators; 033import java.util.Spliterator; 034import java.util.Collection; 035import java.util.List; 036import java.util.RandomAccess; 037import java.util.Objects; 038 039import java.util.function.Consumer; 040 041/** 042 * Immutable variant of Java Collections Framework interface 043 * <CODE>java.util.List<E></CODE>. 044 * 045 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlyList DATA-FILE-ID=INTERFACES> 046 * 047 * @param <E> the type of elements in this list 048 */ 049@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE") 050public interface ReadOnlyList<E> extends ReadOnlyCollection<E> 051{ 052 // ******************************************************************************************** 053 // ******************************************************************************************** 054 // Query Operations 055 // ******************************************************************************************** 056 // ******************************************************************************************** 057 058 059 /** 060 * Returns the number of elements in this list. If this list contains more than 061 * {@code Integer.MAX_VALUE} elements, returns {@code Integer.MAX_VALUE}. 062 * 063 * @return the number of elements in this list 064 */ 065 int size(); 066 067 /** 068 * Returns {@code TRUE} if this list contains no elements. 069 * @return {@code TRUE} if this list contains no elements 070 */ 071 boolean isEmpty(); 072 073 /** 074 * Returns {@code TRUE} if this list contains the specified element. More formally, returns 075 * {@code TRUE} if and only if this list contains at least one element {@code e} such that 076 * {@code Objects.equals(o, e)}. 077 * 078 * @param o element whose presence in this list is to be tested 079 * 080 * @return {@code TRUE} if this list contains the specified element 081 * 082 * @throws ClassCastException if the type of the specified element is incompatible with this 083 * list (<a href="Collection.html#optional-restrictions">optional</a>) 084 * 085 * @throws NullPointerException if the specified element is null and this list does not permit 086 * null elements (<a href="Collection.html#optional-restrictions">optional</a>) 087 */ 088 boolean contains(Object o); 089 090 /** 091 * Returns an iterator over the elements in this list in proper sequence. 092 * @return an iterator over the elements in this list in proper sequence 093 */ 094 RemoveUnsupportedIterator<E> iterator(); 095 096 /** 097 * Returns an array containing all of the elements in this list in proper sequence (from first 098 * to last element). 099 * 100 * <BR /><BR />The returned array will be "safe" in that no references to it are maintained by 101 * this list. (In other words, this method must allocate a new array even if this list is 102 * backed by an array). The caller is thus free to modify the returned array. 103 * 104 * <BR /><BR />This method acts as bridge between array-based and collection-based APIs. 105 * 106 * @return an array containing all of the elements in this list in proper sequence 107 */ 108 Object[] toArray(); 109 110 /** 111 * Returns an array containing all of the elements in this list in proper sequence (from first 112 * to last element); the runtime type of the returned array is that of the specified array. If 113 * the list fits in the specified array, it is returned therein. Otherwise, a new array is 114 * allocated with the runtime type of the specified array and the size of this list. 115 * 116 * <BR /><BR />If the list fits in the specified array with room to spare (i.e., the array has 117 * more elements than the list), the element in the array immediately following the end of the 118 * list is set to {@code null}. (This is useful in determining the length of the list 119 * <i>only</i> if the caller knows that the list does not contain any null elements.) 120 * 121 * <BR /><BR />Like the {@link #toArray()} method, this method acts as bridge between 122 * array-based and collection-based APIs. Further, this method allows precise control over the 123 * runtime type of the output array, and may, under certain circumstances, be used to save 124 * allocation costs. 125 * 126 * <BR /><BR />Suppose {@code x} is a list known to contain only strings. The following code 127 * can be used to dump the list into a newly allocated array of {@code String}: 128 * 129 * <BR /><DIV CLASS=SNIP>{@code 130 * String[] y = x.toArray(new String[0]); 131 * }</DIV> 132 * 133 * <BR /><BR />Note that {@code toArray(new Object[0])} is identical in function to 134 * {@code toArray()}. 135 * 136 * @param a the array into which the elements of this list are to be stored, if it is big 137 * enough; otherwise, a new array of the same runtime type is allocated for this purpose. 138 * 139 * @return an array containing the elements of this list 140 * 141 * @throws ArrayStoreException if the runtime type of the specified array is not a supertype of 142 * the runtime type of every element in this list 143 * 144 * @throws NullPointerException if the specified array is null 145 */ 146 <T> T[] toArray(T[] a); 147 148 /** 149 * Returns {@code TRUE} if this list contains all of the elements of the specified collection. 150 * @param c collection to be checked for containment in this list 151 * @return {@code TRUE} if this list contains all of the elements of the specified collection 152 * 153 * @throws ClassCastException if the types of one or more elements in the specified collection 154 * are incompatible with this list 155 * (<a href="Collection.html#optional-restrictions">optional</a>) 156 * 157 * @throws NullPointerException if the specified collection contains one or more null elements 158 * and this list does not permit null elements 159 * (<a href="Collection.html#optional-restrictions">optional</a>), or if the specified 160 * collection is null 161 * 162 * @see #contains(Object) 163 */ 164 boolean containsAll(Collection<?> c); 165 166 167 // ******************************************************************************************** 168 // ******************************************************************************************** 169 // Comparison and Hashing 170 // ******************************************************************************************** 171 // ******************************************************************************************** 172 173 174 /** 175 * Compares the specified object with this list for equality. Returns {@code TRUE} if and only 176 * if the specified object is also a list, both lists have the same size, and all corresponding 177 * pairs of elements in the two lists are <i>equal</i>. (Two elements {@code e1} and 178 * {@code e2} are <i>equal</i> if {@code Objects.equals(e1, e2)}.) In other words, two lists 179 * are defined to be equal if they contain the same elements in the same order. This 180 * definition ensures that the equals method works properly across different implementations of 181 * the {@code ReadOnlyList} interface. 182 * 183 * @param o the object to be compared for equality with this list 184 * @return {@code TRUE} if the specified object is equal to this list 185 */ 186 boolean equals(Object o); 187 188 /** 189 * Returns the hash code value for this list. The hash code of a list is defined to be the 190 * result of the following calculation: 191 * 192 * <BR /><DIV CLASS=SNIP>{@code 193 * int hashCode = 1; 194 * for (E e : list) hashCode = 31*hashCode + (e==null ? 0 : e.hashCode()); 195 * }</DIV> 196 * 197 * <BR /><BR />This ensures that {@code list1.equals(list2)} implies that 198 * {@code list1.hashCode()==list2.hashCode()} for any two lists, {@code list1} and 199 * {@code list2}, as required by the general contract of {@code Object.hashCode}. 200 * 201 * @return the hash code value for this list 202 * 203 * @see Object#equals(Object) 204 * @see #equals(Object) 205 */ 206 int hashCode(); 207 208 209 // ******************************************************************************************** 210 // ******************************************************************************************** 211 // Positional Access Operations 212 // ******************************************************************************************** 213 // ******************************************************************************************** 214 215 216 /** 217 * Returns the element at the specified position in this list. 218 * @param index index of the element to return 219 * @return the element at the specified position in this list 220 * 221 * @throws IndexOutOfBoundsException if the index is out of range 222 * ({@code index < 0 || index >= size()}) 223 */ 224 E get(int index); 225 226 227 // ******************************************************************************************** 228 // ******************************************************************************************** 229 // Search Operations 230 // ******************************************************************************************** 231 // ******************************************************************************************** 232 233 234 /** 235 * Returns the index of the first occurrence of the specified element in this list, or -1 if 236 * this list does not contain the element. More formally, returns the lowest index {@code i} 237 * such that {@code Objects.equals(o, get(i))}, or -1 if there is no such index. 238 * 239 * @param o element to search for 240 * 241 * @return the index of the first occurrence of the specified element in this list, or -1 if 242 * this list does not contain the element 243 * 244 * @throws ClassCastException if the type of the specified element is incompatible with this 245 * list (<a href="Collection.html#optional-restrictions">optional</a>) 246 * 247 * @throws NullPointerException if the specified element is null and this list does not permit 248 * null elements (<a href="Collection.html#optional-restrictions">optional</a>) 249 */ 250 int indexOf(Object o); 251 252 /** 253 * Returns the index of the last occurrence of the specified element in this list, or -1 if 254 * this list does not contain the element. More formally, returns the highest index {@code i} 255 * such that {@code Objects.equals(o, get(i))}, or -1 if there is no such index. 256 * 257 * @param o element to search for 258 * 259 * @return the index of the last occurrence of the specified element in this list, or -1 if 260 * this list does not contain the element 261 * 262 * @throws ClassCastException if the type of the specified element is incompatible with this 263 * list (<a href="Collection.html#optional-restrictions">optional</a>) 264 * 265 * @throws NullPointerException if the specified element is null and this list does not permit 266 * null elements (<a href="Collection.html#optional-restrictions">optional</a>) 267 */ 268 int lastIndexOf(Object o); 269 270 271 // ******************************************************************************************** 272 // ******************************************************************************************** 273 // Change The Type, Clone the Internal Data-Structure 274 // ******************************************************************************************** 275 // ******************************************************************************************** 276 277 278 /** 279 * Clones the internal {@code java.util.List} representation, and returns it. This is the 280 * Top-Level Interface-Variant of this method. It returns the Interface-Implementation 281 * {@code java.util.List}. 282 * 283 * <BR /><BR /><B CLASS=JDDescLabel>Alternate Variant:</B> 284 * 285 * <BR />The two classes which implement the interface {@code ReadOnlyList} 286 * (which are {@link ReadOnlyVector} and {@link ReadOnlyArrayList}), for convenience, also 287 * implement an identical "Wrap To" Method which returns the exact type of the internal 288 * {@code List} representation (which are {@code java.util.ArrayList} and 289 * {@code java.util.Vector}) - rather than the Top-Leval Interface-Type {@code java.util.List}. 290 * 291 * @return <UL CLASS=JDUL> 292 * 293 * <LI> For the sub-class {@link ReadOnlyArrayList}, this will return a cloned instance of the 294 * internal {@code java.util.ArrayList}. 295 * <BR /><BR /> 296 * </LI> 297 * 298 * <LI> For the sub-class {@link ReadOnlyVector}, this will return a cloned instance of the 299 * internal {@code java.util.Vector}. 300 * </LI> 301 * 302 * </UL> 303 */ 304 List<E> cloneToList(); 305 306 /** 307 * Invokes {@code java.util.Collections.unmodifiableList} on the internal {@code List}. 308 * 309 * <EMBED CLASS='external-html' DATA-JDK=List DATA-RET_TYPE=List 310 * DATA-FILE-ID=WRAP_TO_IMMUTABLE> 311 * 312 * @return A {@code List} which adheres to the JDK interface {@code java.util.List}, but throws 313 * an {@code UnsupportedOperationException} if a user attempts to invoke a Mutator-Method on 314 * the returned instance. 315 */ 316 List<E> wrapToImmutableList(); 317 318 319 // ******************************************************************************************** 320 // ******************************************************************************************** 321 // List Iterators 322 // ******************************************************************************************** 323 // ******************************************************************************************** 324 325 326 /** 327 * Returns a list iterator over the elements in this list (in proper sequence). 328 * @return a list iterator over the elements in this list (in proper sequence) 329 */ 330 ReadOnlyListIterator<E> listIterator(); 331 332 /** 333 * Returns a list iterator over the elements in this list (in proper sequence), starting at the 334 * specified position in the list. The specified index indicates the first element that would 335 * be returned by an initial call to {@link ReadOnlyListIterator#next}. An initial call to 336 * {@link ReadOnlyListIterator#previous} would return the element with the specified index 337 * minus one. 338 * 339 * @param index index of the first element to be returned from the list iterator (by a call to 340 * {@link ReadOnlyListIterator#next next}) 341 * 342 * @return a list iterator over the elements in this list (in proper sequence), starting at the 343 * specified position in the list 344 * 345 * @throws IndexOutOfBoundsException if the index is out of range 346 * ({@code index < 0 || index > size()}) 347 */ 348 ReadOnlyListIterator<E> listIterator(int index); 349 350 351 // ******************************************************************************************** 352 // ******************************************************************************************** 353 // View 354 // ******************************************************************************************** 355 // ******************************************************************************************** 356 357 358 /** 359 * Returns a view of the portion of this list between the specified {@code fromIndex}, 360 * inclusive, and {@code toIndex}, exclusive. (If {@code fromIndex} and {@code toIndex} are 361 * equal, the returned list is empty.) The returned list is backed by this list, so 362 * non-structural changes in the returned list are reflected in this list, and vice-versa. The 363 * returned list supports all of the optional list operations supported by this list. 364 * 365 * <BR /><BR />This method eliminates the need for explicit range operations (of the sort that 366 * commonly exist for arrays). Any operation that expects a list can be used as a range 367 * operation by passing a subList view instead of a whole list. For example, the following 368 * idiom removes a range of elements from a list: 369 * 370 * <BR /><DIV CLASS=SNIP>{@code 371 * list.subList(from, to).clear(); 372 * }</DIV> 373 * 374 * <BR /><BR />Similar idioms may be constructed for {@code indexOf} and {@code lastIndexOf}, 375 * and all of the algorithms in the {@code Collections} class can be applied to a subList. 376 * 377 * <BR /><BR />The semantics of the list returned by this method become undefined if the 378 * backing list (i.e., this list) is <i>structurally modified</i> in any way other than via the 379 * returned list. (Structural modifications are those that change the size of this list, or 380 * otherwise perturb it in such a fashion that iterations in progress may yield incorrect 381 * results.) 382 * 383 * @param fromIndex low endpoint (inclusive) of the subList 384 * 385 * @param toIndex high endpoint (exclusive) of the subList 386 * 387 * @return a view of the specified range within this list 388 * 389 * @throws IndexOutOfBoundsException for an illegal endpoint index value 390 * ({@code fromIndex < 0 || toIndex > size || fromIndex > toIndex}) 391 */ 392 ReadOnlyList<E> subList(int fromIndex, int toIndex); 393 394 /* 395 * Creates a {@link Spliterator} over the elements in this list. 396 * 397 * <BR /><BR />The {@code Spliterator} reports {@code Spliterator.SIZED} and 398 * {@code Spliterator.ORDERED}. Implementations should document the 399 * reporting of additional characteristic values. 400 * 401 * <BR /><BR />The default implementation creates a 402 * <em><a href="Spliterator.html#binding">late-binding</a></em> 403 * spliterator as follows: 404 * 405 * <UL CLASS=JDUL> 406 * 407 * <LI> If the list is an instance of {@code RandomAccess} then the default implementation 408 * creates a spliterator that traverses elements by invoking the method 409 * {@link ReadOnlyList#get}. 410 * </LI> 411 * 412 * <LI> Otherwise, the default implementation creates a spliterator from the list's 413 * {@code Iterator}. 414 * </LI> 415 * 416 * </UL> 417 * 418 * <BR /><BR />The created {@code Spliterator} additionally reports 419 * {@code Spliterator.SUBSIZED}. 420 * 421 * @return a {@code Spliterator} over the elements in this list 422 */ 423 @Override 424 default Spliterator<E> spliterator() 425 { 426 return (this instanceof RandomAccess) 427 ? new RandomAccessSpliterator<>(this) 428 : Spliterators.spliterator(this.iterator(), this.size(), Spliterator.ORDERED); 429 } 430 431 432 // ******************************************************************************************** 433 // ******************************************************************************************** 434 // Static Builder Methods 435 // ******************************************************************************************** 436 // ******************************************************************************************** 437 438 439 /** 440 * Returns an unmodifiable list containing zero elements. 441 * @param <E> the {@code List}'s element type 442 * @return an empty {@code List} 443 */ 444 static <E> ReadOnlyList<E> of() 445 { return new JavaHTMLReadOnlyList<>(java.util.List.of()); } 446 447 /** 448 * Returns an unmodifiable list containing one element. 449 * @param <E> the {@code List}'s element type 450 * @param e1 the single element 451 * @return a {@code List} containing the specified element 452 * @throws NullPointerException if the element is {@code null} 453 */ 454 static <E> ReadOnlyList<E> of(E e1) 455 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1)); } 456 457 /** 458 * Returns an unmodifiable list containing two elements. 459 * @param <E> the {@code List}'s element type 460 * @param e1 the first element 461 * @param e2 the second element 462 * @return a {@code List} containing the specified elements 463 * @throws NullPointerException if an element is {@code null} 464 */ 465 static <E> ReadOnlyList<E> of(E e1, E e2) 466 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2)); } 467 468 /** 469 * Returns an unmodifiable list containing three elements. 470 * @param <E> the {@code List}'s element type 471 * 472 * @param e1 the first element 473 * @param e2 the second element 474 * @param e3 the third element 475 * 476 * @return a {@code List} containing the specified elements 477 * @throws NullPointerException if an element is {@code null} 478 */ 479 static <E> ReadOnlyList<E> of(E e1, E e2, E e3) 480 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3)); } 481 482 /** 483 * Returns an unmodifiable list containing four elements. 484 * @param <E> the {@code List}'s element type 485 * 486 * @param e1 the first element 487 * @param e2 the second element 488 * @param e3 the third element 489 * @param e4 the fourth element 490 * 491 * @return a {@code List} containing the specified elements 492 * @throws NullPointerException if an element is {@code null} 493 */ 494 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4) 495 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4)); } 496 497 /** 498 * Returns an unmodifiable list containing five elements. 499 * @param <E> the {@code List}'s element type 500 * 501 * @param e1 the first element 502 * @param e2 the second element 503 * @param e3 the third element 504 * @param e4 the fourth element 505 * @param e5 the fifth element 506 * 507 * @return a {@code List} containing the specified elements 508 * @throws NullPointerException if an element is {@code null} 509 */ 510 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5) 511 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5)); } 512 513 /** 514 * Returns an unmodifiable list containing six elements. 515 * @param <E> the {@code List}'s element type 516 * 517 * @param e1 the first element 518 * @param e2 the second element 519 * @param e3 the third element 520 * @param e4 the fourth element 521 * @param e5 the fifth element 522 * @param e6 the sixth element 523 * 524 * @return a {@code List} containing the specified elements 525 * @throws NullPointerException if an element is {@code null} 526 */ 527 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6) 528 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5, e6)); } 529 530 /** 531 * Returns an unmodifiable list containing seven elements. 532 * @param <E> the {@code List}'s element type 533 * 534 * @param e1 the first element 535 * @param e2 the second element 536 * @param e3 the third element 537 * @param e4 the fourth element 538 * @param e5 the fifth element 539 * @param e6 the sixth element 540 * @param e7 the seventh element 541 * 542 * @return a {@code List} containing the specified elements 543 * @throws NullPointerException if an element is {@code null} 544 */ 545 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) 546 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5, e6, e7)); } 547 548 /** 549 * Returns an unmodifiable list containing eight elements. 550 * @param <E> the {@code List}'s element type 551 * 552 * @param e1 the first element 553 * @param e2 the second element 554 * @param e3 the third element 555 * @param e4 the fourth element 556 * @param e5 the fifth element 557 * @param e6 the sixth element 558 * @param e7 the seventh element 559 * @param e8 the eighth element 560 * 561 * @return a {@code List} containing the specified elements 562 * @throws NullPointerException if an element is {@code null} 563 */ 564 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) 565 { return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8)); } 566 567 /** 568 * Returns an unmodifiable list containing nine elements. 569 * @param <E> the {@code List}'s element type 570 * 571 * @param e1 the first element 572 * @param e2 the second element 573 * @param e3 the third element 574 * @param e4 the fourth element 575 * @param e5 the fifth element 576 * @param e6 the sixth element 577 * @param e7 the seventh element 578 * @param e8 the eighth element 579 * @param e9 the ninth element 580 * 581 * @return a {@code List} containing the specified elements 582 * @throws NullPointerException if an element is {@code null} 583 */ 584 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) 585 { 586 return new JavaHTMLReadOnlyList<> 587 (java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8, e9)); 588 } 589 590 /** 591 * Returns an unmodifiable list containing ten elements. 592 * @param <E> the {@code List}'s element type 593 * 594 * @param e1 the first element 595 * @param e2 the second element 596 * @param e3 the third element 597 * @param e4 the fourth element 598 * @param e5 the fifth element 599 * @param e6 the sixth element 600 * @param e7 the seventh element 601 * @param e8 the eighth element 602 * @param e9 the ninth element 603 * @param e10 the tenth element 604 * 605 * @return a {@code List} containing the specified elements 606 * @throws NullPointerException if an element is {@code null} 607 */ 608 static <E> ReadOnlyList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) 609 { 610 return new JavaHTMLReadOnlyList<> 611 (java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10)); 612 } 613 614 /** 615 * Returns an unmodifiable list containing an arbitrary number of elements. 616 * 617 * @apiNote 618 * This method also accepts a single array as an argument. The element type of the resulting 619 * list will be the component type of the array, and the size of the list will be equal to the 620 * length of the array. To create a list with a single element that is an array, do the 621 * following: 622 * 623 * <BR /><DIV CLASS=SNIP>{@code 624 * String[] array = ... ; 625 * ReadOnlyList<String[]> list = ReadOnlyList.<String[]>of(array); 626 * }</DIV> 627 * 628 * <BR /><BR />This will cause the {@link ReadOnlyList#of(Object) ReadOnlyList.of(E)} method to 629 * be invoked instead. 630 * 631 * @param <E> the {@code List}'s element type 632 * @param elements the elements to be contained in the list 633 * @return a {@code List} containing the specified elements 634 * @throws NullPointerException if an element is {@code null} or if the array is {@code null} 635 */ 636 @SafeVarargs 637 @SuppressWarnings("varargs") 638 static <E> ReadOnlyList<E> of(E... elements) 639 { return new JavaHTMLReadOnlyList<>(java.util.List.of(elements)); } 640 641 /** 642 * Returns a {@code ReadOnlyList} containing the elements of the given 643 * {@code ReadOnlyCollection}, in its iteration order. The given {@code Collection} must not be 644 * null, and it must not contain any null elements. If the given {@code Collection} is 645 * subsequently modified, the returned {@code ReadOnlyList} will not reflect such modifications 646 * 647 * @param <E> the {@code ReadOnlyList}'s element type 648 * @param coll a {@code ReadOnlyCollection} from which elements are drawn, must be non-null 649 * @return a {@code ReadOnlyList} containing the elements of the given {@code Collection} 650 * @throws NullPointerException if coll is null, or if it contains any nulls 651 */ 652 @SuppressWarnings("unchecked") 653 static <E> ReadOnlyList<E> copyOf(ReadOnlyCollection<? extends E> coll) 654 { 655 return (ReadOnlyList.class.isAssignableFrom(coll.getClass())) 656 ? (ReadOnlyList<E>) coll 657 : new ReadOnlyArrayList<E>((ReadOnlyCollection<E>) coll, coll.size()); 658 } 659 660 661 // ******************************************************************************************** 662 // ******************************************************************************************** 663 // COPIED FEBRUARY 2025 - FROM JDK 664 // ******************************************************************************************** 665 // ******************************************************************************************** 666 667 668} 669 670// Auxillary class !! 671class RandomAccessSpliterator<E> implements Spliterator<E> 672{ 673 private final ReadOnlyList<E> list; 674 private int index; // current index, modified on advance/split 675 private int fence; // -1 until used; then one past last index 676 677 // The following fields are valid if covering an AbstractList 678 // private final AbstractReadOnlyList<E> alist; 679 680 RandomAccessSpliterator(ReadOnlyList<E> list) 681 { 682 assert list instanceof RandomAccess; 683 684 this.list = list; 685 this.index = 0; 686 this.fence = -1; 687 688 /* 689 this.alist = (list instanceof AbstractReadOnlyList) 690 ? (AbstractReadOnlyList<E>) list 691 : null; 692 */ 693 } 694 695 /** Create new spliterator covering the given range */ 696 private RandomAccessSpliterator 697 (RandomAccessSpliterator<E> parent, int origin, int fence) 698 { 699 this.list = parent.list; 700 this.index = origin; 701 this.fence = fence; 702 // this.alist = parent.alist; 703 } 704 705 // initialize fence to size on first use 706 private int getFence() 707 { 708 int hi; 709 ReadOnlyList<E> lst = list; 710 711 if ((hi = fence) < 0) 712 { 713 // if (alist != null) expectedModCount = alist.modCount; 714 715 hi = fence = lst.size(); 716 } 717 718 return hi; 719 } 720 721 public Spliterator<E> trySplit() 722 { 723 int hi = getFence(), lo = index, mid = (lo + hi) >>> 1; 724 725 return (lo >= mid) 726 727 ? null 728 729 // divide range in half unless too small 730 : new RandomAccessSpliterator<>(this, lo, index = mid); 731 } 732 733 public boolean tryAdvance(Consumer<? super E> action) 734 { 735 if (action == null) throw new NullPointerException(); 736 737 int hi = getFence(), i = index; 738 739 if (i < hi) 740 { 741 index = i + 1; 742 action.accept(get(list, i)); 743 return true; 744 } 745 746 return false; 747 } 748 749 public void forEachRemaining(Consumer<? super E> action) 750 { 751 Objects.requireNonNull(action); 752 753 ReadOnlyList<E> lst = list; 754 int hi = getFence(); 755 int i = index; 756 757 index = hi; 758 for (; i < hi; i++) action.accept(get(lst, i)); 759 } 760 761 public long estimateSize() 762 { return (long) (getFence() - index); } 763 764 public int characteristics() 765 { return Spliterator.ORDERED | Spliterator.SIZED | Spliterator.SUBSIZED; } 766 767 private static <E> E get(ReadOnlyList<E> list, int i) 768 { 769 try 770 { return list.get(i); } 771 772 // *** Java-HTML: I'm pretty sure this is unreachable, you should check it 773 catch (IndexOutOfBoundsException ex) 774 { throw new Torello.Java.UnreachableError(); } 775 } 776}