import java.util.Set;

/**
 * A <code>CodeBookI</code> contains the symbols, frequencies and encodings
 * for character based inputs. It is also able to encode individual symbols, or
 * entire strings.
 * @author CIS-121 Staff
 * @version 1.0 - 03/19/08
 */
public interface CodeBookI
{
	/**
	 * Returns the set of all valid symbols.
	 * @return The set of all valid symbols.
	 */
	public Set<Character> getAlphabet();

	/**
	 * Return the probability of a given symbol. The probability of a symbol is
	 * defined as: (frequency of symbol) / (sum of frequencies of all symbols).
	 * @param symbol The symbol being queried.
	 * @return The probability of a given symbol.
	 * @throws InvalidSymbolException If the given symbol is not handled by this
	 *             CodeBookI
	 */
	public double getProbability(char symbol) throws InvalidSymbolException;

	/**
	 * Return the expected coding length of the entire code-book. The value of
	 * the expected coding length is defined as: sum over all symbols of (symbol
	 * probability) * (length of symbol encoding).
	 * @return The expected coding length of the entire code-book.
	 */
	public double expectedEncodingLength();

	/**
	 * Add the given symbol to the code-book. If the given symbol is already
	 * included in this code-book, replace it with the new entry.
	 * @param symbol The symbol being added.
	 * @param frequency The <em>relative</em> frequency of this symbol with
	 *            respect to all other symbols.
	 * @param encoding The encoding of this symbol.
	 * @throws IllegalArgumentException If the frequency is not positive.
	 */
	public void putSymbol(char symbol, double frequency, String encoding)
			throws IllegalArgumentException;

	/**
	 * Encodes a single symbol.
	 * @param symbol The symbol to encode.
	 * @return The encoding of this one symbol.
	 * @throws InvalidSymbolException If the given symbol is not handled by this
	 *             CodeBookI
	 */
	public String encode(char symbol) throws InvalidSymbolException;

	/**
	 * Encodes a String of symbols.
	 * @param text The String to encode.
	 * @return The encoded text.
	 * @throws InvalidSymbolException If the given symbol is not handled by this
	 *             CodeBookI
	 */
	public String encode(String text) throws InvalidSymbolException;
}