LÖVE

My take on it is that he's concerned that since the wiki uses "Number" everywhere, since 5.1 lua doesn't have an "Integer" type, people will think they can just pass (1/0) into it and it'll work...

I'm still voting for just writing Whole numbers only, next to vars on the wiki that shouldn't be given real numbers anyway; more people understand whole numbers than integers. (even though the latter would be 1 word shorter)

If LuaJIT had strong typing mechanism, that would help.

I'm not sure what you mean by "coercion", in this case,

I meant "implicit type conversion," something that's often frowned on. I was saying that the current state of Love documentation does not treat these "automatic conversions" (aka letting Love floor stuff for you) as something evil, like coercion or UB.

The mouse.setPosition example is evidence of that; even though the documentation never says what happens when the user passes a fractional value, we're left to assume that Love does something reasonable (like floor it) and that it's alright to do this.

but the coordinates are floored, there's still no (magic) interpolation. It just doesn't spit out garbage anymore.

Of course they're not interpolated. I don't understand either the OP being accused of assuming they were interpolated, or the addition of a message about them not being interpolated to the wiki, but those are what I was referring to when I said "half the time you probably don't care whether Love floors it, rounds it, interpolates it or whatever."

My take on it is that he's concerned that since the wiki uses "Number" everywhere, since 5.1 lua doesn't have an "Integer" type, people will think they can just pass (1/0) into it and it'll work...

I'm saying that people will think they can pass 1/2 and it will work. And they will think that, as long as the documentation remains as it is, and it will work, as long as any cases where it doesn't work are treated as bugs and fixed. The only thing I'd change about this, if anything, is being specific about what actually happens in the documentation, like saying "non-integer values will be floored," as I mentioned earlier.

I'm still voting for just writing Whole numbers only, next to vars on the wiki that shouldn't be given real numbers anyway; more people understand whole numbers than integers. (even though the latter would be 1 word shorter)

Why shouldn't they be given real numbers if Love floors them anyway? What's the point in flooring them in user code and flooring them again in Love? I'm still voting for wiki being explicit about any conversions it does and leaving user to decide.

airstruck wrote:I'm saying that people will think they can pass 1/2 and it will work. And they will think that, as long as the documentation remains as it is, and it will work, as long as any cases where it doesn't work are treated as bugs and fixed. The only thing I'd change about this, if anything, is being specific about what actually happens in the documentation, like saying "non-integer values will be floored," as I mentioned earlier.

airstruck wrote:Of course they're not interpolated. I don't understand either the OP being accused of assuming they were interpolated, or the addition of a message about them not being interpolated to the wiki, but those are what I was referring to when I said "half the time you probably don't care whether Love floors it, rounds it, interpolates it or whatever."

So the issue is, i wrote the wrong addenda there, right? In that case, i'll just edit myself to what i originally wanted to add.

airstruck wrote:Why shouldn't they be given real numbers if Love floors them anyway? What's the point in flooring them in user code and flooring them again in Love? I'm still voting for wiki being explicit about any conversions it does and leaving user to decide.

