Swapped parameter behaviour for constrain is not obvious

[lesamouraipourpre]

The behaviour when the min_value and max_value parameters are swapped is non-obvious.

from adafruit_simplemath import constrain

print(constrain(-5, 0, 10))  # Outputs 0, as expected
print(constrain(5, 0, 10))  # Outputs 5, as expected
print(constrain(15, 0, 10))  # Outputs 10, as expected

print(constrain(-5, 10, 0))  # Outputs 10
print(constrain(5, 10, 0))  # Outputs 10
print(constrain(15, 10, 0))  # Outputs 10

I think it should either

• raise an exception if they are swapped
• auto-swap the values
• add an exception parameter defaulted to False, which will auto-swap if False and raise an exception if True

My personal preference is to auto-swap the value, because it 'just works'.

I can create a PR if there is a consensus reached.

[dhalbert]

The code in map_range() does this:

 if out_min <= out_max:
        return max(min(mapped, out_max), out_min)   # This line is what constrain() does now.
    return min(max(mapped, out_max), out_min)

This is the equivalent of your auto-swap, if my REPL testing is right. In fact, we could have map_range() call constrain() if we generalize constrain() as you suggest. I would not suggest either the exception or the extra-arg solution.

You could add this to your current PR.

[lesamouraipourpre]

 if out_min <= out_max:
        return max(min(mapped, out_max), out_min)   # This line is what constrain() does now.
    return min(max(mapped, out_max), out_min)

This is the equivalent of your auto-swap, if my REPL testing is right. In fact, we could have map_range() call constrain() if we generalize constrain() as you suggest. I would not suggest either the exception or the extra-arg solution.

You could add this to your current PR.

As it happens, I was planning to 'borrow' that code for the auto-swap.

I've been searching through a few other language implementations and they either 'have undefined behaviour' (including numpy.clip) or 'panic/exception'. But it feels most pythonic to 'just work'.

I will add and document this to the PR.