Line data    Source code

       1           1 : import { bool } from "./distribution/bool.ts";
       2           1 : import { date } from "./distribution/date.ts";
       3           1 : import { dice } from "./distribution/dice.ts";
       4           1 : import { die } from "./distribution/die.ts";
       5           1 : import { hex } from "./distribution/hex.ts";
       6           1 : import { int32 } from "./distribution/int32.ts";
       7           1 : import { int53 } from "./distribution/int53.ts";
       8           1 : import { int53Full } from "./distribution/int53Full.ts";
       9           1 : import { integer } from "./distribution/integer.ts";
      10           1 : import { pick } from "./distribution/pick.ts";
      11           1 : import { real } from "./distribution/real.ts";
      12           1 : import { realZeroToOneExclusive } from "./distribution/realZeroToOneExclusive.ts";
      13           1 : import { realZeroToOneInclusive } from "./distribution/realZeroToOneInclusive.ts";
      14           1 : import { sample } from "./distribution/sample.ts";
      15           1 : import { shuffle } from "./distribution/shuffle.ts";
      16           1 : import { string } from "./distribution/string.ts";
      17           1 : import { uint32 } from "./distribution/uint32.ts";
      18           1 : import { uint53 } from "./distribution/uint53.ts";
      19           1 : import { uint53Full } from "./distribution/uint53Full.ts";
      20           1 : import { uuid4 } from "./distribution/uuid4.ts";
      21           1 : import { nativeMath } from "./engine/nativeMath.ts";
      22             : import { Engine } from "./types.ts";
      23             : 
      24             : // tslint:disable:unified-signatures
      25             : 
      26             : /**
      27             :  * A wrapper around an Engine that provides easy-to-use methods for
      28             :  * producing values based on known distributions
      29             :  */
      30           1 : export class Random {
      31             :   readonly engine: Engine;
      32             : 
      33             :   /**
      34             :    * Creates a new Random wrapper
      35             :    * @param engine The engine to use (defaults to a `Math.random`-based implementation)
      36             :    */
      37           0 :   constructor(engine: Engine = nativeMath) {
      38           0 :     this.engine = engine;
      39           0 :   }
      40             : 
      41             :   /**
      42             :    * Returns a value within [-0x80000000, 0x7fffffff]
      43             :    */
      44           0 :   public int32(): number {
      45           0 :     return int32(this.engine);
      46           0 :   }
      47             : 
      48             :   /**
      49             :    * Returns a value within [0, 0xffffffff]
      50             :    */
      51           0 :   public uint32(): number {
      52           0 :     return uint32(this.engine);
      53           0 :   }
      54             : 
      55             :   /**
      56             :    * Returns a value within [0, 0x1fffffffffffff]
      57             :    */
      58           0 :   public uint53(): number {
      59           0 :     return uint53(this.engine);
      60           0 :   }
      61             : 
      62             :   /**
      63             :    * Returns a value within [0, 0x20000000000000]
      64             :    */
      65           0 :   public uint53Full(): number {
      66           0 :     return uint53Full(this.engine);
      67           0 :   }
      68             : 
      69             :   /**
      70             :    * Returns a value within [-0x20000000000000, 0x1fffffffffffff]
      71             :    */
      72           0 :   public int53(): number {
      73           0 :     return int53(this.engine);
      74           0 :   }
      75             : 
      76             :   /**
      77             :    * Returns a value within [-0x20000000000000, 0x20000000000000]
      78             :    */
      79           0 :   public int53Full(): number {
      80           0 :     return int53Full(this.engine);
      81           0 :   }
      82             : 
      83             :   /**
      84             :    * Returns a value within [min, max]
      85             :    * @param min The minimum integer value, inclusive. No less than -0x20000000000000.
      86             :    * @param max The maximum integer value, inclusive. No greater than 0x20000000000000.
      87             :    */
      88           0 :   public integer(min: number, max: number): number {
      89           0 :     return integer(min, max)(this.engine);
      90           0 :   }
      91             : 
      92             :   /**
      93             :    * Returns a floating-point value within [0.0, 1.0]
      94             :    */
      95           0 :   public realZeroToOneInclusive(): number {
      96           0 :     return realZeroToOneInclusive(this.engine);
      97           0 :   }
      98             : 
      99             :   /**
     100             :    * Returns a floating-point value within [0.0, 1.0)
     101             :    */
     102           0 :   public realZeroToOneExclusive(): number {
     103           0 :     return realZeroToOneExclusive(this.engine);
     104           0 :   }
     105             : 
     106             :   /**
     107             :    * Returns a floating-point value within [min, max) or [min, max]
     108             :    * @param min The minimum floating-point value, inclusive.
     109             :    * @param max The maximum floating-point value.
     110             :    * @param inclusive If true, `max` will be inclusive.
     111             :    */
     112           0 :   public real(min: number, max: number, inclusive: boolean = false): number {
     113           0 :     return real(min, max, inclusive)(this.engine);
     114           0 :   }
     115             : 
     116             :   /**
     117             :    * Returns a boolean with 50% probability of being true or false
     118             :    */
     119             :   public bool(): boolean;
     120             :   /**
     121             :    * Returns a boolean with the provided `percentage` of being true
     122             :    * @param percentage A number within [0, 1] of how often the result should be `true`
     123             :    */
     124             :   public bool(percentage: number): boolean;
     125             :   /**
     126             :    * Returns a boolean with a probability of `numerator`/`denominator` of being true
     127             :    * @param numerator The numerator of the probability
     128             :    * @param denominator The denominator of the probability
     129             :    */
     130             :   public bool(numerator: number, denominator: number): boolean;
     131           0 :   public bool(numerator?: number, denominator?: number): boolean {
     132           0 :     return bool(numerator!, denominator!)(this.engine);
     133           0 :   }
     134             : 
     135             :   /**
     136             :    * Return a random value within the provided `source` within the sliced
     137             :    * bounds of `begin` and `end`.
     138             :    * @param source an array of items to pick from
     139             :    * @param begin the beginning slice index (defaults to `0`)
     140             :    * @param end the ending slice index (defaults to `source.length`)
     141             :    */
     142           0 :   public pick<T>(source: ArrayLike<T>, begin?: number, end?: number): T {
     143           0 :     return pick(this.engine, source, begin, end);
     144           0 :   }
     145             : 
     146             :   /**
     147             :    * Shuffles an array in-place
     148             :    * @param array The array to shuffle
     149             :    */
     150           0 :   public shuffle<T>(array: T[]): T[] {
     151           0 :     return shuffle(this.engine, array);
     152           0 :   }
     153             : 
     154             :   /**
     155             :    * From the population array, returns an array with sampleSize elements that
     156             :    * are randomly chosen without repeats.
     157             :    * @param population An array that has items to choose a sample from
     158             :    * @param sampleSize The size of the result array
     159             :    */
     160           0 :   public sample<T>(population: ArrayLike<T>, sampleSize: number): T[] {
     161           0 :     return sample(this.engine, population, sampleSize);
     162           0 :   }
     163             : 
     164             :   /**
     165             :    * Returns a value within [1, sideCount]
     166             :    * @param sideCount The number of sides of the die
     167             :    */
     168           0 :   public die(sideCount: number): number {
     169           0 :     return die(sideCount)(this.engine);
     170           0 :   }
     171             : 
     172             :   /**
     173             :    * Returns an array of length `dieCount` of values within [1, sideCount]
     174             :    * @param sideCount The number of sides of each die
     175             :    * @param dieCount The number of dice
     176             :    */
     177           0 :   public dice(sideCount: number, dieCount: number): number[] {
     178           0 :     return dice(sideCount, dieCount)(this.engine);
     179           0 :   }
     180             : 
     181             :   /**
     182             :    * Returns a Universally Unique Identifier Version 4.
     183             :    *
     184             :    * See http://en.wikipedia.org/wiki/Universally_unique_identifier
     185             :    */
     186           0 :   public uuid4(): string {
     187           0 :     return uuid4(this.engine);
     188           0 :   }
     189             : 
     190             :   /**
     191             :    * Returns a random string using numbers, uppercase and lowercase letters,
     192             :    * `_`, and `-` of length `length`.
     193             :    * @param length Length of the result string
     194             :    */
     195             :   public string(length: number): string;
     196             :   /**
     197             :    * Returns a random string using the provided string pool as the possible
     198             :    * characters to choose from of length `length`.
     199             :    * @param length Length of the result string
     200             :    */
     201             :   public string(length: number, pool: string): string;
     202           0 :   public string(length: number, pool?: string): string {
     203           0 :     return string(pool!)(this.engine, length);
     204           0 :   }
     205             : 
     206             :   /**
     207             :    * Returns a random string comprised of numbers or the characters `abcdef`
     208             :    * (or `ABCDEF`) of length `length`.
     209             :    * @param length Length of the result string
     210             :    * @param uppercase Whether the string should use `ABCDEF` instead of `abcdef`
     211             :    */
     212           0 :   public hex(length: number, uppercase?: boolean): string {
     213           0 :     return hex(uppercase)(this.engine, length);
     214           0 :   }
     215             : 
     216             :   /**
     217             :    * Returns a random `Date` within the inclusive range of [`start`, `end`].
     218             :    * @param start The minimum `Date`
     219             :    * @param end The maximum `Date`
     220             :    */
     221           0 :   public date(start: Date, end: Date): Date {
     222           0 :     return date(start, end)(this.engine);
     223           0 :   }
     224           1 : }