Editing Module:Buffer/doc (section)

===Iterators===
{{luaself|iterator|args=table, key}}

One of four functions may be provided in the ''{{luaref|iterators|expression-list|y}}'' returned by this pairs method, depending on which group of keys (numeric or non-numeric) and which iteration process (map-based or mapless) is indicated.

When <code>key</code> is nil or unspecified, map iterators will return the key object referenced by the first index of the relevant map along with the value it indexes. If passed the first mapped key, these iterators then return the second index mapped, which if passed in turn may retrieve the third and so on until the last mapped key has been served.

For numeric iteration, the mapless method returns {{code|lang=lua|1, table[1]}} when ''key'' is unspecified. If a ''key'' is given, it returns {{code|lang=lua|key + 1, table[ key + 1 ]}} unless ''key'' is greater or equal to the length of the table, upon which it returns nil. For non-numeric keys, the mapless "iterator" is actually a no-op (empty) function which takes nothing, does nothing, and returns nothing{{--}}provided only to prevent an error when the for loop expects a function.

As mentioned (using different words), key-value pairs are served independently of whether or not {{code|lang=lua|table[key]}} exists and retrieved without using {{luaref|rawget}}.

For example, take a look at table ''x'' as declared in the following statement: {{code|lang=lua|local x = {1,nil,nil,nil,nil,nil,nil,8}  }}. Table ''x'' has a length equal to 8. With ipairs, the for loop stops after the first pair. In contrast, this module's __pairs method will loop all 8 keys declared{{--}}i.e., (1, 1), (2, nil), ... (7, nil), (8, 8). That said, this only iterates two keys if table ''x'' were declared as {{code|lang=lua|{ 1, [8] = 8} }} instead even though such is indistinguishable to Finally, the loop would continue to include any keys set to nil after the mapping process.</ref>

You may assign these iterators to a local variable to use them directly. If an unmapped table is given to a map iterator, it will forward the table to this pairs method for immediate mapping. Though no map table is produced for the mapless iteration, the pairs method does cache the length of the table at a map reference, which the iterator compares against ''key'' to determine when to stop. Unlike the map methods, the mapless iterator does not call the pairs method when such has been bypassed and instead compares ''key'' to the value returned by the {{luaref|length operator||y}}, which may be unstable if the loop includes code that sets or unsets indicies within the table. Also, the mapless method will throw an error if given a table that has been mapped (when it attempts to compare ''key'' to a map object).