//! Grisu3 算法的 Rust 适应性，在使用整数快速而准确地打印浮点数 [^1] 中进行了介绍。
//! 它使用大约 1KB 的预先计算表，因此，对于大多数输入而言，它非常快。
//!
//! [^1]: Florian Loitsch.  2010. 快速、高效地打印浮点数字
//!   准确地使用整数。SIGPLAN 不是。45, 6 (2010 年 6 月)，233-243。
//!

use crate::mem::MaybeUninit;
use crate::num::diy_float::Fp;
use crate::num::flt2dec::{round_up, Decoded, MAX_SIG_DIGITS};

// 有关基本原理，请参见 `format_shortest_opt` 中的注释。
#[doc(hidden)]
pub const ALPHA: i16 = -60;
#[doc(hidden)]
pub const GAMMA: i16 = -32;

/*
# the following Python code generates this table:
for i in xrange(-308, 333, 8):
    if i >= 0: f = 10**i; e = 0
    else: f = 2**(80-4*i) // 10**-i; e = 4 * i - 80
    l = f.bit_length()
    f = ((f << 64 >> (l-1)) + 1) >> 1; e += l - 64
    print '    (%#018x, %5d, %4d),' % (f, e, i)
*/

#[doc(hidden)]
pub static CACHED_POW10: [(u64, i16, i16); 81] = [
    // (f, e,  k)
    (0xe61acf033d1a45df, -1087, -308),
    (0xab70fe17c79ac6ca, -1060, -300),
    (0xff77b1fcbebcdc4f, -1034, -292),
    (0xbe5691ef416bd60c, -1007, -284),
    (0x8dd01fad907ffc3c, -980, -276),
    (0xd3515c2831559a83, -954, -268),
    (0x9d71ac8fada6c9b5, -927, -260),
    (0xea9c227723ee8bcb, -901, -252),
    (0xaecc49914078536d, -874, -244),
    (0x823c12795db6ce57, -847, -236),
    (0xc21094364dfb5637, -821, -228),
    (0x9096ea6f3848984f, -794, -220),
    (0xd77485cb25823ac7, -768, -212),
    (0xa086cfcd97bf97f4, -741, -204),
    (0xef340a98172aace5, -715, -196),
    (0xb23867fb2a35b28e, -688, -188),
    (0x84c8d4dfd2c63f3b, -661, -180),
    (0xc5dd44271ad3cdba, -635, -172),
    (0x936b9fcebb25c996, -608, -164),
    (0xdbac6c247d62a584, -582, -156),
    (0xa3ab66580d5fdaf6, -555, -148),
    (0xf3e2f893dec3f126, -529, -140),
    (0xb5b5ada8aaff80b8, -502, -132),
    (0x87625f056c7c4a8b, -475, -124),
    (0xc9bcff6034c13053, -449, -116),
    (0x964e858c91ba2655, -422, -108),
    (0xdff9772470297ebd, -396, -100),
    (0xa6dfbd9fb8e5b88f, -369, -92),
    (0xf8a95fcf88747d94, -343, -84),
    (0xb94470938fa89bcf, -316, -76),
    (0x8a08f0f8bf0f156b, -289, -68),
    (0xcdb02555653131b6, -263, -60),
    (0x993fe2c6d07b7fac, -236, -52),
    (0xe45c10c42a2b3b06, -210, -44),
    (0xaa242499697392d3, -183, -36),
    (0xfd87b5f28300ca0e, -157, -28),
    (0xbce5086492111aeb, -130, -20),
    (0x8cbccc096f5088cc, -103, -12),
    (0xd1b71758e219652c, -77, -4),
    (0x9c40000000000000, -50, 4),
    (0xe8d4a51000000000, -24, 12),
    (0xad78ebc5ac620000, 3, 20),
    (0x813f3978f8940984, 30, 28),
    (0xc097ce7bc90715b3, 56, 36),
    (0x8f7e32ce7bea5c70, 83, 44),
    (0xd5d238a4abe98068, 109, 52),
    (0x9f4f2726179a2245, 136, 60),
    (0xed63a231d4c4fb27, 162, 68),
    (0xb0de65388cc8ada8, 189, 76),
    (0x83c7088e1aab65db, 216, 84),
    (0xc45d1df942711d9a, 242, 92),
    (0x924d692ca61be758, 269, 100),
    (0xda01ee641a708dea, 295, 108),
    (0xa26da3999aef774a, 322, 116),
    (0xf209787bb47d6b85, 348, 124),
    (0xb454e4a179dd1877, 375, 132),
    (0x865b86925b9bc5c2, 402, 140),
    (0xc83553c5c8965d3d, 428, 148),
    (0x952ab45cfa97a0b3, 455, 156),
    (0xde469fbd99a05fe3, 481, 164),
    (0xa59bc234db398c25, 508, 172),
    (0xf6c69a72a3989f5c, 534, 180),
    (0xb7dcbf5354e9bece, 561, 188),
    (0x88fcf317f22241e2, 588, 196),
    (0xcc20ce9bd35c78a5, 614, 204),
    (0x98165af37b2153df, 641, 212),
    (0xe2a0b5dc971f303a, 667, 220),
    (0xa8d9d1535ce3b396, 694, 228),
    (0xfb9b7cd9a4a7443c, 720, 236),
    (0xbb764c4ca7a44410, 747, 244),
    (0x8bab8eefb6409c1a, 774, 252),
    (0xd01fef10a657842c, 800, 260),
    (0x9b10a4e5e9913129, 827, 268),
    (0xe7109bfba19c0c9d, 853, 276),
    (0xac2820d9623bf429, 880, 284),
    (0x80444b5e7aa7cf85, 907, 292),
    (0xbf21e44003acdd2d, 933, 300),
    (0x8e679c2f5e44ff8f, 960, 308),
    (0xd433179d9c8cb841, 986, 316),
    (0x9e19db92b4e31ba9, 1013, 324),
    (0xeb96bf6ebadf77d9, 1039, 332),
];

