Allow `Random.number(10, 1)`, or throw?

[tabatkins]

Should we allow calls of the form Random.number(10, 1), in addition to the standard Random.number(1, 10)? In the most naive version of the method (return Random.random()*(b - a) + a), this Just Works automatically; the b-a term ends up negative and counts down from the (higher) a value, so you still cover the same range either way. (Modulo the edge values, possibly.)

I'm inclined to allow it.

[kgryte]

I would disallow this, so that it maps more directly to a uniform distribution with minimum support a and maximum support b. That is muddied if you allow swapping parameters (a) and (b) accounts for when b < a should be considered an error condition (e.g., when b is the result of some prior calculation). Additionally, it further depends on whether a and b are inclusive or exclusive. A typical parameterization is a is inclusive and b is exclusive. In this scenario, swapping parameters does not map to the same range.

[ljharb]

This would be repeating the mistake of substring imo, and we should not allow it.

[michaelficarra]

To me, this is asking to pull a random value from an empty set, which should throw.

[tabatkins]

I'm okay with throwing, tho at least Python does allow them to be misordered.

[WhosyVox]

It does seem odd to me that you might have the parameters in reverse order like that. In the worst case that's a bug, so throwing is probably the best choice.

If for some reason your code does need this behaviour, you can emulate it it pretty effectively with
Random.number( Math.min(a,b), Math.max(a,b) )

Though do we throw when low>high, or low>=high?

That is, what should the expected behaviour of say Random.number(1, 1) be?

[tabatkins]

at is, what should the expected behaviour of say Random.number(1, 1) be?

That depends solely on what our defined range is. If it's double-closed ([min, max]), then that's valid and just returns 1. If it's half-open or double-open ([min, max) or (min, max)) then it's an error, as there are no possible values to return.

[tabatkins]

Now that my ranges are defined as closed, and thus symmetrical, the core confusion from supporting "misordered" arguments is gone.

On the other hand, the step argument to several of the functions introduces an asymmetry in the treatment of the arguments, meaning that just swapping them when they're "out of order" isn't necessarily going to give you the same results: Random.int(10, 25, 10) generates two possible values (10 and 20), and you'd like Random.int(-10, -25, -10) to do the same but negative, but swapping to put them in the "correct order" gives Random.int(-25, -10, -10), which instead generates -25 and -15.

So I think it is best to go ahead and support arguments in either order.

[ljharb]

To me that seems like it's easy to make a mistake and get a different answer, which means we must throw an exception for whichever we decide is the "wrong" one.

[kgryte]

a) I don't see a good argument for a "step" parameter for generating a random integer when doing so without a step parameter is equivalent to randint( 1, 10 ) * step.

b) As I have mentioned elsewhere, I would keep the parameterization equivalent to a discrete uniform distribution with [min, max] parameterization. Otherwise, you force into userland the need add guards when min > max is not desired behavior.

[WhosyVox]

a) I don't see a good argument for a "step" parameter for generating a random integer when doing so without a step parameter is equivalent to randint( 1, 10 ) * step.

I'd like to add that I'm not a fan of the return signature changing when adding this extra step parameter.
But I think we should open another issue to discuss this further.

[tabatkins]

@WhosyVox

I'd like to add that I'm not a fan of the return signature changing when adding this extra step parameter.

I don't understand what you mean by this.

@ljharb

To me that seems like it's easy to make a mistake and get a different answer, which means we must throw an exception for whichever we decide is the "wrong" one.

What sort of mistake do you anticipate here?

@kgryte

a) I don't see a good argument for a "step" parameter for generating a random integer when doing so without a step parameter is equivalent to randint( 1, 10 ) * step.

"Generate an even number between 10 and 20" with a step parameter is trivial: Random.int(10, 20, 2). Without, you need to adjust both of the range endpoints, getting Random.int(5, 10) * 2, which doesn't obviously match the problem statement - where did the 5 and 10 come from? (Or worse, forcing someone to write Random.int(start/2, end/2) * 2, repeating the step value three times, because the endpoints come from variables.) And actually that's no good either, as the endpoints might not be even, so we have to write Random.int(Math.trunc(start/2), Math.trunc(end/2)) * 2 to avoid the potential of a thrown error. That's pretty nasty for such a simple and reasonable example!

And let's not even talk about "generate an odd number between 11 and 21"; Random.int(11, 21, 2) vs Random.int(5, 10)*2 + 1...

As a more general point, Random.int() is just convenient sugar for Random.number(a, b, 1), and we shouldn't diverge except when necessary. (There are some meaningful differences in the details, but nothing that affects this argument.) It would be weird if step was allowed for one but not the other, as long as it makes sense at all to have it apply to both.

b) As I have mentioned elsewhere, I would keep the parameterization equivalent to a discrete uniform distribution with [min, max] parameterization. Otherwise, you force into userland the need add guards when min > max is not desired behavior.

