stillwater-sc / universal / 30624996632

85%

master: 84%

push

github

docs(lns): document scale() int-truncation limit for wide configurations (#1274) (#1276)

* docs(lns): document scale() int-truncation limit for wide configurations (#1274)

scale() returns int by the library-wide convention (posit/cfloat/... all return
int), which is baked into the arithmetic engine (blocktriple/blocksignificand
consume int scale) and ~499 call sites. lns is the one type whose exponent field
(nbits-rbits-1 bits) can exceed int range, so scale() truncates for
astronomically wide configs (lns<64,11> ~ 2^52, lns<128,15> ~ 2^111).

Per the #1274 decision (document the limit rather than widen the library-wide
return type or forbid the wide configs, which are legitimately used e.g. in the
lns math library): add a doc note on lns::scale() explaining the limit and that
lns ARITHMETIC is unaffected (it operates on the full fixed-point exponent; only
this metadata accessor saturates). No behavior change.

Resolves #1274

* docs(lns): correct scale() limit wording per CodeRabbit (#1276 review)

Two doc-accuracy fixes on the #1274 note:
- "saturates" was wrong: operator int() keeps the low 64 bits and the C++20
  int64->int conversion reduces modulo 2^32 (well-defined wrap, not saturation).
- dropped the non-actionable "read the exponent field directly" guidance (_block
  is private and there is no public full-width exponent/scale accessor); state
  instead that wide configs currently have no public full-width scale() alternative.

Relates to #1274

1 of 1 new or added line in 1 file covered. (100.0%)

41671 of 48905 relevant lines covered (85.21%)

7268688.19 hits per line