The terms "sequence", "list", etc in Lua 5.2.0 (beta-rc1)

[Dirk Laurie <dpl@...>]

1. The manual uses `sequence` as a precisely defined term, but the 
definition varies.  In the discussion of the table library, the
term `proper sequence` is also used.

> 2.1 – Values and Types
> ...
> We use the term sequence to denote a table where all integer keys 
> comprise the set {1..n} for some integer n, which is called the 
> length of the sequence (see §3.4.6). 

> 3.4.6 The Length Operator
> ...
> The length of a table t is only defined if the table is a sequence, 
> that is, all its numeric keys comprise the set {1..n} for some 
> integer n.  

Suggestion: change `numeric` and `integer` respectively to 
`positive integer`.


2. The documentation of the table library uses the overworked term 
`list` (used for other purposes elsewhere) and fails to specify the 
behaviour of table.insert for keys like -1000, 0 and 0.0001.  This 
omission may be deliberate, in anticipation of developments planned 
for a release later than Lua 5.2.  But in the meantime, the intention 
seems to be that the table functions give predictable results for tables 
with holes provided that the user has provided a __len metamethod, and 
it would be nice to have that property documented.

The following reformulation of §3.4.6, the second paragraph of §6.5,
and the desciptions of table.insert and table.remove, is an attempt 
to be more precise.  

~~~~
3.4.6 – The Length Operator

The length operator is denoted by the unary prefix operator #. The length 
of a string is its number of bytes (that is, the usual meaning of string 
length when each character is one byte).  This may, depending on locale,
differ from the number of characters displayed.

A program can modify the behavior of the length operator for any value but 
strings through the __len metamethod (see §2.4).

If the __len metamethod has been not been supplied, the length of a table
is only defined if the table is a sequence, that is, all its positive 
integer keys comprise the set {1..n} for some integer n. In that case, 
n is its length. Note that a table like

     {10, 20, nil, 40}

is not a sequence, because it has the key 4 but does not have the 
key 3. (So, there is no n such that the set {1..n} is equal to the set of 
numeric keys of that table.)  Note, however, that non-numeric keys do not 
interfere with whether a table is a sequence.

Depending on the implementation, the expression #t may return a value
even when the length of the table is undefined.  This value cannot
be relied on in any way.
~~~~

~~~~
Currently, all functions in the table library except table.pack
make use of the length operator (see §3.4.6).  Their behaviour is 
therefore only defined when the table `seq` either represents a 
sequence or has a `__len` metamethod, and the value `pos` is in 
the set `{1..#seq}`.  They all ignore non-numeric keys in tables 
given as arguments.
~~~~

~~~~
table.insert (seq, [pos,] value)

Inserts element `value` at position `pos` in `seq`, shifting up the 
elements at `pos,pos+1,...,#seq`.  `seq[#seq+1]` is overwritten even 
if it is not nil.  The default value for pos is `#seq+1`, so that a 
call to table.insert(seq,x) inserts x at the end of sequence seq. 
~~~~

~~~~
table.remove (seq [, pos])

Removes from seq the element at position `pos`, shifting down the elements 
at `pos+1,pos+2,...,#seq`.   Returns the value of the removed element. The
default value for `pos` is `#seq`, so that a call `table.remove(seq)` removes 
the last element of `seq`. 
~~~

Dirk