 |
lua-l archive |
|
|
||
|
On 26/08/2011 15.13, Roberto Ierusalimschy wrote:
The manual doesn't say that non-acceptable indices should return NULL.In my opinion it does. "If the value at the given acceptable index is a full userdata, returns its block address. If the value is a light userdata, returns its pointer. Otherwise, returns NULL" This english compiles into pseudo-code if valid(index) and valueat(index) == userdata then return block address elseif valid(index) and valueat(index) == light userdata then return pointer else return NULL. So an invalid index returns NULL.Of course, being English a natural language, practically any sentence is subject to multiple interpretations. But I, as a non-native speaker, would read that sentence like this: "If the value at the given acceptable index is a full userdata, returns its block address. If the value [at the given acceptable index] is a light userdata, returns its pointer. Otherwise [that is, both cases are false: the value at the given acceptable index is neither a full userdata nor a light userdata], returns NULL."
Well, being in the same position as non-native-speaker, I must say that it wasn't so clear to me. I understood that acceptable/valid index thing because it is explained in another part of the manual, but in the individual descriptions those adjectives (valid/acceptable) get in the way.
After a while I got them as a reminder of the preconditions, but at first I had some doubts too. I.e. when you say here "the first case", in reality one may get the case as being:
"index is valid" AND "type is userdata"I would suggest, to emphasize that the acceptable/valid property is a precondition, to avoid using adjectives in the sentence describing the behaviour of the function. Instead you could put a short, schematic "preconditions" section in every description.
E.g.: lua_touserdata void *lua_touserdata (lua_State *L, int index); Preconditions: index is valid/acceptable.If the value at the given index is a full userdata, returns its block address. If the value is a light userdata, returns its pointer. Otherwise, returns NULL.
-- Roberto
-- Lorenzo