From 07dc20055a599811b6ae517467d6a75392e47a60 Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Sat, 30 Jun 2012 16:25:41 +0400 Subject: Tweak documentation for utils.make_sort_order and devel/prepare-save --- Lua API.html | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'Lua API.html') diff --git a/Lua API.html b/Lua API.html index 0496d7e5..2c9a6a8d 100644 --- a/Lua API.html +++ b/Lua API.html @@ -1571,14 +1571,14 @@ Returns nil if any of obj or indices is nil, or a numeric inde
Returns a lua sequence of numbers in start..end.
utils.make_sort_order(data, ordering)
-Computes an ordering of objects in data, as a table of integer +
Computes a sorted permutation of objects in data, as a table of integer indices into the data sequence. Uses data.n as input length if present.
The ordering argument is a sequence of ordering specs, represented as lua tables with following possible fields:
Computes comparison key from a data value. Not called on nil. +
Computes comparison key from input data value. Not called on nil. If omitted, the comparison key is the value itself.
If true, sort non-nil keys in descending order.
This function is used by the sort plugin.
+For every comparison during sorting the specs are applied in +order until an unambiguous decision is reached. Sorting is stable.
+Example of sorting a sequence by field foo:
+
+local spec = { key = function(v) return v.foo end }
+local order = utils.make_sort_order(data, { spec })
+local output = {}
+for i = 1,#order do output[i] = data[order[i]] end
+
+Separating the actual reordering of the sequence in this +way enables applying the same permutation to multiple arrays. +This function is used by the sort plugin.
utils.assign(tgt, src)
Does a recursive assignment of src into tgt. @@ -1728,6 +1739,8 @@ calls lua code to perform the actual ordering of list items.
are automatically used by the DFHack core as commands. The matching command name consists of the name of the file sans the extension. +If the first line of the script is a one-line comment, it is +used by the built-in ls and help commands.
NOTE: Scripts placed in subdirectories still can be accessed, but do not clutter the ls command list; thus it is preferred for obscure developer-oriented scripts and scripts used by tools. -- cgit v1.2.1