lua-users home
lua-l archive

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

On 07/11/2006, at 8:11 AM, Shmuel Zeigerman wrote:

API *is* the manual. The manual (not the source code!) is the only definitive authority with regards to the API. What you suggest is not rewording, it is *change*, since number of matches and number of substitutions are totally different things.

Hmm, I see what you mean, however if I may suggest, the only thing that *can* change is the manual (the documentation). Lua 5.1.1 is released and therefore cannot change, however any mis-descriptions of its behaviour can be clarified, at least in the online version of the manual.

Also, you might argue that the API is the actual behaviour of the source, which the manual attempts to describe. Sometimes an English description does not do full justice to the behaviour of the code (eg. does the word "replace" really mean "replace by a different thing").

I suggest that changing the behaviour of the code is more likely to break things than clearing up the documentation of what is actually happening. For example, people may be doing this:

_, count = string.gsub ("a a a a", " ", "")  -- count spaces
print (count) --> 3

Now the reference manual actually suggests (something like) this:

_, count = string.gsub ("a a a a", " ", " ")  -- count spaces
print (count) --> 3

However even here you could argue that we haven't really made a replacement, as "replacing" implies substitution by something different - although this is a debatable point. :)

I think you would find that someone who wanted to code something to, for example, count vowels, would write this:

_, count = string.gsub ("the quick brown fox", "[aeiou]", "") -- count vowels

And not this, which is longer and one would assume, slower:

_, count = string.gsub ("the quick brown fox", "[aeiou]", "%1") -- count vowels

Especially, as we are discarding the resulting string.

- Nick