Modified and documented boolean chance operators

src/API.ts

@@ -705,55 +705,91 @@ export class UserAPI {
   // Probability functions
   // =============================================================
 
-  public almostNever = (): boolean => {
+  public odds = (n: number, sec: number = 15): boolean => {
+    /**
+     * Returns true n% of the time.
+     * 
+     * @param n - The probability of returning true. 1/4 = 25% = 0.25, 80/127 = 62.9% = 0.6299212598425197, etc...
+     * @param sec - The time frame in seconds
+     * @returns True n% of the time
+     */
+    return this.randomGen() < n*this.ppqn()/(this.ppqn()*sec);
+  };
+
+  public almostNever = (sec: number = 15): boolean => {
+    /**
+     * Returns true 2.5% of the time in given time frame.
+     * 
+     * @param sec - The time frame in seconds
+     * @returns True 2.5% of the time
+     */
+    return this.randomGen() < 0.025*this.ppqn()/(this.ppqn()*sec);
+  };
+
+  public rarely = (sec: number = 15): boolean => {
     /**
      * Returns true 10% of the time.
-     *
-     * @returns True 10% of the time
+     * 
+     * @param sec - The time frame in seconds
+     * @returns True 10% of the time. 
      */
-    return this.randomGen() > 0.9;
+    return this.randomGen() < 0.1*this.ppqn()/(this.ppqn()*sec);
   };
 
-  public sometimes = (): boolean => {
-    /**
-     * Returns true 50% of the time.
-     *
-     * @returns True 50% of the time
-     */
-    return this.randomGen() > 0.5;
-  };
-
-  public rarely = (): boolean => {
+  public scarcely = (sec: number = 15): boolean => {
     /**
      * Returns true 25% of the time.
-     *
+     * 
+     * @param sec - The time frame in seconds
      * @returns True 25% of the time
      */
-    return this.randomGen() > 0.75;
+    return this.randomGen() < 0.25*this.ppqn()/(this.ppqn()*sec);
   };
 
-  public often = (): boolean => {
+  public sometimes = (sec: number = 15): boolean => {
+    /**
+     * Returns true 50% of the time.
+     * 
+     * @param sec - The time frame in seconds
+     * @returns True 50% of the time
+     */
+    return this.randomGen() < 0.5*this.ppqn()/(this.ppqn()*sec);
+  };
+
+  public often = (sec: number = 15): boolean => {
     /**
      * Returns true 75% of the time.
-     *
+     * 
+     * @param sec - The time frame in seconds
      * @returns True 75% of the time
      */
-    return this.randomGen() > 0.25;
+    return this.randomGen() < 0.75*this.ppqn()/(this.ppqn()*sec);
   };
 
-  public almostAlways = (): boolean => {
+  public frequently = (sec: number = 15): boolean => {
     /**
      * Returns true 90% of the time.
-     *
+     * 
+     * @param sec - The time frame in seconds
      * @returns True 90% of the time
      */
-    return this.randomGen() > 0.1;
+    return this.randomGen() < 0.9*this.ppqn()/(this.ppqn()*sec);
+  };
+
+  public almostAlways = (sec: number = 15): boolean => {
+    /**
+     * Returns true 98.5% of the time.
+     * 
+     * @param sec - The time frame in seconds
+     * @returns True 98.5% of the time
+     */
+    return this.randomGen() < 0.985*this.ppqn()/(this.ppqn()*sec);
   };
 
   public dice = (sides: number): number => {
     /**
      * Returns the value of a dice roll with n sides.
-     *
+     * 
      * @param sides - The number of sides on the dice
      * @returns The value of a dice roll with n sides
      */

src/Documentation.ts

@@ -484,6 +484,17 @@ There are some simple functions to play with probabilities.
 - <icode>toss()</icode>: throwing a coin. Head (<icode>true</icode>) or tails (<icode>false</icode>).
 - <icode>seed(val: number|string)</icode>: sets the seed of the random number generator. You can use a number or a string. The same seed will always return the same sequence of random numbers.
 
+Chance operators returning a boolean value are also available:
+
+- <icode>odds(n: number, sec?: number)</icode>: returns true for every n (odds) (eg. 1/4 = 0.25) in given seconds (sec)
+- <icode>almostNever(sec?: number)</icode>: returns true 0.1% in given seconds (sec)
+- <icode>rarely(sec?: number)</icode>: returns true 1% in given seconds (sec)
+- <icode>scaresly(sec?: number)</icode>: returns true 10% in given seconds (sec)
+- <icode>sometimes(sec?: number)</icode>: returns true 50% in given seconds (sec)
+- <icode>often(sec?: number)</icode>: returns true 75% in given seconds (sec)
+- <icode>frequently(sec?: number)</icode>: returns true 90% in given seconds (sec)
+- <icode>almostAlways(sec?: number)</icode>: returns true 99% in given seconds (sec)
+
 ## Math functions
 
 - <icode>max(...values: number[]): number</icode>: returns the maximum value of a list of numbers.

src/Event.ts

@@ -12,23 +12,39 @@ export class Event {
         }
     }
 
-    sometimesBy = (probability: number, func: Function): Event => {
+    odds = (probability: number, func: Function): Event => {
         if(this.randomGen() < probability) {
             return this.modify(func);
         }
         return this;
     }
 
-    sometimes = (func: Function): Event => {
-        return this.sometimesBy(0.5, func);
+    almostNever = (func: Function): Event => {
+        return this.odds(0.025, func);
     }
 
     rarely = (func: Function): Event => {
-        return this.sometimesBy(0.1, func);
+        return this.odds(0.1, func);
+    }
+
+    scarcely = (func: Function): Event => {
+        return this.odds(0.25, func);
+    }
+
+    sometimes = (func: Function): Event => {
+        return this.odds(0.5, func);
     }
 
     often = (func: Function): Event => {
-        return this.sometimesBy(0.9, func);
+        return this.odds(0.75, func);
+    }
+
+    frequently = (func: Function): Event => {
+        return this.odds(0.9, func);
+    }
+
+    almostAlways = (func: Function): Event => {
+        return this.odds(0.985, func);
     }
 
     modify = (func: Function): Event => {