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

package net.ranides.assira.collection.map;

/**
 * Interfejs reprezentujący mapę dwuwymiarową.
 * @param <KX> 
 * @param <KY> 
 * @param <V> 
 * @author ranides
 * @todo (migration) assira
 */
@SuppressWarnings("PMD.ShortVar")
public interface CrossMap<KX, KY, V> {

    /**
     * Sprawdza, czy zawiera wartość przypisaną do podanych kluczy.
     * @param x
     * @param y
     * @return
     */
    boolean contains(KX x, KY y);
    
    /**
     * Przypisuje nową wartość do podanych kluczy.
     * @param x
     * @param y
     * @param value
     * @return poprzednio przypisana wartość lub {@code null}.
     */
    V put(KX x, KY y, V value);
    
    /**
     * Usuwa wartość przypisaną do podanych kluczy.
     * @param x
     * @param y
     * @return usunięta wartość lub {@code null}.
     */
    V remove(KX x, KY y);
    
    /**
     * Pobiera wartość przypisaną do podanych kluczy.
     * @param x
     * @param y
     * @return przypisana wartość lub {@code null}.
     */
    V get(KX x, KY y);

    /**
     * Zwraca rozmiar mapy.
     * @return
     */
    int size();
    
    /**
     * Sprawdza, czy mapa jest pusta.
     * @return
     */
    boolean isEmpty();
    
    /**
     * Usuwa całą zawartość mapy.
     */
    void clear();

    /**
     * Redukuje przypisane wartości i zwraca multi-mapę zawierającą klucze
     * @return
     */
    MultiMap<KX, KY> reduceZ();
    
    /**
     * Redukuje klucz drugiego rzędu i zwraca multi-mapę zawierającą klucze główne i przypisane im wartości
     * @return
     */
    MultiMap<KX, V> reduceY();
}