Whether or not löve fixes user's stupidity internally is imo moot; i mean, it could just raise an error saying you're stupid for wanting to use non-integer coordinates (in case of mouse position), or trying to access a non-integer position in a sound/imagedata (since again, that's another somewhat similar thing); but it doesn't. It internally rounds towards zero. Solves the problem without shining light on the users questions that they won't ask now.

In any case, all i meant before and still mean is the same thing you want; to be more explicit on the wiki about these things.
(Besides, saying that mouse coordinates are integers doesn't equal "you need to floor it yourself" if there's an addendum next to it stating that löve floors it anyway...though in certain cases, like font positioning, there were issues with internal flooring... but yeah, that was a fun specific case where real positioning can be useful...)

(Also also, i think the interpolation argument was for my somewhat side-track with sounddata samplepoint and imagedata pixel accessing...)

zorg wrote:Whether or not löve fixes user's stupidity internally is imo moot; i mean, it could just raise an error saying you're stupid for wanting to use non-integer coordinates (in case of mouse position)

I don't see how you can possibly call the user stupid for doing the exact same thing as the example code on that page. That's the whole reason I pointed that example out; it strongly suggests that it's perfectly alright and not at all stupid to pass in fractional values, even though it's not explicit about what exactly will happen.

There's a huge difference between throwing an error for stuff like that and doing something defensive like flooring non-integers. If it threw an error, it would make perfect sense to document it as only accepting integers. As it is, it doesn't make sense to document it as only accepting integers, or to recommend that users only pass integers, because it's specifically designed to safely allow fractional values.

airstruck wrote:I don't see how you can possibly call the user stupid for doing the exact same thing as the example code on that page.

It's a figure of speech, describing situation of users issuing invalid commands whereupon the underlying library has to rectify the problem. Wiki page not being 100% accurate is not part of this, it's not a hard official documentation which doesn't really exist even within the source comments. If you want solid data on how things work in this library, you browse the sources. Same as with Lua really. It's not exactly user-friendly but, as with most programmers, documentation is made as an afterthought, and people using the library are expected to browse the source code for detailed information, because otherwise they're left on a mercy of whatever scraps of interpretation are available outside of the source code, which is not even always correct - case in point, up until recently, pages describing some physics functions had wrong argument descriptions. You are, of course, always welcome to make an exhaustive and comprehensive manual.

Regarding fractional values remark, Lua doesn't naturally allows this. If you have an integer indexed array (table) and attempt to get a value halfway between any of the integers by indexing the array with a real number, you get nil.

raidho36 wrote:It's a figure of speech

No, "you're stupid" is not a figure of speech. "You're just muddying the waters" is a figure of speech. "That's a complete heap of horse manure" is a figure of speech. "You're stupid" is completely literal. Go ahead, say I'm just arguing semantics, but it's simply not true.

describing situation of users issuing invalid commands whereupon the underlying library has to rectify the problem.

Except that isn't the situation being discussed. The user is not "issuing invalid commands" when they're using the API exactly as described in the documentation and their code works as expected.

people using the library are expected to browse the source code for detailed information

Do you mean you expect them to browse the source code, or are you speaking for someone else? If you're speaking for someone else, can you cite your reference? I certainly don't expect Love users to do that, for a few reasons: I see no evidence that any significant portion of Love users do it now, I see plenty of evidence to the contrary, and I don't see any recommendation that they should do that posted anywhere prominently.

case in point, up until recently, pages describing some physics functions had wrong argument descriptions

Yes, the majority of the love.physics docs are (were?) woefully inaccurate. I definitely had to consult the source many times on love.physics. Even so, I don't think that's a reason to expect everyone else to do so; in fact love.physics doesn't seem to get nearly as much use as you'd expect it to, and the bad docs combined with general unwillingness to rake through Love source could easily be the culprit.

You are, of course, always welcome to make an exhaustive and comprehensive manual.

Thanks, but I don't intend to do so, and I don't believe I'd need your permission/invitation to do so if I were so inclined.

Regarding fractional values remark, Lua doesn't naturally allows this. If you have an integer indexed array (table) and attempt to get a value halfway between any of the integers by indexing the array with a real number, you get nil.

Completely irrelevant. Lua has a well-defined behavior for indexing tables with fractional numbers; it simply gives the value at that index (or nil if there isn't one). Love's defensive flooring behavior for values that need to be integers internally seems fairly consistent throughout the API, there's no reason users shouldn't expect it, "exploit" it, or whatever else you want to call it, and I don't believe there's any reason not to document it either.

Yes i'm calling the hypothetical users stupid because i expect darwinian law to not allow a parsnip near a computer, whether or not the latter is a potato. Figurative enough? (no offense)

...Aside from my unnatural levels of salt that i seem to have posessed for the last week or so, for whatever reasons (and that i don't personally enjoy at all), the only thing i still don't agree on is that i do believe people should be warned that even though the framework accepts fractional values, they WILL be converted/floored to integers, when the underlying implementation needs those kinds of values.

Telling the user that -under any other circumstances, e.g. other frameworks that won't hold your hand-, passing a function that works with whole numbers, a real number, will simply not work; whether the outcome is undefined behaviour, silent (and possibly wrong) conversion, or a plain old error that suspends the code.

Can we please keep it civil, without calling other users "stupid", or even "potatoes"? Thank you.

airstruck wrote:

describing situation of users issuing invalid commands whereupon the underlying library has to rectify the problem.

Except that isn't the situation being discussed. The user is not "issuing invalid commands" when they're using the API exactly as described in the documentation and their code works as expected.

I can see both sides here. I'm personally in favour of automatic flooring, but that can lead to unintuitive behaviour (getSample(x) == getSample(x+0.001) in most cases, but not all). In my opinion this is a "documentation problem" more so than a code problem. I wouldn't want it to error if I accidentally pass in 1.000001, but if it's documented as taking an integer I'd know that some arbitrary conversion will take place.

There's the interesting sidenote that lua's (C) API actively encourages this behaviour. It coerces everything by default.

raidho36 wrote:people using the library are expected to browse the source code for detailed information

I'm willing to accept the documentation isn't perfect. It isn't. But if all users need to look at the source code, something is horribly wrong. Love is meant to provide abstractions, not a blob of pre-existing code.

raidho36 wrote:You are, of course, always welcome to make an exhaustive and comprehensive manual.

As are you! Please contribute to the wiki! Make the wiki great again.

airstruck wrote:

raidho36 wrote:Regarding fractional values remark, Lua doesn't naturally allows this. If you have an integer indexed array (table) and attempt to get a value halfway between any of the integers by indexing the array with a real number, you get nil.

Completely irrelevant. Lua has a well-defined behavior for indexing tables with fractional numbers; it simply gives the value at that index (or nil if there isn't one). Love's defensive flooring behavior for values that need to be integers internally seems fairly consistent throughout the API, there's no reason users shouldn't expect it, "exploit" it, or whatever else you want to call it, and I don't believe there's any reason not to document it either.

There's a distinct difference here. Tables can contain (almost) arbitrary keys. So indeed, there can be no valid mapping that doesn't break down. If you map x[0.01] to x[0], what happens when I insert x[0.01]? Does it suddenly no longer refer to x[0]? And what happens if I add x[0.05]? On the other hand, there simply is no such thing as audio sample 3.5.

bartbes wrote:In my opinion this is a "documentation problem" more so than a code problem. I wouldn't want it to error if I accidentally pass in 1.000001, but if it's documented as taking an integer I'd know that some arbitrary conversion will take place.

I've updated the ImageData:getPixel wiki page to be explicit about the current behavior (rather than making a usage recommendation), and put a notice about the bug there. For functions that weren't affected by the bug, I believe adding something like "non-integer values are floored" should be enough to let the user make an informed decision based on their individual situation. If you want to be explicit, you can floor it yourself (or round it, etc.). If you feel like that's redundant or unnecessary and want to let Love floor it, you can leave it out.

I haven't updated any other pages yet, in case someone wants to improve on this one first, so it can be used as a template.