lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


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