Userland has to add guards in either behavior, tho, if it doesn't match their intention: if Random.number(10, 0) is valid and you want to avoid that, you need to test for it and error; if Random.number(10, 0) is invalid and you want to avoid that, you need to either test for that and swap or manually use Math.min(10,0) and Math.max(10,0). I don't think either behavior is significantly more natural than the other such that we can judge one to be the obvious thing to support. (After all, clearly our intuitions about these behaviors are different.)

[WhosyVox]

I think I misunderstood the intent behind the last parameter. This does seem to make sense; I withdraw my earlier statement.

[kgryte]

That's pretty nasty for such a simple and reasonable example!

Do you have real-world use cases for, e.g., sampling even/odd integers using the approach you've outlined above? The typical approach here would be pulling a random sample from a fixed set of even numbers with replacement. While this requires materializing a sample, I personally don't see a need for having a dedicated API fulfilling the "step" use case. I'd be interested in seeing code samples from the wild.

Userland has to add guards in either behavior, tho, if it doesn't match their intention

Again, my point is about conventional means of parameterizing distributions. It is not common for unordered parameterization (see Julia, Python, NumPy, MATLAB, etc). I personally don't see a compelling reason for JavaScript to be unique in this regard, and I say this as someone who uses PRNGs on a daily basis while writing numerical and scientific software in JavaScript.

tho at least Python does allow them to be misordered.

I don't think this statement is correct, at least for random integers.

In [1]: import random

In [2]: random.randint(1,10)
Out[2]: 5

In [3]: random.randint(10,1)
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[3], line 1
----> 1 random.randint(10,1)

File ~/anaconda3/lib/python3.10/random.py:370, in Random.randint(self, a, b)
    366 def randint(self, a, b):
    367     """Return random integer in range [a, b], including both end points.
    368     """
--> 370     return self.randrange(a, b+1)

File ~/anaconda3/lib/python3.10/random.py:353, in Random.randrange(self, start, stop, step)
    351     if width > 0:
    352         return istart + self._randbelow(width)
--> 353     raise ValueError("empty range for randrange() (%d, %d, %d)" % (istart, istop, width))
    355 # Non-unit step argument supplied.
    356 if istep > 0:

ValueError: empty range for randrange() (10, 2, -8)

However, I see that you may have been inspired by Python's randrange function. Similar to Python, I would not conflate the APIs.

[tabatkins]

The typical approach here would be pulling a random sample from a fixed set of even numbers with replacement. While this requires materializing a sample, I personally don't see a need for having a dedicated API fulfilling the "step" use case. I'd be interested in seeing code samples from the wild.

It's the same that drove CSS's random() function API shape - it's very reasonable to only want randomness that lines up with a useful layout size increment in your design system. Completely random values can look too uneven and weird, but random heights that are 100px apart can look good. Random ints are also a specific instance of this (random number with a step of 1), albeit a quite special one that could be considered a special case.

But just in general, every range API in existence contains a step, and wanting to generate a random value that could come from a range seems obviously useful, and would be nice to do without having to materialize the range first.

I don't think this statement is correct, at least for random integers.

The docs are wrong, ugh. They claim randint() is just an alias for randrange() with the second value bumped up by 1. They do imply an ordering constraint, but that can just as well be read as a casual overstatement while trying to express the endpoint semantics. My bad.

---

Yeah, so I think it's really the interaction with step that's pulling me one way. Given that step is anchored to the first point, I think it would be weird/annoying if that meant it had to be anchored to the smaller point, and wanting steps that count down from some value required extra shenanigans to ensure that the smaller value was exactly a step multiple away. Note as well that Iterator.range(), as currently proposed, also allows the endpoints in either order, and automatically computes a +1 or -1 step accordingly. (And it does use a half-open range, so (1, 10) and (10, 1) give different answers even ignoring the order.) (But that automatic direction determination does differ from most languages.)

When step is specified, tho, there's already an implied direction anyway. If you wrote Random.number(10, 1, 1), that would at best only return 10; I think it's more reasonable to throw. (And Iterator.range agrees; it returns an empty iterator in this case.) But Random.number(10, 1, -1) needs to work, identically to Random.number(1, 10, 1).

So I guess I'm more agnostic about the behavior when step is omitted. There's no meaningful behavior difference, in that case, between (1, 10) and (10, 1), so requiring people to use Math.min()/max() when they don't know the ordering would be acceptable, I suppose.

My one complaint is that I'm not the happiest about the fact that negative numbers have a less obvious ordering. There's always some confusion about whether "smaller" means "closer to zero" or "closer to negative infinity", and the two give opposite answers here. We'd obviously match Math.min() and choose "closer to negative infinity", but still, it feels reasonable to write Random.number(-10, -25). But I could be okay with that being invalid.

[tabatkins]

Conclusion, after giving this some thought: The argument ordering has to match the sign of the step argument when specified, and when unspecified, we should default to a "positive" step (of an auto-calculated size, matching the larger float regime of the two endpoints, as outlined in the proposed algorithm).

So Random.number(10, 1) throws, but Random.number(10, 1, -1) will work as expected.