use hdrsample::Histogram;
let mut hist = Histogram::<u64>::new_with_bounds(1, 60 * 60 * 1000, 2).unwrap();

// samples can be recorded using .record, which will error if the value is too small or large
hist.record(54321).expect("value 54321 should be in range");

// for ergonomics, samples can also be recorded with +=
// this call will panic if the value is out of range!
hist += 54321;

// if the code that generates the values is subject to Coordinated Omission,
// the self-correcting record method should be used instead.
// for example, if the expected sampling interval is 10 msec:
hist.record_correct(54321, 10).expect("value 54321 should be in range");

请注意 u64 类型。此类型可以被更改以减少所有直方图分桶的存储开销，但这会增加大量样本集中在同一桶中时饱和的风险。

查询样本

在任何时候，直方图都可以被查询以返回有趣的统计度量，例如记录的样本总数，或给定分位数的值。

use hdrsample::Histogram;
let hist = Histogram::<u64>::new(2).unwrap();
// ...
println!("# of samples: {}", hist.len());
println!("99.9'th percentile: {}", hist.value_at_quantile(0.999));

还提供了几个有用的迭代器，以便快速了解数据集的概览。最简单的一个是 iter_recorded()，它为每个非空样本桶生成一个项目。HdrSample 支持所有 HdrHistogram 迭代器，因此请查看 Java 文档 中的 *Iterator 类。

use hdrsample::Histogram;
let hist = Histogram::<u64>::new(2).unwrap();
// ...
for v in hist.iter_recorded() {
    println!("{}'th percentile of data is {} with {} samples",
        v.percentile(), v.value_iterated_to(), v.count_at_value());
}

恐慌和错误处理

只要您使用的是安全、非恐慌函数（见下文），则此库永远不会恐慌。您遇到的任何恐慌都是一个错误；请将其记录在问题跟踪器中。

一些函数的功能通过 AddAssign 和 SubAssign 实现公开。这些替代形式等同于简单地调用 unwrap() 正常函数，因此 unwrap() 的正常规则适用：在生产代码中使用时持怀疑态度等。

除了上述函数的恐慌形式外，其他所有操作在可以失败的情况下将返回 Result 或 Option。

usize 限制

根据配置的有效数字数量和最大值，直方图的内部存储可能有数百万个单元。16位 usize 系统无法表示这么大的指针偏移量，因此相关操作（创建、反序列化等）将因适当的错误而失败（例如，CreationError::UsizeTypeTooSmall）。如果您使用此类系统并遇到这些错误，减少有效数字的数量将大大减少内存消耗（因此需要较大的 usize 值）。只要禁用调整大小，降低最大值也可能有所帮助。

32位及以上的系统将不会有此类问题，因为所有可能的直方图都适合在32位索引中。

浮点精度

一些计算本质上是浮点值，例如 value_at_quantile，因此受IEEE754浮点计算精度的限制。用户可见的后果是，在某些边界情况下，你可能会得到一个比使用任意精度算术计算更高的或更低的桶（以及相应的值）。然而，双精度IEEE754（即 f64）在它的任务上做得非常好，因此这些情况应该是很少见的。此外，我们还没有看到超过一个桶的偏差情况。

为了最小化浮点精度损失，我们更倾向于使用分位数而不是百分比。分位数表示一个集合的一部分，用 [0, 1] 中的数字表示。百分比与分位数概念相同，只是它使用范围 [0, 100]。仅使用分位数意味着我们可以在几个地方跳过一个浮点操作，从而避免精度损失的机会。