Package cpsc331.collections

Interface Mapping<K,V>

All Known Subinterfaces:

Dictionary<K,V>

All Known Implementing Classes:

BSTDictionary, ChainHashMap, OpenHashMap

public interface Mapping<K,V>

Provides an interface for a mapping whose keys are of type K and whose values are of type E.

Mapping Invariant: A finite collection S of pairs (k, v) of values where k has type K and is not null, and v has type V, is maintained. For each element k of K, the collection includes at most one ordered pair whose first entry is k, so that a partial function from K to V is being represented.

Method Summary

Modifier and Type	Method	Description
default boolean	defined(K k)
V	get(K k)	Returns the value associated with a given key, throwing a NoSuchElementException if no value is currently associated with the given key.
void	remove(K k)	Removes the ordered pair with a given input key k, returning a NoSuchElementException and leaving the Mapping unchanged if no such ordered pair exists.
void	set(K k, V v)	Sets the value associated with an input key to be an input value — replacing the value formerly associated with this key if one already exists.

Method Detail

get

V get(K k)
throws java.lang.NullPointerException,
      java.util.NoSuchElementException

Returns the value associated with a given key, throwing a NoSuchElementException if no value is currently associated with the given key.

Parameters:

k - the key whose value is to be returned

Returns:

the value of this key

Throws:

java.lang.NullPointerException - if the input key is null

java.util.NoSuchElementException - if the key is not null, but no value is defined for this key

Precondition:

1. The Mapping Invariant is satisfied.
2. A value k with type K has been provided as input.

Postcondition:

1. The Mapping Invariant is satisfied.
2. This Mapping has not been changed.
3. If k is null then a NullPointerException is thrown.
4. Otherwise (that is, if k is not null), if this Mapping includes some ordered pair whose first entry is the input key k, then the value v that is the second entry of this ordered pair (that is, the value associated with k) is returned as output. A NoSuchElementException is thrown otherwise.

defined

default boolean defined(K k)
                 throws java.lang.NullPointerException

Parameters:

k - the key to be searched for

Returns:

true if k is found; false otherwise

Throws:

java.lang.NullPointerException - if k is null

Reports whether a value for an input key k is presently defined.

Precondition:

1. The Mapping Invariant is satisfied.
2. A value k with type K has been provided as input.

Postcondition:

1. The Mapping Invariant is satisfied.
2. This Mapping has not been changed.
3. If k is null then a NullPointerException is thrown.
4. Otherwise (that is, if k is not null), if this Mapping includes some ordered pair whose first entry is the input key k, then true is returned. Otherwise, false is returned.

set

void set(K k,
         V v)
  throws java.lang.NullPointerException

Sets the value associated with an input key to be an input value — replacing the value formerly associated with this key if one already exists.

Parameters:

k - the key for which a value is to be defined

v - the value that is to be defined to this key

Throws:

java.lang.NullPointerException - if k is null

Precondition:

1. The Mapping Invariant is satisfied.
2. A value k with type K and v with type V are provided as input.

Postcondition:

1. The Mapping Invariant is satisfied.
2. If k is null then a NullPointerException is thrown.
3. Otherwise (that is, if k is not null), if this Mapping included an ordered pair whose first entry is the input value k, then this is replaced by the ordered pair (k, v). Otherwise a new ordered pair (k, v) is added. No other changes to this Mapping are made.

remove

void remove(K k)
     throws java.lang.NullPointerException,
            java.util.NoSuchElementException

Removes the ordered pair with a given input key k, returning a NoSuchElementException and leaving the Mapping unchanged if no such ordered pair exists.

Parameters:

k - the key for which a value is to be undefined

Throws:

java.lang.NullPointerException - if k is null

java.util.NoSuchElementException - if no value was defined for this key

Precondition:

1. The Dictionary Invariant is satisfied.
2. A value k with type K is provided as input.

Postcondition:

1. The Mapping Invariant is satisfied.
2. If k is null then a NullPointerException is thrown.
3. Otherwise (that is, if k is not null) if this Mapping includes an ordered pair (k, v) whose first entry is the input key k then this ordered pair is removed; no other changes are made. Otherwise a NoSuchElementException is thrown and this Mapping is not changed at all.