#[doc(hidden)]
pub const CACHED_POW10_FIRST_E: i16 = -1087;
#[doc(hidden)]
pub const CACHED_POW10_LAST_E: i16 = 1039;

#[doc(hidden)]
pub fn cached_power(alpha: i16, gamma: i16) -> (i16, Fp) {
    let offset = CACHED_POW10_FIRST_E as i32;
    let range = (CACHED_POW10.len() as i32) - 1;
    let domain = (CACHED_POW10_LAST_E - CACHED_POW10_FIRST_E) as i32;
    let idx = ((gamma as i32) - offset) * range / domain;
    let (f, e, k) = CACHED_POW10[idx as usize];
    debug_assert!(alpha <= e && e <= gamma);
    (k, Fp { f, e })
}

/// 给定 `x > 0`，则返回 `(k, 10^k)`，如 `10^k <= x < 10^(k+1)`。
#[doc(hidden)]
pub fn max_pow10_no_more_than(x: u32) -> (u8, u32) {
    debug_assert!(x > 0);

    const X9: u32 = 10_0000_0000;
    const X8: u32 = 1_0000_0000;
    const X7: u32 = 1000_0000;
    const X6: u32 = 100_0000;
    const X5: u32 = 10_0000;
    const X4: u32 = 1_0000;
    const X3: u32 = 1000;
    const X2: u32 = 100;
    const X1: u32 = 10;

    if x < X4 {
        if x < X2 {
            if x < X1 { (0, 1) } else { (1, X1) }
        } else {
            if x < X3 { (2, X2) } else { (3, X3) }
        }
    } else {
        if x < X6 {
            if x < X5 { (4, X4) } else { (5, X5) }
        } else if x < X8 {
            if x < X7 { (6, X6) } else { (7, X7) }
        } else {
            if x < X9 { (8, X8) } else { (9, X9) }
        }
    }
}

