'trunc' rounding behaviour does not match documentation

[rkrajnc]

When using negative numbers with 'trunc' rounding mode, rounding produces results that don't match the documentation in this part:

In short, the fractional part of the signed number x that is not supported, is discarded.

Example code:

from fxpmath import Fxp

FXP_FMT_IN  = Fxp(None, signed=True, n_word=24, n_frac=21, rounding="trunc", overflow="wrap")
FXP_FMT_OUT = Fxp(None, signed=True, n_word=12, n_frac=11, rounding="trunc", overflow="wrap")

raw_val = -2095500 #0xe00674
fxp_val = Fxp(raw_val, raw=True, like=FXP_FMT_IN)

out_raw_val = raw_val >> 10
out_fxp_val = fxp_val.like(FXP_FMT_OUT)

out_raw_val and out_fxp_val.raw() should be the same, but are not.

I suggest removing the quoted statement from the documentation.

[daniel-pg-hwit]

No.

fxp-s24/21(-0.9992122650146484...)
= -2095500 / 2^21
= −2046.38671875 / 2^11
(fractional part of the signed number x that is not supported is discarded)
≈ -2046 / 2^11
= fxp-s12/11(-0.9990234375)

Truncation is the same as rounding toward zero (or rounding away from infinity).
The behavior you described is the floor rounding: floor(−2046.38671875) = -2047
Shifting an integer (signed or unsigned) to the right always results in a division by a power of two rounded down to the largest integer that's smaller than it.

[rkrajnc]

Yes,

the documentation mentions that "the fractional part of the signed number x that is not supported, is discarded", but that is not what happens, that is true for floor, but not trunc.

If you look at my code, the right shift produces -2047, which I consider "discarding unused bits". The trunc rounding produces -2046, and floor rounding produces -2047.

Maybe you didn't understand my issue correctly.

The only issue is the statement in the documentation, the code works OK. Anyway, it's such a small thing, not even worth opening an issue for it. The only reason I did is I used some other FP library for some other language, where the "trunc" rounding was actually implemented as floor in fxpmath, and because of that statement in the documentation I thought fxpmath works the same (wrong?) way.

[daniel-pg-hwit]

Thanks for the follow-up.

I understand your concern, but I believe the documentation is actually correct, and the behavior you're seeing is consistent with the mathematical definition of truncation.

When we talk about rounding methods like truncation, we're referring to how a numerical value —not its bit representation— is interpreted and transformed. Truncation means discarding the fractional part of the number, which is equivalent to rounding toward zero. So for example:

trunc(-2046.3867) → -2046

floor(-2046.3867) → -2047

Your example suggests that trunc produced -2048, but that would be incorrect; trunc should and does yield -2046. I suspect there might have been a typo.

It's true that the word "truncation" might suggest a bit-level operation, but in numerical computing, truncation refers specifically to discarding the fractional value, not dropping bits—this is an important distinction with a precise mathematical meaning. Most fixed-point libraries follow this convention, including fxpmath and MATLAB’s Fixed-Point Toolbox.

As for the discrepancy you saw with another library, it sounds like that implementation may have interpreted truncation as floor, which is non-standard and can definitely lead to confusion, so your reaction is understandable.

That said, I do agree the documentation could be improved. The phrase "fractional part of the signed number x that is not supported" is weirdly worded, particularly the use of "supported," which doesn’t have a clear mathematical meaning in this context. Rewording or removing it would probably make the intent clearer.

[rkrajnc]

I fixed the -2048 error in my comment, I meant -2046, sorry about that.

You are right about the usual mathematical meaning of truncation, but this is a fixed point library, where I would assume bit representations would matter ... more, I guess?

You can't really apply mathematical definition to truncation as implemented in fxpmath, as you aren't always 'rounding' all the fractional bits - that is, converting to pure integers. You can just discard one fractional bit of many, like for example 'rounding' s1.16 format to s1.15.

[daniel-pg-hwit]

You're right that rounding between formats can involve partial precision loss rather than full conversion to integers. But even then, rounding modes like trunc still operate on the numerical value, not directly on the bit pattern. The mathematical definition applies because you're effectively discarding the part of the value that cannot be represented at the new precision—whether that's all fractional bits or just the lower ones. So even with partial precision changes, trunc still means rounding toward zero in the numerical sense.

Appreciate the nudge on the documentation wording, it's a good reminder that even well-established conventions should be stated clearly and unambiguously, especially when people come to the topic with different backgrounds.