package toy;

/**
 * ToyDebugHash is essentially a table of Strings (the pseudocode for commands
 * in a program or an ellipsis) and the addresses of those corresponding
 * commands.  Such a table is necessary because not all possible addresses will
 * be used in a program and, with the use of ellipses to denote regions of
 * memory without initialized commands, addresses are skipped and do not
 * necessarily correspond to the line. Here is such an example for the program
 * echo:
 *
 * <BLOCKQUOTE>
 * <b>Program text</b>:
 * <PRE>
 *    Program Echo
 *    Input:    Any sequence of integers ending with 0000
 *    Output:   A copy of that sequence without the 0000
 *    Remarks:  -
 *    --------------------------------------------------------------------------------
 *
 *    // loop
 *    10: 81FF   read R[1]
 *    11: C114   if (R[1] == 0) goto 14
 *    12: 91FF   write R[1]
 *    13: C010   goto 10
 *
 *    // halt
 *    14: 0000   halt
 * </PRE>
 *
 * <b>ToyDebugHash Table</b>:
 * <PRE>
 *    Line Address String
 *    0    0x00    ...
 *    1    0x10    10: 81FF   read R[1]
 *    2    0x11    11: C114   if (R[1] == 0) goto 14
 *    3    0x12    12: 91FF   write R[1]
 *    4    0x13    13: C010   goto 10
 *    5    0x14    14: 0000   halt
 * </PRE>
 * </BLOCKQUOTE>
 *
 * @author Brian Tsang
 * @version 7.0
 */

public class ToyDebugHash
{
    /**
     * The array of strings (either ellipses or pseudocode).
     */
    private String codeArray[];
    /**
     * The array of addresses corresponding to the strings of
     * <a href="#codeArray">codeArray</a>.
     * @see #codeArray
     */
    private short addressArray[];
    /**
     * The number of strings/addresses in codeArray and addressArray.  The two
     * arrays are declared to be the largest possible size.  So codeArray.length
     * or addressArray.length will not give you the total number of lines used.
     * @see #codeArray
     * @see #addressArray
     */
    private int cardinality;

    /**
     * Constructs a new debug hash with the arrays initialized to the largest
     * possible size.
     */
    public ToyDebugHash()
    {
        cardinality = 0;
        codeArray = new String[ToyVirtualMachine.MEM_CARDINALITY];
        addressArray = new short[ToyVirtualMachine.MEM_CARDINALITY];
    }

    /**
     * Adds a particular line of pseudocode to the table.  Note: lines must be
     * added in order.
     *
     * @param address the address corresponding to this line of code
     * @param code the line of code
     */
    public void add(short address, String code)
    {
        if (cardinality < ToyVirtualMachine.MEM_CARDINALITY)
        {
            addressArray[cardinality] = address;
            codeArray[cardinality] = code;
            cardinality++;
        }
    }

    /**
     * Returns the line number corresponding to the address.
     *
     * @return the line number of the address
     * @param address the address of the desired line
     */
    public int getLine(short address)
    {
        int answer = 0;

        while (answer + 1 < cardinality && addressArray[answer + 1] <= address)
            answer++;

        return answer;
    }

    /**
     * Returns the pseudocode string for a given line.
     *
     * @return the pesudocode string for a given line
     * @param line the line of the desired pseudocode string
     */
    public String getCode(int line)
    {
        return codeArray[line];
    }

    /**
     * Returns the number of lines we have so far.
     *
     * @return the number of lines we have so far
     */
    public int getCardinality()
    {
        return cardinality;
    }
}