returning size values as int instead of unsigned
Probably more of a philosophical discussion.
Typically STL uses unsigned int for sizes to be returned by containers. Qt uses a different approach with returning signed numbers (e.g. qint64). bytesAvailable is one example. In general the differences of possible value dfo not play any role anymore. Personally, I appreciate the use of int instead of unsigned, since I tend to use most of the time int values.
However, at the day's end this leaves some uncertainty of returned values. Number of bytes one would clearly expect a return from 0 to anything above within limits of value definition. Unfortunately this is left open in documentation (e.g. bytesAvailable ). For clarity it would be better to add everywhere where in question.
Any other thoughts?
What are you not certain about? Is qint64 not clear enough?
Quoting the documentation:
This type is guaranteed to be 64-bit on all platforms supported by Qt.
That is safe, no question. However, it allows a negative value. That is the point. Certainly, it does not make sense to report number of bytes for instance with a negative number. However, at least theoretically it is possible (e.g. as substitute with a negative number in case of special conditions).
Therefore, it would be completely unambiguous when there was a statement in the documentation similar to "0 or always greater".
Unfortunately this is left open in documentation (e.g. bytesAvailable ). For clarity it would be better to add everywhere where in question.
That's reasonable. There's always room for improvement. Would you like to submit patches? (I don't think the signed integers are a big issue, so I don't want to pester the documentation team -- let them focus on more important stuff)
Thanks for response. You hit the point. That is also the reason I have started the discussion here instead of simply filing something on JIRA. The forum's lounge seem to be the better place.
To formulate a sentence or two for places I come across is probably the easiest part. Since I have not been involved in Qt stuff so far, I am a bit reluctant to state a simple yes. If it is limited to a couple of sentences and one or two emails without having understood the complete process, it would be yes.
On the other it is basically to get the ambiguity out of documentation and state what most will have to read between lines. However, it might have to be clarified as well, that the obvious is also what is implemented. Again not sure what procedures are in place.
I don't think the fix for this situation is sprinkling the docs with "is always greater than or equal to 0". I don't really think there is a doubt in someones head about whether or not a
lengthfunction returns negative value no matter if it's unsigned int, qint64 or size_t.
I think the opposite is more reasonable - document cases where it can actually return negative value and what it means, which Qt docs are doing pretty consistently (correct me if I'm wrong).