001/* Copyright (C) 2013 TU Dortmund 002 * This file is part of AutomataLib, http://www.automatalib.net/. 003 * 004 * AutomataLib is free software; you can redistribute it and/or 005 * modify it under the terms of the GNU Lesser General Public 006 * License version 3.0 as published by the Free Software Foundation. 007 * 008 * AutomataLib is distributed in the hope that it will be useful, 009 * but WITHOUT ANY WARRANTY; without even the implied warranty of 010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 011 * Lesser General Public License for more details. 012 * 013 * You should have received a copy of the GNU Lesser General Public 014 * License along with AutomataLib; if not, see 015 * http://www.gnu.de/documents/lgpl.en.html. 016 */ 017package net.automatalib.commons.smartcollections; 018 019/** 020 * Control interface for collections supporting a capacity management, i.e., reserving 021 * space in advance in order to avoid repeated reallocations. 022 * 023 * @author Malte Isberner <malte.isberner@gmail.com> 024 * 025 */ 026public interface CapacityManagement { 027 /** 028 * Ensures that the internal storage has room for at least 029 * the provided number of elements. 030 * @param minCapacity the minimal number of elements the storage should 031 * have room for. 032 * @return <code>true</code> iff the internal storage had to be resized, 033 * <code>false</code> otherwise. 034 */ 035 public boolean ensureCapacity(int minCapacity); 036 037 /** 038 * Ensures that the internal storage has room for at least 039 * the provided number of <i>additional</i> elements. 040 * 041 * Calling this method is equivalent to calling the above 042 * {@link #ensureCapacity(int)} with an argument of 043 * <code>size() + additionalCapacity</code>. 044 * 045 * @param additionalCapacity the number of additional elements the storage 046 * should have room for. 047 * @return <code>true</code> iff the internal storage had to be resized, 048 * <code>false</code> otherwise. 049 */ 050 public boolean ensureAdditionalCapacity(int additionalCapacity); 051 052 /** 053 * Gives a hint regarding the capacity that should be reserved when 054 * resizing the internal storage for the next time. This method acts 055 * like a "lazy" {@link #ensureCapacity(int)}, i.e. it reserves the 056 * specified capacity at the time the next resizing of the internal 057 * storage is performed. 058 * 059 * This method is useful when a not too imprecise upper bound on the 060 * elements that will in consequence be added is known. Since the actual 061 * number of elements added may be lower than the specified upper bound, 062 * a resizing that would have been performed by 063 * {@link #ensureCapacity(int)} might not be necessary. 064 * 065 * @param nextCapacityHint the next capacity hint. 066 */ 067 public void hintNextCapacity(int nextCapacityHint); 068}