/**
 * @file Mersenne Twister 伪随机数生成器
 * @description 
 * 这是一个基于 Mersenne Twister 算法的伪随机数生成器(PRNG)实现。
 * 该生成器可以根据给定的种子值生成高质量的伪随机数序列。
 * 
 * @usage
 * 主要用于需要可重现随机数的场景,比如:
 * 1. 基于内容哈希值作为种子,确保相同输入产生相同的随机序列
 * 2. 游戏、模拟等需要可重复随机数的应用
 * 3. 测试用例中需要稳定随机数的场景
 */

/**
 * Mersenne Twister 伪随机数生成器类
 * @class MersenneTwister
 * 
 * @description
 * 实现了 MT19937 算法,是一个周期为 2^19937-1 的伪随机数生成器
 * 
 * @pattern 单例模式 - 每个种子对应一个独立的随机数序列
 * 
 * @example
 * ```typescript
 * const mt = new MersenneTwister(12345);
 * const randomNum = mt.genrand_int32(); 
 * ```
 */
export default class MersenneTwister {
  // MT19937 算法的常量参数
  private readonly N: number = 624;  // 状态向量长度
  private readonly M: number = 397;  // 中间点参数
  private readonly MATRIX_A: number = 0x9908b0df;  // 扭矩矩阵常量
  private readonly UPPER_MASK: number = 0x80000000;  // 最高位掩码(32位)
  private readonly LOWER_MASK: number = 0x7fffffff;  // 低31位掩码

  // 内部状态
  private mt: number[];  // 状态向量数组
  private mti: number;   // 当前状态索引

  /**
   * 构造函数
   * @param seed - 随机数生成器的种子值
   * @throws {Error} 当seed不是数字类型时抛出异常
   */
  constructor(seed: number) {
    if (typeof seed !== 'number') {
      throw new Error('种子值必须是数字类型');
    }

    this.mt = new Array(this.N);
    this.mti = this.N + 1;

    this.init_genrand(seed);
  }

  /**
   * 使用种子初始化状态向量
   * @param s - 初始化种子
   * @private
   */
  private init_genrand(s: number): void {
    this.mt[0] = s >>> 0;
    for (this.mti = 1; this.mti < this.N; this.mti++) {
      // 使用递推公式生成初始状态
      s = this.mt[this.mti - 1] ^ (this.mt[this.mti - 1] >>> 30);
      this.mt[this.mti] = (
        ((((s & 0xffff0000) >>> 16) * 1812433253) << 16) +
        (s & 0x0000ffff) * 1812433253 +
        this.mti
      ) >>> 0;
    }
  }

  /**
   * 生成一个32位的随机整数
   * @returns 范围在[0, 2^32-1]之间的随机数
   * @public
   */
  public genrand_int32(): number {
    let y: number;
    const mag01: number[] = [0x0, this.MATRIX_A];

    // 需要重新生成状态向量
    if (this.mti >= this.N) {
      let kk: number;

      // 如果没有初始化,使用默认种子
      if (this.mti === this.N + 1) {
        this.init_genrand(5489);
      }

      // 更新状态向量的前半部分
      for (kk = 0; kk < this.N - this.M; kk++) {
        y = (this.mt[kk] & this.UPPER_MASK) | (this.mt[kk + 1] & this.LOWER_MASK);
        this.mt[kk] = this.mt[kk + this.M] ^ (y >>> 1) ^ mag01[y & 0x1];
      }

      // 更新状态向量的后半部分
      for (; kk < this.N - 1; kk++) {
        y = (this.mt[kk] & this.UPPER_MASK) | (this.mt[kk + 1] & this.LOWER_MASK);
        this.mt[kk] = this.mt[kk + (this.M - this.N)] ^ (y >>> 1) ^ mag01[y & 0x1];
      }

      // 处理最后一个元素
      y = (this.mt[this.N - 1] & this.UPPER_MASK) | (this.mt[0] & this.LOWER_MASK);
      this.mt[this.N - 1] = this.mt[this.M - 1] ^ (y >>> 1) ^ mag01[y & 0x1];

      this.mti = 0;
    }

    // 获取下一个随机数
    y = this.mt[this.mti++];

    // Tempering变换提升随机性
    y ^= y >>> 11;
    y ^= (y << 7) & 0x9d2c5680;
    y ^= (y << 15) & 0xefc60000;
    y ^= y >>> 18;

    return y >>> 0;
  }
}