`GetRandomInt` not swapping argument values

[WaterKnight]

There is this note on GetRandomInt:

@note If lowBound > highBound then it just swaps the values. https://github.com/lep/jassdoc/blob/e0ae9a48607b54290f8c57f1d8958a1ca69fad7e/common.j#L17280C1-L17280C61

I could not confirm this in a recent version (1.36.1.21015) as pointed out here: https://github.com/lep/jassdoc/issues/151#issuecomment-2143869913

Rather, it seems similar to how GetRandomReal behaves.

[lep]

Indeed. Added in 38ae32affacb91bbb0e553fe90c2f4b5ab3e34a0. Maybe it woul be worthwhile to point out the patch this change happened because i'm quite certain it didn't happen in older patches. Also to me i would think that GetRandomInt is the more often use function so it might be better to have the "main" documentation on GetRandomInt instead of GetRandomReal but it's fine either way.

[Luashine]

I don't have access to my game version library at the moment. Maybe the behavior didn't change and the initial note was wrong? Please keep this open and I will check it some time down the line.

[shuen4]

scope test initializer init
private function onTimer takes nothing returns nothing
    call SetRandomSeed(0)
    call BJDebugMsg(I2S(GetRandomInt(-10, 10)))
    call SetRandomSeed(0)
    call BJDebugMsg(I2S(GetRandomInt(10, -10)))
endfunction
private function init takes nothing returns nothing
    call TimerStart(CreateTimer(), 1, false, function onTimer)
endfunction
endscope

print at war3 version

1.24.4.6387
1.26.0.6401
1.27.0.52240
1.28.5.7680
1.29.2.9208 Public Test
1.29.2.9231
1.30.1.10211
1.31.1.12164
1.32.10.18820
1.36.1.21015 SD
1.36.2.21230

[Luashine]

Yes the GetRandomReal's min/mid/max formula is mostly correct. For the -Int mid the game's calculation is the same as // 2 (integer division in Lua) or math.floor(mid) -- rounding towards -inf. Keep in mind the integer syntax is new to Lua, I left a comment about it below.

Except for the 0.5f error for mid values, it's correct to link to GetRandomReal.

There's another problem - and I didn't test the same for floats - if the minimum value is too low, then it will have an effect on the possible output values:

print(GetRandomInt(math.mininteger, math.maxinteger))
--> ALWAYS math.mininteger

See "Max output is offset when using extreme values" below. Personally I don't want to test these any more :/ nor any other extremes. So what can be added right now:

• new seeds for the GetRandomInt
• corrected min/mid/max formula
• note about extreme values, linking to this issue

PS: @shuen4 you tested too many versions 😅 it's safe to assume if it didn't change between 1.24 and 1.36 then it was not changed in between. The only other big changes could have been expected with TFT, but I doubt they changed many internals there... with the exception of simply adding more systems to the game. Rather you should assume the jassdoc descriptions to be incomplete ;)

Test formula for the 3 found seeds

function testFormulaInt()
	local testRInt = function (seed, low, high)
		SetRandomSeed(seed);
		return string.format("%.16f", GetRandomInt(low,high))
	end
	
	local reFormula = function(low, high)
		local min = low
		local mid
		local max = (low > high) and (2 * low - high) or high
		if low == high then
			mid = low
		elseif low < high then
			-- you can use math.floor rather than integer division
			mid = (low + high) // 2
		else -- low > high
			-- you can use math.floor rather than integer division
			mid = (low + -high) // 2 + low
		end
		
		return min, mid, max
	end
	
	local lowSeed = 14545
	local midSeed = 12772
	local highSeed = 72346
	
	print(string.format("%-10s | %-6s %-6s %-6s | %-6s %-6s %-6s",
		" / ",
		"wcMin", "wcMid", "wcHigh",
		"reMin", "reMid", "reMax"
	))
	
	for _, iters in pairs({
		{iterL = {-8, -7, 1}, iterH = {-2, 1, 1}},
		{iterL = {8, 7, -1}, iterH = {-2, 1, 1}},
		--[[{iterL = {-2, 1, 1}, iterH = {8, 7, -1}},
		{iterL = {-2, 1, 1}, iterH = {-8, -7, 1}},]]
	}) do
		local lMin, lMax, lStep = table.unpack(iters.iterL)
		local hMin, hMax, hStep = table.unpack(iters.iterH)
		for l = lMin, lMax, lStep do
			for h = hMin, hMax, hStep do
				local wc3min = testRInt(lowSeed, l, h)
				local wc3mid = testRInt(midSeed, l, h)
				local wc3max = testRInt(highSeed, l, h)
				
				local reMin, reMid, reMax = reFormula(l, h)
				print(string.format("%-5d, %-5d | %-7d %-7d %-7d | %-7.1f %-7.1f %-7.1f",
					l, h,
					wc3min, wc3mid, wc3max,
					reMin, reMid, reMax
				))
			end
		end
	end
