VocItf

public interface VocItf
{
    // OVERVIEW:
    // Un Vocabolario e' una collezione di associazioni del tipo
    // 'chiave -> valore', dove sia 'chiave' che 'valore' sono stringhe,
    // e valgono le seguenti proprieta':

    // - non ci possono essere due associazioni per la stessa chiave;
    // - le associazioni sono ordinate in base alla chiave.

    // Invariante di rappresentazione:
    // I(c) = (this.IsEmpty())|| this.vect.size()==1 ||
    //    (for i=0...this.vect.size()-1
    //       for j=1...this.vect.size()
    //             (i<j implica this.vect.get(i).key<this.vect.get(j).key)))

    // Funzione di astrazione:
    // A(c) = =============
    //    =============
    // se this.IsEmpty(), altrimenti
    // A(c) = =============
    //        [key0->value]
    //    [key1->value]
    //    [....->.....]
    //    [keyN->value]
    //    =============

    // Costruttore senza parametri
    // EFFECTS: inizializza this ad un vocabolario vuoto

    // Metodi:

    public boolean isIn(String k) throws NullPointerException;
    // REQUIRE : this != null && key != null &&
    // (!this.IsEmpty()) -> per ogni
    // associazione 0 <= i < N : chiave(i) < chiave(i+1)
    // (clausola di ordinamento corretto)
    // EFFECTS : se key appartiene a this restituisce true
    // false altrimenti oppure lancia un eccezione se this==null o
    // key==null

    public boolean isEmpty() throws NullPointerException;
    // REQUIRE : this != null
    // EFFECTS : se il vocabolario è vuoto restituisce true
    // false altrimenti, oppure lancia un'eccezione se this è vuoto.

    public String searchTuple(String k) throws NotFoundException, NullPointerException;
    // REQUIRE : this != null && k != null && if (!this.IsEmpty()) -> per ogni
    // associazione 0 <= i < N : chiave(i) < chiave(i+1)
    // EFFECTS : Lancia un eccezione NullPointerException se this o una delle chiavi è null
    // altrimenti restituisce il valore associato a key se quest'ultima è presente,
    // nel caso in cui non lo sia lancia NotFoundException.

    public void insertTuple(String k, String v) throws NullPointerException;
    // REQUIRE : (this != null && k != null && v != null)
    // n.b. clausola di ordinamento corretto
    // EFFECTS : se (!isIn(k)) aggiunge all'oggetto this l'associazione key-value
    // altrimenti aggiorna il valore dell'associazione presente nel vocabolario
    // con quello passato come parametro di ingresso oppure lancia la NullPointerException
    // se this o una delle chiavi/valori è null.

    public void removeTuple(String k) throws EmptyException, NotFoundException, NullPointerException;
    // REQUIRE :(this != null && k != null)
    // // n.b. clausola di ordinamento corretto
    // EFFECTS : Se il vocabolario è vuoto lancia la EmptyException altrimenti
    // se isIn(key) rimuove dal vocabolario la tupla key-value, in caso contrario
    // lancia la NotFoundException o la NullPointerException se this o una delle chiavi
    // è nulla.

    // Funzione di astrazione
    public String toString() throws NullPointerException;
    // REQUIRE : this != null && clausola di ordinamento corretto
    // EFFECTS : restituisce sotto forma di stringa la rappresentazione grafica
    // dell'oggetto this come specificato nell' overview.

    // Funzione di controllo dell'invariante di rappresentazione
    public boolean repOk() throws NullPointerException;
    // REQUIRE : this != null && clausola di ordinamento corretto
    // EFFECTS : restituisce true se l'invariante è soddisfatta, false in caso
    // contrario

}