001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.collections4.list; 018 019import java.util.ArrayList; 020import java.util.Collection; 021import java.util.Collections; 022import java.util.List; 023 024/** 025 * Decorates another {@code List} to make it seamlessly grow when 026 * indices larger than the list size are used on add and set, 027 * avoiding most IndexOutOfBoundsExceptions. 028 * <p> 029 * This class avoids errors by growing when a set or add method would 030 * normally throw an IndexOutOfBoundsException. 031 * Note that IndexOutOfBoundsException IS returned for invalid negative indices. 032 * </p> 033 * <p> 034 * Trying to set or add to an index larger than the size will cause the list 035 * to grow (using {@code null} elements). Clearly, care must be taken 036 * not to use excessively large indices, as the internal list will grow to 037 * match. 038 * </p> 039 * <p> 040 * Trying to use any method other than add or set with an invalid index will 041 * call the underlying list and probably result in an IndexOutOfBoundsException. 042 * </p> 043 * <p> 044 * Take care when using this list with {@code null} values, as 045 * {@code null} is the value added when growing the list. 046 * </p> 047 * <p> 048 * All sub-lists will access the underlying list directly, and will throw 049 * IndexOutOfBoundsExceptions. 050 * </p> 051 * <p> 052 * This class differs from {@link LazyList} because here growth occurs on 053 * set and add, where {@code LazyList} grows on get. However, they 054 * can be used together by decorating twice. 055 * </p> 056 * 057 * @see LazyList 058 * @since 3.2 059 */ 060public class GrowthList<E> extends AbstractSerializableListDecorator<E> { 061 062 /** Serialization version */ 063 private static final long serialVersionUID = -3620001881672L; 064 065 /** 066 * Factory method to create a growth list. 067 * 068 * @param <E> the type of the elements in the list 069 * @param list the list to decorate, must not be null 070 * @return a new growth list 071 * @throws NullPointerException if list is null 072 * @since 4.0 073 */ 074 public static <E> GrowthList<E> growthList(final List<E> list) { 075 return new GrowthList<>(list); 076 } 077 078 /** 079 * Constructor that uses an ArrayList internally. 080 */ 081 public GrowthList() { 082 super(new ArrayList<>()); 083 } 084 085 /** 086 * Constructor that uses an ArrayList internally. 087 * 088 * @param initialCapacity the initial capacity of the ArrayList 089 * @throws IllegalArgumentException if initial capacity is invalid 090 */ 091 public GrowthList(final int initialCapacity) { 092 super(new ArrayList<>(initialCapacity)); 093 } 094 095 /** 096 * Constructor that wraps (not copies). 097 * 098 * @param list the list to decorate, must not be null 099 * @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}