/// Grisu 的最短模式实现。
///
/// 否则，当返回不精确的表示形式时，它将返回 `None`。
pub fn format_shortest_opt<'a>(
    d: &Decoded,
    buf: &'a mut [MaybeUninit<u8>],
) -> Option<(/*digits*/ &'a [u8], /*exp*/ i16)> {
    assert!(d.mant > 0);
    assert!(d.minus > 0);
    assert!(d.plus > 0);
    assert!(d.mant.checked_add(d.plus).is_some());
    assert!(d.mant.checked_sub(d.minus).is_some());
    assert!(buf.len() >= MAX_SIG_DIGITS);
    assert!(d.mant + d.plus < (1 << 61)); // 我们至少需要三位额外的精度

    // 从具有共享指数的归一化值开始
    let plus = Fp { f: d.mant + d.plus, e: d.exp }.normalize();
    let minus = Fp { f: d.mant - d.minus, e: d.exp }.normalize_to(plus.e);
    let v = Fp { f: d.mant, e: d.exp }.normalize_to(plus.e);

    // 找到任何 `cached = 10^minusk` 这样的 `ALPHA <= minusk + plus.e + 64 <= GAMMA`。
    // 由于 `plus` 已标准化，这意味着 `2^(62 + ALPHA) <= plus * cached < 2^(64 + GAMMA)`；
    // 考虑到我们选择了 `ALPHA` 和 `GAMMA`，这会将 `plus * cached` 放入 `[4, 2^32)`。
    //
    // 显然，最大化 `GAMMA - ALPHA` 是可取的，这样我们就不需要很多 10 的缓存幂，但是有一些注意事项：
    //
    //
    // 1. 我们希望将 `floor(plus * cached)` 保留在 `u32` 之内，因为它需要一个代价高昂的除法。
    //    (这实际上是无法避免的，需要剩余的部分来进行准确性估算。)
    // 2.
    // `floor(plus * cached)` 的其余部分反复乘以 10，并且不应溢出。
    //
    // 第一个给出 `64 + GAMMA <= 32`，第二个给出 `10 * 2^-ALPHA <= 2^64`；
    // -60 和 -32 是此约束的最大范围，V8 也使用它们。
    let (minusk, cached) = cached_power(ALPHA - plus.e - 64, GAMMA - plus.e - 64);

    // 缩放 fps。这给出了 1 ulp 的最大误差 (由定理 5.1 证明)。
    let plus = plus.mul(&cached);
    let minus = minus.mul(&cached);
    let v = v.mul(&cached);
    debug_assert_eq!(plus.e, minus.e);
    debug_assert_eq!(plus.e, v.e);

    // +- 负的实际范围
    //   | <---|---------------------- unsafe region --------------------------> |
    //   |     |                                                                 |
    //   |  |<--->|  | <--------------- safe region ---------------> |           |
    //   |  |     |  |                                               |           |
    //   |1 ulp|1 ulp|                 |1 ulp|1 ulp|                 |1 ulp|1 ulp|
    //   |<--->|<--->|                 |<--->|<--->|                 |<--->|<--->|
    //   |-----|-----|-------...-------|-----|-----|-------...-------|-----|-----|
    //   |   minus   |                 |     v     |                 |   plus    | minus1     minus0           v - 1 ulp   v + 1 ulp           plus0       plus1
    //
    //
    // `minus` 之上的 `v` 和 `plus` 被量化为近似值 (误差 < 1 ulp)。
    // 因为我们不知道误差是正还是负，所以我们使用两个等距分布的近似值，并且最大误差为 2 ulps。
    //
    // "unsafe region" 是我们最初生成的自由区间。
    // "safe region" 是我们仅接受的保守区间。
    // 我们从不安全区域内的正确 repr 开始，然后尝试找到也在安全区域内与 `v` 最接近的 repr。
    // 如果不能，我们就放弃。
    //
    let plus1 = plus.f + 1;
    // let plus0 = plus.f - 1; // only for explanation
    //  let minus0 = minus.f + 1; // only for explanation
    let minus1 = minus.f - 1;
    let e = -plus.e as usize; // 共享指数

    // 将 `plus1` 分为整数部分和小数部分。
    // 由于精度要求，缓存的幂保证了 `plus < 2^32`，归一化的 `plus.f` 始终小于 `2^64 - 2^4`，因此保证了集成部件可以装入 u32。
    //
    let plus1int = (plus1 >> e) as u32;
    let plus1frac = plus1 & ((1 << e) - 1);

    // 计算最大的 `10^max_kappa` 不超过 `plus1` (因此 `plus1 < 10^(max_kappa+1)`)。
    // 这是下面的 `kappa` 的上限。
    let (max_kappa, max_ten_kappa) = max_pow10_no_more_than(plus1int);

    let mut i = 0;
    let exp = max_kappa as i16 - minusk + 1;

    // 定理 6.2: 如果 `k` 是最大整数 s.t。
    // `0 <= y mod 10^k <= y - x`，然后 `V = floor(y / 10^k) * 10^k` 在 `[x, y]` 中，并且是该范围内最短的表示之一 (具有最少的有效数字)。
    //
    //
    // 根据定理 6.2，找到 `(minus1, plus1)` 之间的数字长度 `kappa`。
    // 通过定理 6.2 可以通过要求 `y mod 10^k < y - x` 来排除 `x`。
    // (例如，`x` =32000，`y` =32777; `kappa` =2，因为 `y mod 10 ^ 3=777 <y-x=777`。) 该算法依赖于以后的验证阶段来排除 `y`。
    //
    let delta1 = plus1 - minus1;
    // let delta1int = (delta1 >> e) as usize; // only for explanation
    let delta1frac = delta1 & ((1 << e) - 1);

    // 渲染组成部分，同时检查每一步的准确性。
    let mut ten_kappa = max_ten_kappa; // 10^kappa
    let mut remainder = plus1int; // 尚未渲染的数字
    loop {
        // 我们总是有一个数字要渲染，作为 `plus1 >= 10^kappa` 不变量：
        // - `delta1int <= remainder < 10^(kappa+1)`
        // - `plus1int = d[0..n-1] * 10^(kappa+1) + remainder` (紧接着 `remainder = plus1int % 10^(kappa+1)`)
        //
        //

        // 将 `remainder` 除以 `10^kappa`。两者均按照 `2^-e` 缩放。
        let q = remainder / ten_kappa;
        let r = remainder % ten_kappa;
        debug_assert!(q < 10);
        buf[i] = MaybeUninit::new(b'0' + q as u8);
        i += 1;

        let plus1rem = ((r as u64) << e) + plus1frac; // == (plus1 % 10^kappa) * 2^e
        if plus1rem < delta1 {
            // `plus1 % 10^kappa < delta1 = plus1 - minus1`; 我们找到了正确的 `kappa`。
            let ten_kappa = (ten_kappa as u64) << e; // 将 10 ^ kappa 缩放回共享指数
            return round_and_weed(
                // SAFETY: 我们在上面初始化了该内存。
                unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..i]) },
                exp,
                plus1rem,
                delta1,
                plus1 - v.f,
                ten_kappa,
                1,
            );
        }

        // 绘制所有整数后，请中断循环。
        // 确切的位数是 `max_kappa + 1` 和 `plus1 < 10^(max_kappa+1)`。
        if i > max_kappa as usize {
            debug_assert_eq!(ten_kappa, 1);
            break;
        }

        // 恢复不变量
        ten_kappa /= 10;
        remainder = r;
    }

    // 渲染小数部分，同时检查每个步骤的准确性。
    // 这次我们依靠重复的乘法，因为除法将失去精度。
    let mut remainder = plus1frac;
    let mut threshold = delta1frac;
    let mut ulp = 1;
    loop {
        // 下一个数字应该是有效的，因为我们在分解不变量之前已经测试过了，其中 `m = max_kappa + 1` (整数部分的数字) ：
        //
        // - `remainder < 2^e`
        // - `plus1frac * 10^(n-m) = d[m..n-1] * 2^e + remainder`

        remainder *= 10; // 不会溢出，`2^e * 10 < 2^64`
        threshold *= 10;
        ulp *= 10;

        // 将 `remainder` 除以 `10^kappa`。
        // 两者都按 `2^e / 10^kappa` 缩放，因此后者在这里是隐式的。
        let q = remainder >> e;
        let r = remainder & ((1 << e) - 1);
        debug_assert!(q < 10);
        buf[i] = MaybeUninit::new(b'0' + q as u8);
        i += 1;

        if r < threshold {
            let ten_kappa = 1 << e; // 隐式除数
            return round_and_weed(
                // SAFETY: 我们在上面初始化了该内存。
                unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..i]) },
                exp,
                r,
                threshold,
                (plus1 - v.f) * ulp,
                ten_kappa,
                ulp,
            );
        }

        // 恢复不变量
        remainder = r;
    }

    // 我们已经生成了 `plus1` 的所有有效数字，但不确定是否是最佳数字。
    // 例如，如果 `minus1` 为 3.14153 ... `plus1` 是 3.14158 ...，从 3.14154 到 3.14158 有 5 种不同的最短表示形式，但我们只有最大的一种。
    // 我们必须连续减少最后一位并检查这是否是最佳代表。
    // 最多有 9 个候选人 (..1 到..9)，所以这相当快。("rounding" 阶段)
    //
    // 函数检查此 "optimal" repr 是否实际上在 ulp 范围内，并且由于舍入误差，"second-to-optimal" repr 实际上可能是最佳的。
    // 在这两种情况下，都将返回 `None`。
    // ("weeding" 阶段)
    //
    // 这里的所有参数均按公共 (但隐式) 值 `k` 进行缩放，以便：
    // - `remainder = (plus1 % 10^kappa) * k`
    // - `threshold = (plus1 - minus1) * k` (还有 `remainder < threshold`)
    // - `plus1v = (plus1 - v) * k` (以及来自先前不变量的 `threshold > plus1v`)
    // - `ten_kappa = 10^kappa * k`
    // - `ulp = 2^-e * k`
    //
    fn round_and_weed(
        buf: &mut [u8],
        exp: i16,
        remainder: u64,
        threshold: u64,
        plus1v: u64,
        ten_kappa: u64,
        ulp: u64,
    ) -> Option<(&[u8], i16)> {
        assert!(!buf.is_empty());

        // 在 1.5 ulps 内对 `v` (实际上是 `plus1 - v`) 产生两个近似值。
        // 结果表示应为两者最接近的表示。
        //
        // 这里使用 `plus1 - v` 是因为针对 `plus1` 进行了计算，以避免使用 overflow/underflow (因此，似乎交换了名称)。
        //
        let plus1v_down = plus1v + ulp; // plus1 - (v - 1 ulp)
        let plus1v_up = plus1v - ulp; // plus1 - (v + 1 ulp)

        // 减少最后一位数字，并停在最接近 `v + 1 ulp` 的位置。
        let mut plus1w = remainder; // plus1w(n) = plus1 - w(n)
        {
            let last = buf.last_mut().unwrap();

            // 我们使用的近似数字 `w(n)` 最初等于 `plus1 - plus1 % 10^kappa`。运行循环体 `n` 次后，`w(n) = plus1 - plus1 % 10^kappa - n * 10^kappa`。
            // 我们将 `plus1w(n) = plus1 - w(n) = plus1 % 10^kappa + n * 10^kappa` 设置为 (因此 `remainder= plus1w(0)`) 以简化检查。
            // 请注意，`plus1w(n)` 一直在增加。
            //
            // 我们有三个条件可以终止。它们中的任何一个都将使循环无法继续进行，但是无论如何我们至少拥有一个已知的最接近 `v + 1 ulp` 的有效表示形式。
            // 为了简便起见，我们将它们表示为 TC1 至 TC3。
            //
            // TC1: `w(n) <= v + 1 ulp`，即这是最接近的最后一个 repr。
            // 这等效于 `plus1 - w(n) = plus1w(n) >= plus1 - (v + 1 ulp) = plus1v_up`。
            // 与 TC2 (检查 `w(n+1)` 是否有效) 结合使用，可以防止 `plus1w(n)` 的计算可能出现溢出。
            //
            // TC2: `w(n+1) < minus1`，即下一个 repr 肯定不会四舍五入到 `v`。
            // 这等效于 `plus1 - w(n) + 10^kappa = plus1w(n) + 10^kappa > plus1 - minus1 = threshold`。
            // 左侧可能会溢出，但是我们知道 `threshold > plus1v`，所以如果 TC1 为 false，则 `threshold - plus1w(n) > threshold - (plus1v - 1 ulp) > 1 ulp`，我们可以安全地测试 `threshold - plus1w(n) < 10^kappa`。
            //
            //
            // TC3: `abs(w(n) - (v + 1 ulp)) <= abs(w(n+1) - (v + 1 ulp))`，即下一个 repr 不比当前 repr 更接近 `v + 1 ulp`。
            // 给定 `z(n) = plus1v_up - plus1w(n)`，则变为 `abs(z(n)) <= abs(z(n+1))`。再次假设 TC1 为 false，我们得到 `z(n) > 0`。我们有两种情况要考虑：
            //
            // - 当 `z(n+1) >= 0`: TC3 变为 `z(n) <= z(n+1)`。
            // 随着 `plus1w(n)` 的增加，`z(n)` 应该减少，这显然是错误的。
            // - 当 `z(n+1) < 0`：
            //   - TC3a: 前提是 `plus1v_up < plus1w(n) + 10^kappa`。假设 TC2 为 false，则为 `threshold >= plus1w(n) + 10^kappa`，因此它不会溢出。
            //   - TC3b: TC3 变成 `z(n) <= -z(n+1)`，即 `plus1v_up - plus1w(n) >= plus1w(n+1) - plus1v_up = plus1w(n) + 10^kappa - plus1v_up`。
            //   取反的 TC1 给出 `plus1v_up > plus1w(n)`，因此与 TC3a 结合使用时不会溢出或下溢。
            //
            // 因此，我们应该在 `TC1 || TC2 || (TC3a && TC3b)` 时停止。以下等于它的倒数 `!TC1 && !TC2 && (!TC3a || !TC3b)`。
            //
            //
            //
            //
            //
            //
            //
            //
            //
            //
            //
            //
            while plus1w < plus1v_up
                && threshold - plus1w >= ten_kappa
                && (plus1w + ten_kappa < plus1v_up
                    || plus1v_up - plus1w >= plus1w + ten_kappa - plus1v_up)
            {
                *last -= 1;
                debug_assert!(*last > b'0'); // 最短的代表不能以 `0` 结尾
                plus1w += ten_kappa;
            }
        }

        // 检查此表示形式是否也是最接近 `v - 1 ulp` 的表示形式。
        //
        // 这与 `v + 1 ulp` 的终止条件完全相同，所有 `plus1v_up` 都替换为 `plus1v_down`。
        // 溢出分析同样成立。
        if plus1w < plus1v_down
            && threshold - plus1w >= ten_kappa
            && (plus1w + ten_kappa < plus1v_down
                || plus1v_down - plus1w >= plus1w + ten_kappa - plus1v_down)
        {
            return None;
        }

        // 现在，我们在 `plus1` 和 `minus1` 之间具有最接近 `v` 的表示形式。
        // 但是，这太宽松了，因此我们拒绝 `plus0` 和 `minus0` 之间的任何 `w(n)`，即 `plus1 - plus1w(n) <= minus0` 或 `plus1 - plus1w(n) >= plus0`。
        // 我们利用 `threshold = plus1 - minus1` 和 `plus1 - plus0 = minus0 - minus1 = 2 ulp` 的事实。
        //
        if 2 * ulp <= plus1w && plus1w <= threshold - 4 * ulp { Some((buf, exp)) } else { None }
    }
}

