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 * @see LazyList
58 * @since 3.2
59 */
60 public class GrowthList<E> extends AbstractSerializableListDecorator<E> {
61
62 /** Serialization version */
63 private static final long serialVersionUID = -3620001881672L;
64
65 /**
66 * Factory method to create a growth list.
67 *
68 * @param <E> the type of the elements in the list
69 * @param list the list to decorate, must not be null
70 * @return a new growth list
71 * @throws NullPointerException if list is null
72 * @since 4.0
73 */
74 public static <E> GrowthList<E> growthList(final List<E> list) {
75 return new GrowthList<>(list);
76 }
77
78 /**
79 * Constructor that uses an ArrayList internally.
80 */
81 public GrowthList() {
82 super(new ArrayList<>());
83 }
84
85 /**
86 * Constructor that uses an ArrayList internally.
87 *
88 * @param initialCapacity the initial capacity of the ArrayList
89 * @throws IllegalArgumentException if initial capacity is invalid
90 */
91 public GrowthList(final int initialCapacity) {
92 super(new ArrayList<>(initialCapacity));
93 }
94
95 /**
96 * Constructor that wraps (not copies).
97 *
98 * @param list the list to decorate, must not be null
99 * @throws NullPointerException if list is null
100 */
101 protected GrowthList(final List<E> list) {
102 super(list);
103 }
104
105 /**
106 * Decorate the add method to perform the growth behavior.
107 * <p>
108 * If the requested index is greater than the current size, the list will
109 * grow to the new size. Indices between the old size and the requested
110 * size will be filled with {@code null}.
111 * <p>
112 * If the index is less than the current size, the value will be added to
113 * the underlying list directly.
114 * If the index is less than zero, the underlying list is called, which
115 * will probably throw an IndexOutOfBoundsException.
116 *
117 * @param index the index to add at
118 * @param element the object to add at the specified index
119 * @throws UnsupportedOperationException if the underlying list doesn't implement set
120 * @throws ClassCastException if the underlying list rejects the element
121 * @throws IllegalArgumentException if the underlying list rejects the element
122 */
123 @Override
124 public void add(final int index, final E element) {
125 final int size = decorated().size();
126 if (index > size) {
127 decorated().addAll(Collections.<E>nCopies(index - size, null));
128 }
129 decorated().add(index, element);
130 }
131
132 /**
133 * Decorate the addAll method to perform the growth behavior.
134 * <p>
135 * If the requested index is greater than the current size, the list will
136 * grow to the new size. Indices between the old size and the requested
137 * size will be filled with {@code null}.
138 * <p>
139 * If the index is less than the current size, the values will be added to
140 * the underlying list directly.
141 * If the index is less than zero, the underlying list is called, which
142 * will probably throw an IndexOutOfBoundsException.
143 *
144 * @param index the index to add at
145 * @param coll the collection to add at the specified index
146 * @return true if the list changed
147 * @throws UnsupportedOperationException if the underlying list doesn't implement set
148 * @throws ClassCastException if the underlying list rejects the element
149 * @throws IllegalArgumentException if the underlying list rejects the element
150 */
151 @Override
152 public boolean addAll(final int index, final Collection<? extends E> coll) {
153 final int size = decorated().size();
154 boolean result = false;
155 if (index > size) {
156 decorated().addAll(Collections.<E>nCopies(index - size, null));
157 result = true;
158 }
159 return decorated().addAll(index, coll) || result;
160 }
161
162 /**
163 * Decorate the set method to perform the growth behavior.
164 * <p>
165 * If the requested index is greater than the current size, the list will
166 * grow to the new size. Indices between the old size and the requested
167 * size will be filled with {@code null}.
168 * <p>
169 * If the index is less than the current size, the value will be set onto
170 * the underlying list directly.
171 * If the index is less than zero, the underlying list is called, which
172 * will probably throw an IndexOutOfBoundsException.
173 *
174 * @param index the index to set
175 * @param element the object to set at the specified index
176 * @return the object previously at that index
177 * @throws UnsupportedOperationException if the underlying list doesn't implement set
178 * @throws ClassCastException if the underlying list rejects the element
179 * @throws IllegalArgumentException if the underlying list rejects the element
180 */
181 @Override
182 public E set(final int index, final E element) {
183 final int size = decorated().size();
184 if (index >= size) {
185 decorated().addAll(Collections.<E>nCopies(index - size + 1, null));
186 }
187 return decorated().set(index, element);
188 }
189
190 }