1 package org.opentrafficsim.base.immutablecollections;
2
3 import java.util.Enumeration;
4 import java.util.Iterator;
5 import java.util.List;
6 import java.util.NoSuchElementException;
7 import java.util.Vector;
8
9 import nl.tudelft.simulation.language.Throw;
10
11 /**
12 * An immutable wrapper for a Vector.
13 * <p>
14 * Copyright (c) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
15 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
16 * </p>
17 * $LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $,
18 * initial version May 7, 2016 <br>
19 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
20 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
21 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
22 * @param <E> the type of content of this List
23 */
24 public class ImmutableVector<E> extends ImmutableAbstractList<E>
25 {
26 /** */
27 private static final long serialVersionUID = 20160507L;
28
29 /**
30 * @param list the list to use as the immutable list.
31 */
32 public ImmutableVector(final List<E> list)
33 {
34 this(list, Immutable.COPY);
35 }
36
37 /**
38 * @param list the list to use as the immutable vector.
39 * @param copyOrWrap COPY stores a safe, internal copy of the collection; WRAP stores a pointer to the original collection
40 */
41 public ImmutableVector(final List<E> list, final Immutable copyOrWrap)
42 {
43 super(copyOrWrap == Immutable.COPY ? new Vector<E>(list) : list, copyOrWrap == Immutable.COPY);
44 Throw.whenNull(copyOrWrap, "the copyOrWrap argument should be Immutable.COPY or Immutable.WRAP");
45 }
46
47 /**
48 * @param list the list to use as the immutable list.
49 */
50 public ImmutableVector(final ImmutableList<E> list)
51 {
52 this(list, Immutable.COPY);
53 }
54
55 /**
56 * @param list the list to use as the immutable list.
57 * @param copyOrWrap COPY stores a safe, internal copy of the collection; WRAP stores a pointer to the original collection
58 */
59 public ImmutableVector(final ImmutableList<E> list, final Immutable copyOrWrap)
60 {
61 this(((ImmutableAbstractList<E>) list).getList(), copyOrWrap);
62 }
63
64 /** {@inheritDoc} */
65 @Override
66 protected final Vector<E> getList()
67 {
68 return (Vector<E>) super.getList();
69 }
70
71 /** {@inheritDoc} */
72 @Override
73 public final List<E> toList()
74 {
75 return new Vector<E>(getList());
76 }
77
78 /** {@inheritDoc} */
79 @Override
80 public final ImmutableList<E> subList(final int fromIndex, final int toIndex)
81 {
82 return new ImmutableVector<E>(getList().subList(fromIndex, toIndex));
83 }
84
85 /**
86 * Copies the components of this immutable vector into the specified array. The item at index {@code k} in this immutable
87 * vector is copied into component {@code k} of {@code anArray}.
88 * @param anArray the array into which the components get copied
89 * @throws NullPointerException if the given array is null
90 * @throws IndexOutOfBoundsException if the specified array is not large enough to hold all the components of this immutable
91 * vector
92 * @throws ArrayStoreException if a component of this immutable vector is not of a runtime type that can be stored in the
93 * specified array
94 * @see #toArray(Object[])
95 */
96 public final void copyInto(final Object[] anArray)
97 {
98 getList().copyInto(anArray);
99 }
100
101 /**
102 * Returns the current capacity of this immutable vector.
103 * @return the current capacity of this immutable vector.
104 */
105 public final int capacity()
106 {
107 return getList().capacity();
108 }
109
110 /**
111 * Returns an enumeration of the components of this vector. The returned {@code Enumeration} object will generate all items
112 * in this vector. The first item generated is the item at index {@code 0}, then the item at index {@code 1}, and so on.
113 * @return an enumeration of the components of this vector
114 * @see Iterator
115 */
116 public final Enumeration<E> elements()
117 {
118 return getList().elements();
119 }
120
121 /**
122 * Returns the index of the first occurrence of the specified element in this immutable vector, searching forwards from
123 * {@code index}, or returns -1 if the element is not found. More formally, returns the lowest index {@code i} such that
124 * <tt>(i >= index && (o==null ? get(i)==null : o.equals(get(i))))</tt>,
125 * or -1 if there is no such index.
126 * @param o element to search for
127 * @param index index to start searching from
128 * @return the index of the first occurrence of the element in this immutable vector at position {@code index} or later in
129 * the vector; {@code -1} if the element is not found.
130 * @throws IndexOutOfBoundsException if the specified index is negative
131 * @see Object#equals(Object)
132 */
133 public final int indexOf(final Object o, final int index)
134 {
135 return getList().indexOf(o, index);
136 }
137
138 /**
139 * Returns the index of the last occurrence of the specified element in this immutable vector, searching backwards from
140 * {@code index}, or returns -1 if the element is not found. More formally, returns the highest index {@code i} such that
141 * <tt>(i <= index && (o==null ? get(i)==null : o.equals(get(i))))</tt>,
142 * or -1 if there is no such index.
143 * @param o element to search for
144 * @param index index to start searching backwards from
145 * @return the index of the last occurrence of the element at position less than or equal to {@code index} in this immutable
146 * vector; -1 if the element is not found.
147 * @throws IndexOutOfBoundsException if the specified index is greater than or equal to the current size of this immutable
148 * vector
149 */
150 public final int lastIndexOf(final Object o, final int index)
151 {
152 return getList().lastIndexOf(o, index);
153 }
154
155 /**
156 * Returns the component at the specified index.
157 * <p>
158 * This method is identical in functionality to the {@link #get(int)} method (which is part of the {@link List} interface).
159 * @param index an index into this immutable vector
160 * @return the component at the specified index
161 * @throws ArrayIndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= size()})
162 */
163 public final E elementAt(final int index)
164 {
165 return getList().elementAt(index);
166 }
167
168 /**
169 * Returns the first component (the item at index {@code 0}) of this immutable vector.
170 * @return the first component of this immutable vector
171 * @throws NoSuchElementException if this immutable vector has no components
172 */
173 public final E firstElement()
174 {
175 return getList().firstElement();
176 }
177
178 /**
179 * Returns the last component of the immutable vector.
180 * @return the last component of the immutable vector, i.e., the component at index <code>size() - 1</code>.
181 * @throws NoSuchElementException if this immutable vector is empty
182 */
183 public final E lastElement()
184 {
185 return getList().lastElement();
186 }
187
188 /** {@inheritDoc} */
189 @Override
190 public final String toString()
191 {
192 List<E> list = getList();
193 if (null == list)
194 {
195 return "ImmutableVector []";
196 }
197 return "ImmutableVector [" + list.toString() + "]";
198 }
199
200 }