end
testFormulaInt()

Find min/mid/high seeds for GetRandomInt

nextSeed = 0
seedSteps = 10000000
--[[ Steps must not be a scientific notation or the number becomes a float
and breaks the iterator, it goes on infinitely]]
function step()
	local newMax = nextSeed + seedSteps
	for i = nextSeed, newMax, 1 do
		local min, mid, max = -2^16-3333, 0, 2^16+3333
		SetRandomSeed(i)
		local r = GetRandomInt(min, max)
		if r == min or r == mid or r == max then
			print(string.format("Found seed: %-16d, yields: %-16d", i, r))
			newMax = i
			break
		end
	end
	nextSeed = newMax + 1
	print(string.format("...reached seed: %-16d", newMax))
end

--[[ Integer seeds ]]

--[[ minIntSeed = 14545 ]]
--[[ midIntSeed = 12772 ]]
--[[ highIntSeed = 72346 ]]

SetRandomSeed(14545); print(GetRandomInt(-2^10, 2^9)) -- -1024
SetRandomSeed(12772); print(GetRandomInt(-2^10, 2^9)) -- -1024;-256;512
SetRandomSeed(72346); print(GetRandomInt(-2^10, 2^9)) -- 512

SetRandomSeed(14545); print(GetRandomInt(0, -2^9))
SetRandomSeed(12772); print(GetRandomInt(0, -2^9)) -- 256
SetRandomSeed(72346); print(GetRandomInt(0, -2^9)) -- 512

Max output is offset when using extreme values

-- returns MAX; unless (min-max <= -4294967), then returns (max-SOME_NUMBER)
SetRandomSeed(10702187); print(GetRandomInt(-2^20, 4096))
SetRandomSeed(10702187); print(GetRandomInt(-4294966, 0)) --> 0

SetRandomSeed(10702187); print(GetRandomInt(-4294967, 0)) --> -1

SetRandomSeed(10702187); print(GetRandomInt(-4290871, 4096)) --> 4095

SetRandomSeed(10702187); print(GetRandomInt(-8589934, 0)) --> -2
SetRandomSeed(10702187); print(GetRandomInt(-12884901, 0)) --> -3
SetRandomSeed(10702187); print(GetRandomInt(-17179869, 0)) --> -4
SetRandomSeed(10702187); print(GetRandomInt(-21474836, 0)) --> -5
SetRandomSeed(10702187); print(GetRandomInt(-25769803, 0)) --> -6
SetRandomSeed(10702187); print(GetRandomInt(-30064771, 0)) --> -7
SetRandomSeed(10702187); print(GetRandomInt(-34359738, 0)) --> -8
SetRandomSeed(10702187); print(GetRandomInt(-38654705, 0)) --> -9
SetRandomSeed(10702187); print(GetRandomInt(-42949672, 0)) --> -10
SetRandomSeed(10702187); print(GetRandomInt(-47244640, 0)) --> -11

Code to find the next deviating value (keep calling step()):

nextMin = 0
stepsLimit = 10000000
lastFoundValue = nil
--[[ Steps must not be a scientific notation or the number becomes a float
and breaks the iterator, it goes on infinitely]]
function step()
	local stepsDone = 0
	local found = false
	repeat 
		local min = nextMin
		local max = 0
		SetRandomSeed(10702187)
		local r = GetRandomInt(min, max)
		
		if r ~= lastFoundValue then
			found = true
			
			print(string.format("Found limit: %-16d, yields: %-16d", min, r))
			
			lastFoundValue = r
		end
		
		if nextMin == math.mininteger then
			break
		end
		nextMin = nextMin - 1
		stepsDone = stepsDone + 1
	until found or stepsDone == stepsLimit
	
	print(string.format("...reached limit, nextMin: %-16d", nextMin))
end