/* An instance of this class represents a (potentially biased) coin that 
** is suitable for simulating a sequence of coin tosses.
** It enhances its parent class by providing a way for the client program
** to specify --via a parameter passed to a constructor-- the probability 
** with which the toss() method should produce a result of HEADS.
**
** Author: R. McCloskey
** Date: January 2024
*/
public class BiasedCoin extends Coin {

   // class constant
   // --------------

   protected static final double ONE_HALF = 1.0/2.0;  // default probability


   // instance variable
   // -----------------

   protected double headsProb; // probability of a toss resulting in HEADS


   // constructors
   // ------------

   /* Establishes this coin as one that is showing HEADS and whose toss()
   ** method
   ** --uses a pseudo-random number generator seeded by the given number and 
   ** --produces a HEADS result with the given probability.
   */
   public BiasedCoin(int seed, double probOfHeads) {
      super(seed);
      initHeadsProb(probOfHeads);
   }


   /* Establishes this coin as one that is showing HEADS and whose toss()
   ** method
   ** --uses a pseudo-random number generator seeded by the given number and 
   ** --produces a HEADS result with probability one-half.
   */
   public BiasedCoin(int seed) { this(seed, ONE_HALF); }

   /* Establishes this coin as one that is showing HEADS and whose toss()
   ** method
   ** --uses a pseudo-random number generator seeded by a number that is 
   **   itself generated pseudo-randomly and 
   ** --produces a HEADS result with the given probability.
   */
   public BiasedCoin(double probOfHeads) {
      super();
      initHeadsProb(probOfHeads);
   }

   /* Establishes this coin as one that is showing HEADS and whose toss()
   ** method
   ** --uses a pseudo-random number generator seeded by a number that is 
   **   itself generated pseudo-randomly and 
   ** --produces a HEADS result with probability one-half.
   */
   public BiasedCoin() { this(ONE_HALF); }


   // method in support of constructors
   // ---------------------------------

   /* Throws an exception if the parameter's value is outside the range
   ** [0.0 .. 1.0]; otherwise sets the 'headsProb' instance variable to
   ** that value.
   */
   protected void initHeadsProb(double probOfHeads) {
      if (probOfHeads < 0.0  ||  probOfHeads > 1.0) {
         throw new IllegalArgumentException("Probability has to be in [0..1]");
      }
      this.headsProb = probOfHeads;
   }


   // observers
   // ---------

   /* Reports the probability with which a toss of this coin results
   ** in HEADS.
   */
   public double headsProbability() { return headsProb; }

   /* Reports the probability with which a toss of this coin results
   ** in TAILS.
   */
   public double tailsProbability()
      { return 1.0 - headsProbability(); }


   @Override
   public String toString() {
      String headsProbStr = String.format("  Probability of HEADS: %.2f",
                                          headsProbability());
      return super.toString() + '\n' + headsProbStr;
   }


   // mutator
   // -------

   @Override
   public void toss() {
      // Maps pseudo-random numbers in interval [0.0 .. headsProb) to HEADS
      // and those in [headsProb .. 1.0) to TAILS.
      isHeads = rand.nextDouble() < headsProb;
   }

}