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 }