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