/*****************************************************************
 * Dice
 *
 * Member Variables: 
 *    Die[] dice - holds an array of Die objects
 *
 * Private Methods: none
 *
 * Public Methods: 
 *    Dice(int numDice) - constructor to setup the array
 *    void roll() - rolls each Die in the array
 *    Die getDie(int position) - returns the Die object at the
 *                               specified position in the array
 *    int getNumDie() - returns the number of Die objects in the
 *                      array
 *    String toString() - returns a String representation of all
 *                        of the Die objects in the array
 ****************************************************************/
public class Dice
{
    // The data member dice is a reference variable that 
    // can point to an array of Die objects.
    private Die[] dice;

    /*******************************************
     * Dice Constructor
     *
     * - Takes a parameter, numDice, that describes
     *   how many elements should be in the array
     * - Instantiates the array with numDice elements
     * - Instantiates each Die object
     *******************************************/
    public Dice (int numDice)
    {
        // Create space in memory to hold numDice reference
        // variables that each can point to a Die object.
        // Save the address of the array of reference variables
        // in the data member dice.
        dice = new Die[numDice];
        // The data member dice has already been declared (see above)
        // so it should not be preceeded by Die[]. Using
        // Die[] dice = new Die[numDice]; creates a NEW reference 
        // instead of referring to the data member.

        // For each element in the dice array, instantiate a new
        // Die object and save the address in the appropriate
        // reference variable.
        for (int i=0; i<dice.length; i++) {
            // The constructor for Die does not take parameters,
            // so no parameters should be given.
            dice[i] = new Die();
        }
    }

    /*******************************************
     * roll
     *
     * - Takes no parameters
     * - Returns nothing
     * - Rolls each Die object in the arrry
     *******************************************/
    public void roll()
    {
        // For each element in the dice array, call the
        // roll method to randomly choose a face value
        for (int i=0; i<dice.length; i++) {
            dice[i].roll();
        }
    }

    /*******************************************
     * getDie
     *
     * - Takes an integer parameter, position
     * - Returns the Die object at that position,
     *   or null, if the position is invalid
     *******************************************/
    public Die getDie (int position)
    {
        // Make sure that position is a valid index
        // (between 0 and dice.length)        
        if (position >= dice.length || position < 0) {
            // position is invalid, return null
            return null;
        }
        // position is valid, return the appropriate Die object
        return dice[position];
    }

    /*******************************************
     * getNumDice
     *
     * - Takes no parameters
     * - Returns the length of the dice array
     *******************************************/
    public int getNumDice()
    {
        // The data member dice is private, so classes outside
        // of Dice cannot directly access dice, which also means
        // that they cannot directly access dice.length.
        return dice.length;
    }

    /*******************************************
     * toString
     *
     * - Takes no parameters
     * - Returns a String containing the face values
     *   of all of the Die objects in the array
     *******************************************/
    public String toString()
    {
        // Create a blank String variable
        String diceString = "";

        // For each element in the dice array, add its
        // face value (obtained through dice[i].getFace())
        // to the String.  Separate each element's face
        // by the tab character.
        for (int i=0; i<dice.length; i++) {
            diceString += dice[i].getFace() + "\t";
        }
        // Return the completed String
        return (diceString);
    }

} // end of Dice class