Add a clip_u31_to_q31

[christophe0606]

#66

clip_u31_to_q31 or clip_q32_to_q31 ... naming to be defined ...

[kjbracey]

Yes, naming's tricky, because it's not fully general like I said - it's specifically handling the values [0..0x80000000].

I think that's a common intermediate to end up with, so a commonly-needed clip, but I've got no idea what to call it either.

Have to make sure people don't accidentally use it for a wider range in the future.

[kjbracey]

How about q31_t clip_q31_abs_to_q31(uint32_t)?

Only issue is that's thinking of an instruction-set non-saturated "ABS" as opposed to "QABS", while "abs" normally means "QABS" throughout the library APIs.

[christophe0606]

I was thinking about clip_q32_to_q31 ? And only the positive q32 are representable in this case ...

[kjbracey]

That didn't make any sense to me at first, but now I see all the "clip" functions are of course not taking what they say they're taking. clip_q63_to_q31 doesn't actually take a q63_t ("64-bit fractional data type in 1.63 format"), it takes 33.31 format.

So by extension clip_q32_to_q31(uint32_t) would imply we're looking at the bottom 32 bits of a Q2.31 number, and we are assuming the missing bit is zero to get it to do what we want for 0x80000000. So the input could represent [0..2.0).

Okay, that works as an API naming, but my proposed fast-and-easy implementation would just turn 1.5 (0xC0000000) into 0xBFFFFFFF. It's only correct when you only have to worry about nudging +1.0 down to +1.0-lsb.

I guess you could have a more general implementation to handle any value. But not sure how often you're encountering inputs in the range [0..2.0) and not [0..1.0] to merit a more general implementation though.

(I haven't stopped to figure out if there is a fast general implementation. Maybe there is?)