/// 具有 Dragon 后备功能的 Grisu 的最短模式实现。
///
/// 在大多数情况下都应使用此方法。
pub fn format_shortest<'a>(
    d: &Decoded,
    buf: &'a mut [MaybeUninit<u8>],
) -> (/*digits*/ &'a [u8], /*exp*/ i16) {
    use crate::num::flt2dec::strategy::dragon::format_shortest as fallback;
    // SAFETY: 借用检查器不够智能，无法在第二个分支中使用 `buf`，因此我们在这里清洗生命周期。
    // 但是，只有在 `format_shortest_opt` 返回 `None` 的情况下，我们才重新使用 `buf`，所以可以。
    //
    match format_shortest_opt(d, unsafe { &mut *(buf as *mut _) }) {
        Some(ret) => ret,
        None => fallback(d, buf),
    }
}

/// Grisu 的确切和固定模式实现。
///
/// 否则，当返回不精确的表示形式时，它将返回 `None`。
pub fn format_exact_opt<'a>(
    d: &Decoded,
    buf: &'a mut [MaybeUninit<u8>],
    limit: i16,
) -> Option<(/*digits*/ &'a [u8], /*exp*/ i16)> {
    assert!(d.mant > 0);
    assert!(d.mant < (1 << 61)); // 我们至少需要三位额外的精度
    assert!(!buf.is_empty());

    // 归一化和缩放 `v`。
    let v = Fp { f: d.mant, e: d.exp }.normalize();
    let (minusk, cached) = cached_power(ALPHA - v.e - 64, GAMMA - v.e - 64);
    let v = v.mul(&cached);

    // 将 `v` 分为整数部分和小数部分。
    let e = -v.e as usize;
    let vint = (v.f >> e) as u32;
    let vfrac = v.f & ((1 << e) - 1);

    let requested_digits = buf.len();

    const POW10_UP_TO_9: [u32; 10] =
        [1, 10, 100, 1000, 10_000, 100_000, 1_000_000, 10_000_000, 100_000_000, 1_000_000_000];

    // 我们在这里偏离原始算法并进行一些早期检查以确定我们是否可以满足 requested_digits。
    // 如果我们确定我们不能，我们会提前退出并避免算法在其他情况下所做的大部分繁重工作。
    //
    // 当 vfrac 为零时，我们可以轻松确定 vint 是否可以满足要求的数字:
    //      如果 requested_digits >=11，则 vint 无法自行耗尽计数，因为 10^(11 -1) > u32 最大值 >= vint。
    //      如果 vint <10^(requested_digits-1)，则 vint 无法耗尽计数。
    //      否则，vint 可能会耗尽计数，我们需要执行剩余的代码。
    if (vfrac == 0) && ((requested_digits >= 11) || (vint < POW10_UP_TO_9[requested_digits - 1])) {
        return None;
    }

    // 旧 `v` 和新 `v` (由 `10^-k` 缩放) 的误差均小于 1 ulp (定理 5.1)。
    // 因为我们不知道误差是正还是负，所以我们使用两个等距的近似值，并且最大误差为 2 ulps (与最短的情况相同)。
    //
    //
    // 目的是找到 `v - 1 ulp` 和 `v + 1 ulp` 共有的精确四舍五入的数字序列，以便我们有最大的信心。
    // 如果无法做到这一点，我们不知道哪一个是 `v` 的正确输出，因此我们放弃并后退。
    //
    // `err` 在这里被定义为 `1 ulp * 2^e` (与 `vfrac` 中的 ulp 相同)，只要 `v` 被缩放，我们就会缩放它。
    //
    //
    //
    let mut err = 1;

    // 计算最大的 `10^max_kappa` 不超过 `v` (因此 `v < 10^(max_kappa+1)`)。
    // 这是下面的 `kappa` 的上限。
    let (max_kappa, max_ten_kappa) = max_pow10_no_more_than(vint);

    let mut i = 0;
    let exp = max_kappa as i16 - minusk + 1;

    // 如果使用的是最后一位数字的限制，则需要在实际渲染之前缩短缓冲区，以避免双舍入。
    //
    // 请注意，在进行舍入操作时，我们必须再次扩大缓冲区！
    let len = if exp <= limit {
        // 糟糕，我们甚至无法产生 *一位* 数字。
        // 例如，当我们有类似 9.5 的值并将其四舍五入时，这是可能的。
        //
        // 原则上，我们可以立即使用空缓冲区调用 `possibly_round`，但是将 `max_ten_kappa << e` 缩放 10 会导致溢出。
        //
        // 因此我们在这里很草率，错误范围扩大了 10 倍。
        // 这会增加假阴性率，但只会非常非常轻微地提高假阴性率；
        // 仅当尾数大于 60 位时才有意义。
        //
        // SAFETY: `len=0`，因此初始化此内存的义务微不足道。
        return unsafe {
            possibly_round(buf, 0, exp, limit, v.f / 10, (max_ten_kappa as u64) << e, err << e)
        };
    } else if ((exp as i32 - limit as i32) as usize) < buf.len() {
        (exp - limit) as usize
    } else {
        buf.len()
    };
    debug_assert!(len > 0);

    // 渲染不可分割的部分。
    // 该错误完全是零星的，因此我们无需在此部分中进行检查。
    let mut kappa = max_kappa as i16;
    let mut ten_kappa = max_ten_kappa; // 10^kappa
    let mut remainder = vint; // 尚未渲染的数字
    loop {
        // 我们总是至少有一位数字来表示不变量：
        // - `remainder < 10^(kappa+1)`
        // - `vint = d[0..n-1] * 10^(kappa+1) + remainder` (紧接着 `remainder = vint % 10^(kappa+1)`)
        //
        //

        // 将 `remainder` 除以 `10^kappa`。两者均按照 `2^-e` 缩放。
        let q = remainder / ten_kappa;
        let r = remainder % ten_kappa;
        debug_assert!(q < 10);
        buf[i] = MaybeUninit::new(b'0' + q as u8);
        i += 1;

        // 缓冲区是否已满？ 用余数运行舍入通行证。
        if i == len {
            let vrem = ((r as u64) << e) + vfrac; // == (v % 10^kappa) * 2^e
            // SAFETY: 我们已经将 `len` 初始化了很多字节。
            return unsafe {
                possibly_round(buf, len, exp, limit, vrem, (ten_kappa as u64) << e, err << e)
            };
        }

        // 绘制所有整数后，请中断循环。
        // 确切的位数是 `max_kappa + 1` 和 `plus1 < 10^(max_kappa+1)`。
        if i > max_kappa as usize {
            debug_assert_eq!(ten_kappa, 1);
            debug_assert_eq!(kappa, 0);
            break;
        }

        // 恢复不变量
        kappa -= 1;
        ten_kappa /= 10;
        remainder = r;
    }

    // 渲染小数部分。
    //
    // 原则上，我们可以继续到最后一个可用数字并检查准确性。
    // 不幸的是，我们正在使用有限大小的整数，因此我们需要一些标准来检测溢出。
    // V8 使用 `remainder > err`，当 `v - 1 ulp` 和 `v` 的第一个 `i` 有效数字不同时，它变为 false。
    // 但是，这会拒绝太多否则有效的输入。
    //
    // 由于后面的阶段具有正确的溢出检测功能，因此我们使用更严格的标准：
    // 我们继续直到 `err` 超过 `10^kappa / 2`，以便 `v - 1 ulp` 和 `v + 1 ulp` 之间的范围肯定包含两个或多个舍入表示形式。
    //
    // 对于引用，这与 `possibly_round` 的前两次比较相同。
    //
    let mut remainder = vfrac;
    let maxerr = 1 << (e - 1);
    while err < maxerr {
        // 不变量，其中 `m = max_kappa + 1` (整数部分的位数) ：
        // - `remainder < 2^e`
        // - `vfrac * 10^(n-m) = d[m..n-1] * 2^e + remainder`
        // - `err = 10^(n-m)`

        remainder *= 10; // 不会溢出，`2^e * 10 < 2^64`
        err *= 10; // 不会溢出，`err * 10 < 2^e * 5 < 2^64`

        // 将 `remainder` 除以 `10^kappa`。
        // 两者都按 `2^e / 10^kappa` 缩放，因此后者在这里是隐式的。
        let q = remainder >> e;
        let r = remainder & ((1 << e) - 1);
        debug_assert!(q < 10);
        buf[i] = MaybeUninit::new(b'0' + q as u8);
        i += 1;

        // 缓冲区是否已满？ 用余数运行舍入通行证。
        if i == len {
            // SAFETY: 我们已经将 `len` 初始化了很多字节。
            return unsafe { possibly_round(buf, len, exp, limit, r, 1 << e, err) };
        }

        // 恢复不变量
        remainder = r;
    }

    // 进一步的计算是没有用的 (`possibly_round` 肯定会失败)，所以我们放弃了。
    return None;

    // 我们已经生成了所有要求的 `v` 数字，这些数字也应该与 `v - 1 ulp` 的相应数字相同。
    // 现在，我们检查 `v - 1 ulp` 和 `v + 1 ulp` 是否共享唯一的表示形式； 这可以与生成的数字相同，也可以与这些数字的四舍五入形式相同。
    //
    // 如果范围包含相同长度的多个表示形式，则不能确定，应返回 `None`。
    //
    // 这里的所有参数均按公共 (但隐式) 值 `k` 进行缩放，以便：
    // - `remainder = (v % 10^kappa) * k`
    // - `ten_kappa = 10^kappa * k`
    // - `ulp = 2^-e * k`
    //
    // SAFETY: `buf` 的前 `len` 字节必须初始化。
    //
    unsafe fn possibly_round(
        buf: &mut [MaybeUninit<u8>],
        mut len: usize,
        mut exp: i16,
        limit: i16,
        remainder: u64,
        ten_kappa: u64,
        ulp: u64,
    ) -> Option<(&[u8], i16)> {
        debug_assert!(remainder < ten_kappa);

        // 10^kappa
        //    :   :   :<->:   :
        //    :   :   :   :   :
        //    :|1 ulp|1 ulp|  :
        //    :|<--->|<--->|  :
        // ----|-----|-----|----
        //     |     v     | v - 1 ulp   v + 1 ulp
        //
        // (对于引用，虚线表示在给定数字位数下可能表示的确切值。)
        //
        //
        // 错误太大，以至于 `v - 1 ulp` 和 `v + 1 ulp` 之间至少存在三种可能的表示形式。
        // 我们无法确定哪一个是正确的。
        //
        if ulp >= ten_kappa {
            return None;
        }

        // 10^kappa
        //   :<------->:
        //   :         :
        //   : |1 ulp|1 ulp|
        //   : |<--->|<--->|
        // ----|-----|-----|----
        //     |     v     | v - 1 ulp   v + 1 ulp
        //
        // 实际上，1/2 ulp 足以引入两种可能的表示形式。
        // (请记住，对于 `v - 1 ulp` 和 `v + 1 ulp`，我们都需要一个唯一的表示形式。) 这不会溢出，因为从第一次检查起就是 `ulp < ten_kappa`。
        //
        //
        if ten_kappa - ulp <= ulp {
            return None;
        }

        // remainder
        //       :<->|                           :
        //       :   |                           :
        //       :<--------- 10^kappa ---------->:
        //     | :   |                           :
        //     |1 ulp|1 ulp|                     :
        //     |<--->|<--->|                     :
        // ----|-----|-----|------------------------
        //     |     v     | v - 1 ulp   v + 1 ulp
        //
        // 如果 `v + 1 ulp` 更接近四舍五入的表示形式 (已经存在于 `buf` 中)，那么我们可以安全地返回。
        // 请注意，`v - 1 ulp` 可以小于当前表示形式，但是作为 `1 ulp < 10^kappa / 2`，此条件就足够了：
        // `v - 1 ulp` 和当前表示之间的距离不能超过 `10^kappa / 2`。
        //
        // 条件等于 `remainder + ulp < 10^kappa / 2`。
        // 由于这很容易溢出，因此请首先检查 `remainder < 10^kappa / 2`。
        // 我们已经验证了 `ulp < 10^kappa / 2`，因此只要 `10^kappa` 毕竟没有溢出，第二次检查就可以了。
        //
        //
        //
        //
        if ten_kappa - remainder > remainder && ten_kappa - 2 * remainder >= 2 * ulp {
            // SAFETY: 我们的调用者初始化了该内存。
            return Some((unsafe { MaybeUninit::slice_assume_init_ref(&buf[..len]) }, exp));
        }

        // :<------- remainder ------>|   :
        //   :                          |   :
        //   :<--------- 10^kappa --------->:
        //   :                    |     |   : |
        //   :                    |1 ulp|1 ulp|
        //   :                    |<--->|<--->|
        // -----------------------|-----|-----|-----
        //                        |     v     | v - 1 ulp   v + 1 ulp
        //
        // 另一方面，如果 `v - 1 ulp` 更接近于四舍五入的表示形式，我们应该四舍五入并返回。
        // 出于同样的原因，我们不需要检查 `v + 1 ulp`。
        //
        // 条件等于 `remainder - ulp >= 10^kappa / 2`。
        // 再次，我们首先检查是否为 `remainder > ulp` (请注意，这不是 `remainder >= ulp`，因为 `10^kappa` 永远不会为零)。
        //
        // 还请注意 `remainder - ulp <= 10^kappa`，因此第二次检查不会溢出。
        //
        if remainder > ulp && ten_kappa - (remainder - ulp) <= remainder - ulp {
            if let Some(c) =
                // SAFETY: 我们的调用者必须已初始化该内存。
                round_up(unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..len]) })
            {
                // 仅在要求我们提供固定精度时才添加一个额外的数字。
                // 我们还需要检查一下，如果原始缓冲区为空，则只能在 `exp == limit` (edge 情况) 下添加附加数字。
                //
                exp += 1;
                if exp > limit && len < buf.len() {
                    buf[len] = MaybeUninit::new(c);
                    len += 1;
                }
            }
            // SAFETY: 我们和调用者初始化了该内存。
            return Some((unsafe { MaybeUninit::slice_assume_init_ref(&buf[..len]) }, exp));
        }

        // 否则，我们注定要失败 (即，`v - 1 ulp` 和 `v + 1 ulp` 之间的一些值四舍五入，而其他值则四舍五入) 并放弃。
        //
        None
    }
}

/// 具有 Dragon 后备功能的 Grisu 的精确和固定模式实现。
///
/// 在大多数情况下都应使用此方法。
pub fn format_exact<'a>(
    d: &Decoded,
    buf: &'a mut [MaybeUninit<u8>],
    limit: i16,
) -> (/*digits*/ &'a [u8], /*exp*/ i16) {
    use crate::num::flt2dec::strategy::dragon::format_exact as fallback;
    // SAFETY: 借用检查器不够智能，无法在第二个分支中使用 `buf`，因此我们在这里清洗生命周期。
    // 但是，只有在 `format_exact_opt` 返回 `None` 的情况下，我们才重新使用 `buf`，所以可以。
    //
    match format_exact_opt(d, unsafe { &mut *(buf as *mut _) }, limit) {
        Some(ret) => ret,
        None => fallback(d, buf, limit),
    }
}