Document expected behaviour of floor
ekscrypto opened this issue · 3 comments
The behaviour of how the floor impacts the output isn't really documented and the term itself brings confusion.
From https://en.wikipedia.org/wiki/Floor_and_ceiling_functions :
In mathematics and computer science, the floor function is the function that takes as input a real number x, and gives as output the greatest integer less than or equal to x.
Based on this definition, when I specified a step of 1024 with a floor of 897 and H28 of 1 I didn't expect to receive a value of 0x00000010000003a7 followed by 0x0000001000000728 and 0x0000001000000aa9; given that 0xAA9 is much higher than the "floor" value. It's obvious why this is happening when looking at the code where next() returns n / floor * floor.
The best that I can see is this is somehow useful in order to make it less obvious what the "step" actually is, using a Real number as step and benefiting from rounding to nearest Integer, causing the steps to be +/- 1. A floor > 1 is also a requirement when used with obfuscation to hide the obfuscation values used.
However the main issue is that I couldn't find any documentation about this expected behaviour, so as a user of this library I ended up having to dig through the code to figure it out.
Sorry for the confusion the minor feature had brought you.
I didn't expect anyone else other than a guy in my company to use or even notice the feature. That guy hoped to add a small number to each unique ID, which is some kind of object type. He hoped to recognize the type of an object with just a glance at an ID. Those types are defined in decimal and the ID numbers are also decimal in log messages.
The floor is expected to be 0, 10, 100 or 1000, not an arbitrary number like 897. Give a step of 1024, a floor of 1000 and an object type of 169, the 1st ID is floor(1024*1/1000)*1000+169=1169, the 2nd ID is floor(1024*2/1000)*1000+169=2169, the 3rd ID is floor(1024*3/1000)*1000+169=3169, and so on. You see, 169 is easy to recognize.
I know that floor is a bad name, but I'm not able to find a better one. Maybe you can :)
Maybe reservedDecimalDigits ? Provide a value between 0 and 3, then use it as 10^reservedDecimalDigits in the WithStep function, keep the logic the same elsewhere using a renamed variable name.
FYI the only reason I stumbled on this, is I'm currently working on a Swift implementation of WUID at https://github.com/ekscrypto/SwiftWUID
I've Swiftified the interfaces and it's still a work in progress. Based on our discussions I've updated the implementation and matching unit tests, below is a snapshot of the outcome so far:
