1 package org.djutils.immutablecollections;
2
3 import java.util.ArrayList;
4 import java.util.List;
5
6 /**
7 * A List interface without the methods that can change it. The constructor of the ImmutableList needs to be given an initial
8 * List.
9 * <p>
10 * Copyright (c) 2016-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
11 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
12 * distributed under a three-clause BSD-style license, which can be found at
13 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
14 * </p>
15 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
16 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</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>,
55 * inclusive, and <code>toIndex</code>, exclusive. (If <code>fromIndex</code> and <code>toIndex</code> are equal, the
56 * returned immutable list is 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 /**
94 * Return an empty ImmutableList, backed by a ArrayList.
95 * @param <E> the value type
96 * @return ImmutableList<K, V>; an empty ImmutableList
97 */
98 static <E> ImmutableList<E> of()
99 {
100 return new ImmutableArrayList<>(new ArrayList<E>(), Immutable.WRAP);
101 }
102
103 /**
104 * Return an ImmutableList with 1 entry, backed by a ArrayList.
105 * @param <E> the value type
106 * @param v1 E; value 1
107 * @return ImmutableList<K, V>; an ImmutableList with 1 entry, backed by a ArrayList
108 */
109 static <E> ImmutableList<E> of(final E v1)
110 {
111 ArrayList<E> list = new ArrayList<>();
112 list.add(v1);
113 return new ImmutableArrayList<>(list, Immutable.WRAP);
114 }
115
116 /**
117 * Return an ImmutableList with 2 entries, backed by a ArrayList.
118 * @param <E> the value type
119 * @param v1 E; value 1
120 * @param v2 E; value 2
121 * @return ImmutableList<K, V>; an ImmutableList with 2 entries, backed by a ArrayList
122 */
123 static <E> ImmutableList<E> of(final E v1, final E v2)
124 {
125 ArrayList<E> list = new ArrayList<>();
126 list.add(v1);
127 list.add(v2);
128 return new ImmutableArrayList<>(list, Immutable.WRAP);
129 }
130
131 /**
132 * Return an ImmutableList with 3 entries, backed by a ArrayList.
133 * @param <E> the value type
134 * @param v1 E; value 1
135 * @param v2 E; value 2
136 * @param v3 E; value 3
137 * @return ImmutableList<K, V>; an ImmutableList with 3 entries, backed by a ArrayList
138 */
139 static <E> ImmutableList<E> of(final E v1, final E v2, final E v3)
140 {
141 ArrayList<E> list = new ArrayList<>();
142 list.add(v1);
143 list.add(v2);
144 list.add(v3);
145 return new ImmutableArrayList<>(list, Immutable.WRAP);
146 }
147
148 /**
149 * Return an ImmutableList with 4 entries, backed by a ArrayList.
150 * @param <E> the value type
151 * @param v1 E; value 1
152 * @param v2 E; value 2
153 * @param v3 E; value 3
154 * @param v4 E; value 4
155 * @return ImmutableList<K, V>; an ImmutableList with 4 entries, backed by a ArrayList
156 */
157 static <E> ImmutableList<E> of(final E v1, final E v2, final E v3, final E v4)
158 {
159 ArrayList<E> list = new ArrayList<>();
160 list.add(v1);
161 list.add(v2);
162 list.add(v3);
163 list.add(v4);
164 return new ImmutableArrayList<>(list, Immutable.WRAP);
165 }
166
167 /**
168 * Return an ImmutableList with 5 or more entries, backed by a ArrayList.
169 * @param <E> the value type
170 * @param v1 E; value 1
171 * @param v2 E; value 2
172 * @param v3 E; value 3
173 * @param v4 E; value 4
174 * @param v5 E; value 5
175 * @param vn E...; values 6 and beyond
176 * @return ImmutableList<K, V>; an ImmutableList with 5 or more entries, backed by a ArrayList
177 */
178 @SuppressWarnings("unchecked")
179 static <E> ImmutableList<E> of(final E v1, final E v2, final E v3, final E v4, final E v5, final E... vn)
180 {
181 ArrayList<E> list = new ArrayList<>();
182 list.add(v1);
183 list.add(v2);
184 list.add(v3);
185 list.add(v4);
186 list.add(v5);
187 for (E v : vn)
188 {
189 list.add(v);
190 }
191 return new ImmutableArrayList<>(list, Immutable.WRAP);
192 }
193
194 }