1 package org.djutils.immutablecollections;
2
3 import java.util.List;
4
5 /**
6 * A List interface without the methods that can change it. The constructor of the ImmutableList needs to be given an initial
7 * List.
8 * <p>
9 * Copyright (c) 2016-2019 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
10 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
11 * distributed under a three-clause BSD-style license, which can be found at
12 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
13 * </p>
14 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
15 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
16 * @author <a href="https://www.transport.citg.tudelft.nl">Wouter Schakel</a>
17 * @param <E> the type of content of this List
18 */
19 public interface ImmutableList<E> extends ImmutableCollection<E>
20 {
21 /**
22 * Returns the element at the specified position in this immutable list.
23 * @param index int; index of the element to return
24 * @return the element at the specified position in this immutable list
25 * @throws IndexOutOfBoundsException if the index is out of range (<code>index < 0 || index >= size()</code>)
26 */
27 E get(int index);
28
29 /**
30 * Returns the index of the first occurrence of the specified element in this immutable list, or -1 if this immutable list
31 * does not contain the element. More formally, returns the lowest index <code>i</code> such that
32 * <code>(o==null ? get(i)==null : o.equals(get(i)))</code>, or -1 if there is no such index.
33 * @param o Object; element to search for
34 * @return the index of the first occurrence of the specified element in this immutable list, or -1 if this immutable list
35 * does not contain the element
36 * @throws ClassCastException if the type of the specified element is incompatible with this immutable list
37 * @throws NullPointerException if the specified element is null and this immutable list does not permit null elements
38 */
39 int indexOf(Object o);
40
41 /**
42 * Returns the index of the last occurrence of the specified element in this immutable list, or -1 if this immutable list
43 * does not contain the element. More formally, returns the highest index <code>i</code> such that
44 * <code>(o==null ? get(i)==null : o.equals(get(i)))</code>, or -1 if there is no such index.
45 * @param o Object; element to search for
46 * @return the index of the last occurrence of the specified element in this immutable list, or -1 if this immutable list
47 * does not contain the element
48 * @throws ClassCastException if the type of the specified element is incompatible with this immutable list
49 * @throws NullPointerException if the specified element is null and this immutable list does not permit null elements
50 */
51 int lastIndexOf(Object o);
52
53 /**
54 * Returns a safe, immutable copy of the portion of this immutable list between the specified <code>fromIndex</code>, inclusive,
55 * and <code>toIndex</code>, exclusive. (If <code>fromIndex</code> and <code>toIndex</code> are equal, the returned immutable list is
56 * empty).
57 * @param fromIndex int; low endpoint (inclusive) of the subList
58 * @param toIndex int; high endpoint (exclusive) of the subList
59 * @return a view of the specified range within this immutable list
60 * @throws IndexOutOfBoundsException for an illegal endpoint index value (<code>fromIndex < 0 || toIndex > size ||
61 * fromIndex > toIndex</code>)
62 */
63 ImmutableList<E> subList(int fromIndex, int toIndex);
64
65 /**
66 * Returns a modifiable copy of this immutable list.
67 * @return a modifiable copy of this immutable list.
68 */
69 List<E> toList();
70
71 /**
72 * Force to redefine equals for the implementations of immutable collection classes.
73 * @param obj Object; the object to compare this collection with
74 * @return whether the objects are equal
75 */
76 @Override
77 boolean equals(Object obj);
78
79 /**
80 * Force to redefine hashCode for the implementations of immutable collection classes.
81 * @return the calculated hashCode
82 */
83 @Override
84 int hashCode();
85
86 /**
87 * Force to redefine toString.
88 * @return String; a description of this immutable list
89 */
90 @Override
91 String toString();
92
93 }