diff --git a/init.lua b/init.lua index 8d913f0..c1ea943 100644 --- a/init.lua +++ b/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,8 +61,8 @@ 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 diff --git a/readme.md b/readme.md index bde473c..df07f21 100644 --- a/readme.md +++ b/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. -- `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. -- `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. +**Geometry:** +- `intersect` - 2d intersection routines, a bit sparse at the moment - `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. diff --git a/stable_sort.lua b/sort.lua similarity index 69% rename from stable_sort.lua rename to sort.lua index 52b31da..bffa9e2 100644 --- a/stable_sort.lua +++ b/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 ---license as follows: +--this is based on code from Dirk Laurie and Steve Fisher, +--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) - if high - low <= sort_core.max_chunk_size then - sort_core._insertion_sort_impl(array, low, high, less) +function sort._merge_sort_impl(array, workspace, low, high, less) + if high - low <= sort.max_chunk_size then + 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_core._merge_sort_impl(array, workspace, middle + 1, high, less) - sort_core._merge(array, workspace, low, middle, high, less) + sort._merge_sort_impl(array, workspace, low, middle, less) + sort._merge_sort_impl(array, workspace, middle + 1, 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() - table.insertion_sort = sort_core.insertion_sort - table.stable_sort = sort_core.stable_sort - table.unstable_sort = sort_core.unstable_sort +function sort:export() + table.insertion_sort = sort.insertion_sort + table.stable_sort = sort.stable_sort + table.unstable_sort = sort.unstable_sort end -return sort_core +return sort