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.
