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}