1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4.list;
18
19 import java.util.ArrayList;
20 import java.util.Collection;
21 import java.util.Collections;
22 import java.util.List;
23
24 /**
25 * Decorates another {@code List} to make it seamlessly grow when
26 * indices larger than the list size are used on add and set,
27 * avoiding most IndexOutOfBoundsExceptions.
28 * <p>
29 * This class avoids errors by growing when a set or add method would
30 * normally throw an IndexOutOfBoundsException.
31 * Note that IndexOutOfBoundsException IS returned for invalid negative indices.
32 * </p>
33 * <p>
34 * Trying to set or add to an index larger than the size will cause the list
35 * to grow (using {@code null} elements). Clearly, care must be taken
36 * not to use excessively large indices, as the internal list will grow to
37 * match.
38 * </p>
39 * <p>
40 * Trying to use any method other than add or set with an invalid index will
41 * call the underlying list and probably result in an IndexOutOfBoundsException.
42 * </p>
43 * <p>
44 * Take care when using this list with {@code null} values, as
45 * {@code null} is the value added when growing the list.
46 * </p>
47 * <p>
48 * All sub-lists will access the underlying list directly, and will throw
49 * IndexOutOfBoundsExceptions.
50 * </p>
51 * <p>
52 * This class differs from {@link LazyList} because here growth occurs on
53 * set and add, where {@code LazyList} grows on get. However, they
54 * can be used together by decorating twice.
55 * </p>
56 *
57 * @param <E> the type of the elements in the list.
58 * @see LazyList
59 * @since 3.2
60 */
61 public class GrowthList<E> extends AbstractSerializableListDecorator<E> {
62
63 /** Serialization version */
64 private static final long serialVersionUID = -3620001881672L;
65
66 /**
67 * Factory method to create a growth list.
68 *
69 * @param <E> the type of the elements in the list
70 * @param list the list to decorate, must not be null
71 * @return a new growth list
72 * @throws NullPointerException if list is null
73 * @since 4.0
74 */
75 public static <E> GrowthList<E> growthList(final List<E> list) {
76 return new GrowthList<>(list);
77 }
78
79 /**
80 * Constructor that uses an ArrayList internally.
81 */
82 public GrowthList() {
83 super(new ArrayList<>());
84 }
85
86 /**
87 * Constructor that uses an ArrayList internally.
88 *
89 * @param initialCapacity the initial capacity of the ArrayList
90 * @throws IllegalArgumentException if initial capacity is invalid
91 */
92 public GrowthList(final int initialCapacity) {
93 super(new ArrayList<>(initialCapacity));
94 }
95
96 /**
97 * Constructor that wraps (not copies).
98 *
99 * @param list the list to decorate, must not be null
100 * @throws NullPointerException if list is null
101 */
102 protected GrowthList(final List<E> list) {
103 super(list);
104 }
105
106 /**
107 * Decorate the add method to perform the growth behavior.
108 * <p>
109 * If the requested index is greater than the current size, the list will
110 * grow to the new size. Indices between the old size and the requested
111 * size will be filled with {@code null}.
112 * <p>
113 * If the index is less than the current size, the value will be added to
114 * the underlying list directly.
115 * If the index is less than zero, the underlying list is called, which
116 * will probably throw an IndexOutOfBoundsException.
117 *
118 * @param index the index to add at
119 * @param element the object to add at the specified index
120 * @throws UnsupportedOperationException if the underlying list doesn't implement set
121 * @throws ClassCastException if the underlying list rejects the element
122 * @throws IllegalArgumentException if the underlying list rejects the element
123 */
124 @Override
125 public void add(final int index, final E element) {
126 final int size = decorated().size();
127 if (index > size) {
128 decorated().addAll(Collections.<E>nCopies(index - size, null));
129 }
130 decorated().add(index, element);
131 }
132
133 /**
134 * Decorate the addAll method to perform the growth behavior.
135 * <p>
136 * If the requested index is greater than the current size, the list will
137 * grow to the new size. Indices between the old size and the requested
138 * size will be filled with {@code null}.
139 * <p>
140 * If the index is less than the current size, the values will be added to
141 * the underlying list directly.
142 * If the index is less than zero, the underlying list is called, which
143 * will probably throw an IndexOutOfBoundsException.
144 *
145 * @param index the index to add at
146 * @param coll the collection to add at the specified index
147 * @return true if the list changed
148 * @throws UnsupportedOperationException if the underlying list doesn't implement set
149 * @throws ClassCastException if the underlying list rejects the element
150 * @throws IllegalArgumentException if the underlying list rejects the element
151 */
152 @Override
153 public boolean addAll(final int index, final Collection<? extends E> coll) {
154 final int size = decorated().size();
155 boolean result = false;
156 if (index > size) {
157 decorated().addAll(Collections.<E>nCopies(index - size, null));
158 result = true;
159 }
160 return decorated().addAll(index, coll) || result;
161 }
162
163 /**
164 * Decorate the set method to perform the growth behavior.
165 * <p>
166 * If the requested index is greater than the current size, the list will
167 * grow to the new size. Indices between the old size and the requested
168 * size will be filled with {@code null}.
169 * <p>
170 * If the index is less than the current size, the value will be set onto
171 * the underlying list directly.
172 * If the index is less than zero, the underlying list is called, which
173 * will probably throw an IndexOutOfBoundsException.
174 *
175 * @param index the index to set
176 * @param element the object to set at the specified index
177 * @return the object previously at that index
178 * @throws UnsupportedOperationException if the underlying list doesn't implement set
179 * @throws ClassCastException if the underlying list rejects the element
180 * @throws IllegalArgumentException if the underlying list rejects the element
181 */
182 @Override
183 public E set(final int index, final E element) {
184 final int size = decorated().size();
185 if (index >= size) {
186 decorated().addAll(Collections.<E>nCopies(index - size + 1, null));
187 }
188 return decorated().set(index, element);
189 }
190
191 }