Re: string.gsub (Lua 5.1.1)

[Nick Gammon <nick@...>]

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