RFE (reference manual): Documenting common Lua idiom t[#t+1]=value.

[Lorenzo Donati <lorenzo.donati.bz@...>]

Hi all!
When I began programming in Lua about one year ago, I used the reference 
manual as my primary source for learning. I was really surprised, after 
some months, reading the wiki and lurking on this list, to discover that 
the most common, efficient and simple way to append a value to an 
array-like table t was t[#t+1]=value! I had always used table.insert(t, 
value) instead.

This is so basic and common an operation that I think the manual should 
point it out (either in table.insert description or -better?- when 
describing tables) with something like:

"When a programmer only needs to append a value to an array-like table 
t, the most efficient way to do it is t[#t+1]=value. The library 
function table.insert should be used when there is a need to actually 
insert values in the middle of t or efficiency is not an issue."
(Of course a better rephrasing, maybe by a native English speaker, would 
be welcome :-)

I know that the manual shouldn't be a place where every idiom is spelled 
out, but this one is really _so widespread_  and the manual still 
reports many usage examples (e.g., in section 2.5.7 Table constructors - 
Lua 5.1.4).

Best Regards,
Lorenzo