Editing Module:Buffer/doc (section)

==require'Module:Buffer'.__pairs==
[[#MBpairs|{{code|lang=lua|require'Module:Buffer'.__pairs( table, flag, ext )}}]]

Returns two values: an iterator function and the <code>table</code>. This is intended for use in the {{luaref|iterators|iterator form of|y}}&nbsp;<code>for</code>.

One distinctive feature of this pairs method is that it splits keys into two groups: {{luaref|number||y}}s and non-numbers. This indexes each group of keys in its own "map" object, traversed by its own iterator function{{--}}i.e, iterating both sets of keys requires two separate for loops. Numeric keys are served in an orderly fashion as with {{luaref|ipairs}} except that those which are negative, non-consecutive, and non-integer may be included. Moreover, this can find some keys paired with explicitly nil values.<ref group="example">Take a moment to look at the following tables ''X'' and ''Y'':
:{|style=width:50%
|{{#tag:syntaxhighlight|local X = { [5] = 5 }
local Y = { nil, nil, nil, nil, 5 }
|lang=lua}}
|}
These tables are indistinguishable to {{luaref|ipairs}} and {{luaref|pairs}} (ipairs iterates nothing and pairs yields only one key-value pair for either table).

While this module's __pairs method also gives only one pair for table ''X'', it loops all five explicitly declared indicies for table ''Y'', as shown in the console input below with Module:Buffer as ''p'':
:{|style=width:50%
|{{#tag:syntaxhighlight|for k, v in p.__pairs{ [5] {{=}} 5 } do mw.log(k, v) end
5	5
for k, v in p.__pairs{ nil, nil, nil, nil, 5 } do mw.log(k, v) end
1	nil
2	nil
3	nil
4	nil
5	5|lang=lua}}
|}</ref>

The <code>flag</code> argument selects the iterator method returned for that loop. When ''flag'' is an explicit nil or omitted, this returns an iterator for number keys. If given any non-nil ''flag'' (i.e., false or any value that evaluates true), this returns a method for looping non-numeric keys. Because both sets are mapped at the same time, you may avoid a redundant mapping op in a subsequent loop by passing an explicit nil or false as ''flag''{{--}}i.e., omitting ''flag'' or passing true indicate that re-mapping is desired.

This automatically selects certain tables for "mapless" iteration. Typically, mapless differs from mapped only in that it uses fewer server resources, though, as explained in the next section on mapping, it may "miss" keys in some cases.

Mapping behavior may be modified or extended by <code>ext</code>. To disable mapless iteration for the table, you may pass false as ''ext''. If not nil or false, ''ext'' must be a pairs method that takes the table as its only argument and returns a function that may iterate its keys for mapping purposes. Note that re-mapping avoidance via ''flag'' does not apply if ''ext'' is explicitly given, though a nil ''ext'' does not disqualify a table from mapless iteration.
{{anchor|mapping}}

===Mapping process===
Tables are mapped in two stages.

The initial stage is a {{luaref|for|numerical for loop|y}} which inserts integers between {{code|lang=lua|1}} and {{code|lang=lua|#table}} in the number key map. Because nothing is checked in this step, this may map keys which the [[#Iterators|numeric map iterator]] would pair with nil values or with values from the table's {{luaref|Metatables|meta __index|y}}.

The second stage explores the table's keys with an {{luaref|iterators|iterative for loop|y}} and {{luaref|next|next, table}} as the default ''expression-list'', or, if ''ext'' evaluates true, the expression returned by {{code|lang=lua|ext( table )}}. This ignores keys already mapped in the first stage and checks if any unmapped key is a number before indexing it in the appropriate map group. Upon completion, if any new number key were found in the second stage, this runs the numeric map through {{luaref|table.sort||y}}. No order is imposed on the non-numeric map.

Alternatively, a table may qualify for "mapless" iteration if {{luaref|rawget|args=table, 1}} is not nil, and {{luaref|next|args=table, #table}} returns nil. If either ''flag'' or ''ext'' are not nil, or if the table was previously mapped, such permanently disqualifies a table for mapless processing.

As a side note, if mapless numeric iteration occurs, this returns {{code|lang=lua|iterator, table, nil}}. In other words, you may use {{luaref|select}} to confirm that the table qualifies for mapless iteration when it has a third explicit return (for debugging).

===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).