[modified] renamed stable_sort.lua to sort.lua; swapped alias order

init.lua

@@ -20,7 +20,7 @@ local _batteries = {
 	tablex = require_relative("tablex"),
 	stringx = require_relative("stringx"),
 	--sorting routines
-	stable_sort = require_relative("stable_sort"),
+	sort = require_relative("sort"),
 	--
 	functional = require_relative("functional"),
 	--collections
@@ -43,7 +43,7 @@ for _, alias in ipairs({
 	{"mathx", "math"},
 	{"tablex", "table"},
 	{"stringx", "string"},
-	{"stable_sort", "sort"},
+	{"sort", "stable_sort"},
 	{"colour", "color"},
 }) do
 	_batteries[alias[2]] = _batteries[alias[1]]
@@ -61,7 +61,7 @@ function _batteries:export()
 	self.tablex.overlay(table, self.tablex)
 	--now we can use it through table directly
 	table.overlay(table, self.functional)
-	self.stable_sort:export()
+	self.sort:export()
 
 	--functional module also available separate from table
 	functional = self.functional

readme.md

@@ -10,22 +10,26 @@ Examples [in another repo](https://github.com/1bardesign/batteries-examples) to
 
 # Module Overview
 
-- `class` - Single-inheritance oo in a single function.
+**Lua Core Extensions:**
 - `mathx` - Mathematical extensions. Alias `math`.
 - `tablex` - Table handling extensions. Alias `table`.
 - `stringx` - String handling extensions. Alias `string`.
-- `stable_sort` - A stable sorting algorithm that is also, as a bonus, often faster than table.sort under luajit.
+**General Utility:**
+- `class` - Single-inheritance oo in a single function.
 - `functional` - Functional programming facilities. `map`, `reduce`, `any`, `match`, `minmax`, `mean`...
-- `sequence` - An oo wrapper on sequential tables, so you can do `t:insert(i, v)` instead of `table.insert(t, i, v)`. Also supports method chaining for the `functional` interface above, which can save a lot of typing!
+- `sequence` - An oo wrapper on sequential tables, so you can do `t:insert(i, v)` instead of `table.insert(t, i, v)`. Also supports method chaining for the `functional` interface above, which can save a lot of needless typing!
 - `set` - A set type supporting a full suite of set operations with fast membership testing and ipairs-style iteration.
+- `sort` - Provides a stable merge+insertion sorting algorithm that is also, as a bonus, often faster than `table.sort` under luajit. Also exposes `insertion_sort` if needed. Alias `stable_sort`
 - `state_machine` - Finite state machine implementation with state transitions and all the rest. Useful for game states, ai, cutscenes...
-- `async` - Async operations as coroutines.
+**Geometry:**
-- `manual_gc` - Get GC out of your update/draw calls. Useful when trying to get accurate profiling information; moves "randomness" of GC. Requires you to think a bit about your garbage budgets though.
+- `intersect` - 2d intersection routines, a bit sparse at the moment
-- `colour` - Colour conversion routines. Alias `color`.
-- `unique_mapping` - Generate a unique mapping from arbitrary lua values to numeric keys - essentially making up a consistent ordering for unordered data. Niche, but can be used to optimise draw batches for example, as you can't sort on textures without it.
 - `vec2` - 2d vectors with method chaining, garbage saving interface. A bit of a mouthful at times, but you get used to it.
 - `vec3` - 3d vectors as above.
-- `intersect` - 2d intersection routines, a bit sparse at the moment
+**Misc:**
+- `async` - Async operations as coroutines.
+- `colour` - Colour conversion routines. Alias `color`.
+- `manual_gc` - Get GC out of your update/draw calls. Useful when trying to get accurate profiling information; moves "randomness" of GC. Requires you to think a bit about your garbage budgets though.
+- `unique_mapping` - Generate a unique mapping from arbitrary lua values to numeric keys - essentially making up a consistent ordering for unordered data. Niche, but can be used to optimise draw batches for example, as you can't sort on textures without it.
 
 Aliases are provided at both the `batteries` level and globally when exported.
 

sort.lua

@@ -1,9 +1,9 @@
 --[[
-	stable sorting routines
+	various sorting routines
 ]]
 
---this is based on MIT licensed code from Dirk Laurie and Steve Fisher
+--this is based on code from Dirk Laurie and Steve Fisher,
---license as follows:
+--used under license as follows:
 
 --[[
 	Copyright © 2013 Dirk Laurie and Steve Fisher.
@@ -29,13 +29,13 @@
 
 -- (modifications by Max Cahill 2018, 2020)
 
-local sort_core = {}
+local sort = {}
 
 --tunable size for insertion sort "bottom out"
-sort_core.max_chunk_size = 32
+sort.max_chunk_size = 32
 
 --insertion sort on a section of array
-function sort_core._insertion_sort_impl(array, first, last, less)
+function sort._insertion_sort_impl(array, first, last, less)
 	for i = first + 1, last do
 		local k = first
 		local v = array[i]
@@ -52,7 +52,7 @@ function sort_core._insertion_sort_impl(array, first, last, less)
 end
 
 --merge sorted adjacent sections of array
-function sort_core._merge(array, workspace, low, middle, high, less)
+function sort._merge(array, workspace, low, middle, high, less)
 	local i, j, k
 	i = 1
 	-- copy first half of array to auxiliary array
@@ -85,14 +85,14 @@ function sort_core._merge(array, workspace, low, middle, high, less)
 end
 
 --implementation for the merge sort
-function sort_core._merge_sort_impl(array, workspace, low, high, less)
+function sort._merge_sort_impl(array, workspace, low, high, less)
-	if high - low <= sort_core.max_chunk_size then
+	if high - low <= sort.max_chunk_size then
-		sort_core._insertion_sort_impl(array, low, high, less)
+		sort._insertion_sort_impl(array, low, high, less)
 	else
 		local middle = math.floor((low + high) / 2)
-		sort_core._merge_sort_impl(array, workspace, low, middle, less)
+		sort._merge_sort_impl(array, workspace, low, middle, less)
-		sort_core._merge_sort_impl(array, workspace, middle + 1, high, less)
+		sort._merge_sort_impl(array, workspace, middle + 1, high, less)
-		sort_core._merge(array, workspace, low, middle, high, less)
+		sort._merge(array, workspace, low, middle, high, less)
 	end
 end
 
@@ -102,7 +102,7 @@ local function default_less(a, b)
 end
 
 --inline common setup stuff
-function sort_core._sort_setup(array, less)
+function sort._sort_setup(array, less)
 	--default less
 	less = less or default_less
 	--
@@ -119,36 +119,36 @@ function sort_core._sort_setup(array, less)
 	return trivial, n, less
 end
 
-function sort_core.stable_sort(array, less)
+function sort.stable_sort(array, less)
 	--setup
-	local trivial, n, less = sort_core._sort_setup(array, less)
+	local trivial, n, less = sort._sort_setup(array, less)
 	if not trivial then
 		--temp storage; allocate ahead of time
 		local workspace = {}
 		local middle = math.ceil(n / 2)
 		workspace[middle] = array[1]
 		--dive in
-		sort_core._merge_sort_impl( array, workspace, 1, n, less )
+		sort._merge_sort_impl( array, workspace, 1, n, less )
 	end
 	return array
 end
 
-function sort_core.insertion_sort(array, less)
+function sort.insertion_sort(array, less)
 	--setup
-	local trivial, n, less = sort_core._sort_setup(array, less)
+	local trivial, n, less = sort._sort_setup(array, less)
 	if not trivial then
-		sort_core._insertion_sort_impl(array, 1, n, less)
+		sort._insertion_sort_impl(array, 1, n, less)
 	end
 	return array
 end
 
-sort_core.unstable_sort = table.sort
+sort.unstable_sort = table.sort
 
 --export sort core to the global table module
-function sort_core:export()
+function sort:export()
-	table.insertion_sort = sort_core.insertion_sort
+	table.insertion_sort = sort.insertion_sort
-	table.stable_sort = sort_core.stable_sort
+	table.stable_sort = sort.stable_sort
-	table.unstable_sort = sort_core.unstable_sort
+	table.unstable_sort = sort.unstable_sort
 end
 
-return sort_core
+return sort