/*
 * @author Ranides Atterwim <ranides@gmail.com>
 * @copyright Ranides Atterwim
 * @license WTFPL
 * @url http://ranides.net/projects/assira
 */
package net.ranides.assira.collection.maps;

import java.util.Map;

/**
 *
 * @author Ranides Atterwim <ranides@gmail.com>
 */
public interface BlockMap<K,V> extends Map<K,V> {
    
    int capacity();

    /**
     * Reallocates this collection, making the capacity as small as possible.
     *
     * <P>This method reallocates the internal table to the smallest possible size. 
     * It can be used when the collection will not be changed anymore, so
     * to optimize access speed and size.
     *
     * <P>If the table size is already the minimum possible, this method does nothing.
     *
     * @return true if there was enough memory to trim the collection.
     * @see #trim(int)
     */
    boolean trim();

    /**
     * Reallocates this collection if the table is too large.
     *
     * <P>Let <var>N</var> be the smallest capacity that can hold
     * <code>max(n,{@link #size()})</code> entries, still satisfying internal constraints. 
     * If the current table size is smaller than or equal to
     * <var>N</var>, this method does nothing. Otherwise, it resizes this set
     * in a table of size <var>N</var>.
     *
     * <P>This method is useful when reusing collections. {@linkplain #clear() Clearing a
     * set} leaves in most situations the collection capacity untouched. If you are reusing a collection many
     * times, you can call this method with a typical size to avoid keeping
     * around a very large memory usage just because of a few large transient sets.
     *
     * @param n the threshold for the trimming.
     * @return true if there was enough memory to trim the set.
     * @see #trim()
     */
    boolean trim(int n);
    
}
