Re: Manual unclear on lua_tointegerx and lua_tounsignedx

[Roberto Ierusalimschy <roberto@...>]

> In the lua-5.0.3 draft manual (and previous editions), the documentations
> for these functions states:
> 
> "If isnum is not NULL, its referent is assigned a boolean value that
> indicates whether the operation succeeded."
> 
> However in the context of the rest of the description "succeeded" is
> ambiguous since default behaviours are specified for circumstances that
> might or might not be considered "failure".

Lua 5.3 (work) is different from Lua 5.2 and previous versions. In 5.2
we have this:

  Converts the Lua value at the given index to the signed integral type
  lua_Integer. The Lua value must be a number or a string convertible to
  a number (see §3.4.2); otherwise, lua_tointegerx returns 0.

  If the number is not an integer, it is truncated in some non-specified
  way.

  If isnum is not NULL, its referent is assigned a boolean value that
  indicates whether the operation succeeded.

Do we really have to explain that the value not being what it "must be"
means it did not succeeded (and vice versa)?


> I'm guessing the value not being
> a number or a string convertible to a number is definitely "failure" (or
> else lua_tonumberx has the same problem). But is not being an integer?

This is implied in the first line ("The value must be a number", not
"The value must be an integer"), and is better detailed in the second
line ("If the number is not an integer...").


For Lua 5.3, the documentation says this:

  Converts the Lua value at the given index to the signed integral type
  lua_Integer. The Lua value must be an integer, or a number or string
  convertible to an integer (see §3.4.2); otherwise, lua_tointegerx
  returns 0.

Again, if the value is not what it should be, the operation does not
succeed. Should we explain that? (The details of what is "convertible
to an integer" are explained in 3.4.2, as documented.)


> Also, in lua_tounsignedx ( in the 5.0.3 draft ):
> 
> "If the number is not an integer, it is rounded towards minus infinite
> (floor). If the result is outside the range of representable values, it is
> normalized to the module of its division by one more than the maximum
> representable value."
> 
> Sorry if my math is letting me down, but does this specify what happens if
> the value is negative?

Yes, it does (at least as well as for non-negative values).

-- Roberto