Skip to content

fix: assign a bare number to a decibel quantity as decibels - #436

Merged
nholthaus merged 1 commit into
mainfrom
fix/decibel-assignment-means-decibels
Oct 18, 2026
Merged

nholthaus merged 1 commit into
mainfrom
fix/decibel-assignment-means-decibels

Conversation

@nholthaus

@nholthaus nholthaus commented Sep 8, 2026 •

Copy link
Copy Markdown
Owner

Scalar assignment currently treats a bare number assigned to a decibel gain as a linear ratio. This makes gain = 100.0 produce 20 dB even though construction, scalar extraction, and scalar comparison use 100 dB. This change makes scalar assignment preserve the destination's numerical scale while retaining dimensionless normalization and typed quantity conversion.

Contract and evidence

The invariant is that scalar assignment agrees with the quantity's public scalar value and scalar comparison. It is not a blanket rule that assignment must equal scalar construction for every unit.

The existing discrepancy breaks ordinary generic code:

std::vector<decibels<double>> gains(1, 100.0); // constructs 100 dB
std::fill(gains.begin(), gains.end(), 100.0); // previously assigns 20 dB

After gain = 100.0, gain == 100.0 was false. Likewise, assigning static_cast<double>(gain) back to a 3 dB gain changed it to approximately 4.771 dB. These are observable value-contract failures, not just surprising internal storage.

std::assignable_from<decibels<double>&, double> passes the syntactic concept checks, but the old operation fails the semantic postcondition that the assigned object compares equal to the source. The compiler does not check that semantic requirement. See the assignment concept contract.

Decision and compatibility

The strongest alternative is to define every bare scalar assignment as a canonical linear dimensionless ratio. That interpretation is coherent in isolation and has a long history here: older code assigned directly into linearized storage, and the 2022 concentration-normalization change explicitly used a linear intermediate. Its age does not reconcile it with the rest of the public scalar interface.

Making assignment-as-linear-ratio agree with the public scalar value would instead require changing established scalar extraction and comparison semantics. Correcting assignment is the narrower correction and also agrees with existing decibel construction. This is an intentional behavior correction, with a real compatibility cost:

Expression Before After
gain = 100.0 20 dB 100 dB
gain = 0.0 zero linear gain, negative infinity dB unity linear gain, 0 dB
gain = -3.0 invalid negative linear gain, NaN dB -3 dB
gain = dimensionless<double>(100.0) 20 dB 20 dB
percentage = 0.5 50% 50%

Code that intends to assign a linear ratio should make that intent explicit:

gain = dimensionless<double>(ratio);

Typed quantities retain their physical meaning; their assignment overload and conversion path are unchanged.

Percent is the important boundary on the rule. percent<double>(0.5) constructs 0.5%, while assigning 0.5 produces 50%. That distinction is deliberate: percent's public scalar value/comparison is the normalized fraction, so its existing assignment already satisfies the chosen invariant. This change preserves the existing linear-scale normalization path.

Smallest implementation

Change one template argument in the existing scalar assignment operator: construct the canonical dimensionless intermediate with NumericalScale instead of hard-coded linear_scale. Keep the existing units::convert call to normalize the destination's conversion factor.

This uses the same general path for every scale. Assigning through the destination constructor directly would lose normalization for scaled dimensionless types. Branching on exact equality with linear_scale would also mishandle inherited linear scales. The tests cover both a logarithmic percent and an inherited linear percent to guard those boundaries. No new helper, branch, or public API is needed.

The scope is scalar assignment. There are broader existing mixed-type equality inconsistencies: a 3 dB quantity and a linear dimensionless quantity of 3 can each compare equal to the scalar 3 while comparing unequal to each other. This change does not claim to resolve the entire scalar interface; it corrects assignment without redesigning those contracts.

Validation

  • Positive, zero, and negative decibel assignment, plus explicit typed linear-ratio conversion.
  • Existing integral and floating-point dimensionless assignment coverage, and percent assignment from integral and floating-point inputs.
  • Custom logarithmic and inherited linear scale normalization.
  • The focused regressions fail on current main and distinguish the normalization regressions in the original proposal; they pass with this implementation.

Local validation of this revision:

  • GCC 13.4, C++23: 508/508 unit tests, including 27 Eigen interop tests with Eigen 3.4; all 12 CTest targets pass (unit suite, four lean configurations, and seven examples).
  • GCC 13.4 with UndefinedBehaviorSanitizer and recovery disabled: the same 508 unit tests and all 12 CTest targets pass without a sanitizer report.
  • Compile-pass/compile-fail diagnostic harness: 77/77 cases pass.
  • Focused assignment regressions: 3/3 pass with GCC 13.4 and Clang 23.1.3 using -Wall -Wconversion -Wshadow -Werror (third-party GoogleTest headers treated as system headers for Clang).
  • Generated reference documentation and built-in dimension consistency checks pass; git diff --check is clean.

Remote CI is reported separately by the checks on this PR.

Construct the canonical dimensionless scalar with the destination numerical scale before converting it. Decibel assignment then agrees with scalar value semantics while percent normalization and typed linear-ratio conversion retain their existing behavior.
@nholthaus
nholthaus force-pushed the fix/decibel-assignment-means-decibels branch from 7c19685 to 4b67938 Compare October 18, 2026 19:18
@nholthaus
nholthaus enabled auto-merge (squash) October 18, 2026 19:21
@nholthaus
nholthaus merged commit 3a7dd0f into main Oct 18, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant