From 34d07b77ba7559c3fbaca1ff5e54f60b5f06d4c6 Mon Sep 17 00:00:00 2001 From: Achal Date: Sun, 22 Feb 2026 15:49:18 +0530 Subject: [PATCH] docs: document why map_to_index assumes value is not 0, inf, or NaN --- .../mapping/exponent_mapping.py | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/exponential_histogram/mapping/exponent_mapping.py b/opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/exponential_histogram/mapping/exponent_mapping.py index 297bb7a4831..ce8f8627bb1 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/exponential_histogram/mapping/exponent_mapping.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/exponential_histogram/mapping/exponent_mapping.py @@ -122,7 +122,24 @@ def map_to_index(self, value: float) -> int: # In summary, correction will be -1 if value is a power of 2, 0 if not. - # FIXME Document why we can assume value will not be 0, inf, or NaN. + # map_to_index requires value to be a finite, positive real number. + # 0, inf, and NaN violate this precondition. + + # Zero is represented in IEEE 754 with all exponent bits set to 0, + # giving get_ieee_754_exponent a result of -1023. Since -1023 is less + # than MIN_NORMAL_EXPONENT (-1022), zero is caught by the guard above + # and returned early. + + # Inf is represented in IEEE 754 with all 11 exponent bits set to 1 + # and a mantissa of 0, giving get_ieee_754_exponent a result of 1024 + # and correction a value of -1. + + # NaN is represented in IEEE 754 with all 11 exponent bits set to 1 + # and a non-zero mantissa of unspecified bit pattern, producing an + # unspecified correction value. + + # Inf and NaN are not caught by the guard above. Callers must ensure + # that only finite, positive values are passed to map_to_index. correction = (get_ieee_754_mantissa(value) - 1) >> MANTISSA_WIDTH return (exponent + correction) >> -self._scale