Table Sorting; Both arrays and dictionaries' keys or values

Module that fills all your sorting needs. :")
Note that it was only until completion that I’ve discovered that table.sort() exists.
Regardless, I believe that the module I am going to share would surpass table.sort() in terms of functionality as it features “deep sorting”.

Note: This project has been succeeded by here

Will no longer be pushing updates to this module, instead to the new one


  • Core functions are created and tested in vanilla Lua.
    • (Note that this lacks extensive testing within Roblox Studio, but generally should behave as expected since Roblox Studio runs on Lua and there are no discrepancies within arrays’ behaviors that I know of other than some metamethods.)
  • Speed.
    • I’ve tried my best to prevent from using built in functions such as math.max() etc as efficiency and speed is what I am trying to achieve.
    • Though table.insert() and table.remove() was unavoidable.
  • Ability to sort either the dictionaries’ values or keys and returns as arrays.
    • It is able to sort either the dictionary’s keys or its values.
    • Though when sorting through a dictionary, it will be returned as an array with the sorted elements as dictionaries are unordered, unlike arrays.
    • So it would be impossible to sort dictionaries.
  • Arrays passed as parameters won’t be changed within the module.
    • A new array with a new memory address will be returned.
    • Rest assured that no changes will be made to your initial array.
  • Deep sorting.
    • Relies on recursion to sort through all nested arrays.
  • Ability to deal with non numerical datatypes.
    • When dealing with non numerical datatypes, it will either be excluded or if IncludeNonSorted is set to True, it will be pushed to the back
    • Nested arrays are treated as a non numerical datatypes when using :Sort().
  • Features 3 sorting algorithms as of now, heap sort, insertion sort and bubble sort.

Read more on its features and API/how to use on the github repo here:

Grab the module here:


Creates and return a new SorterObj.


  • SorterObj

    A class object that handles parameters when sorting.

    => Methods


    • Sorts array x, will exclude non numeric datatypes, use Deep Sort to include arrays.
    • Only takes in 1 parameter.
    • No changes will be made to x within the module.
    • Skips nil, won’t be added into returned list regardless of IncludeNonSorted.


    • Sorts array x along with nested arrays.
    • Uses a recursive function to sort all of the numerical data within all of nested arrays.
    • All nested arrays would be pushed to the very back.
    • Won’t sort non numeric datatypes.
    • Only takes in 1 parameter.
    • No changes will be made to x within the module.
    • Skips nil, won’t be added into returned list regardless of IncludeNonSorted.
    • Does not support dictionary input.

    => Properties


    Datatype: number
    Default: 1
    Determines the sorting algorithm used.
    1 - Heap Sort; Without the Heap Property.
    2 - Insertion Sort
    3 - Bubble Sort


    Datatype: number
    Default: 5
    Determines the amount of times to retry when checking of ordered array fails.


    Datatype: boolean
    Default: true
    Determine whether to check the sorted array.
    Uses MaxRetries


    Datatype: boolean
    Default: true
    Whether to sort the given array in ascending order.


    Datatype: number
    Default: 1
    Type of table, 1 – array; 2 – dictionary.


    Datatype: boolean
    Default: false
    Only applicable when sorting a dictionary,
    Instead of sorting the values of the dictionary, it sorts the keys.


    Datatype: boolean
    Default: false
    When set to true, it will pack all of the non numerical datatypes from the given list at the very end of the returned list.

Sorting Stats

Took average time sorted from 100 samples.
Each list contained arbitrary numbers from -100 to 100.
Small List: 10 Items.
Medium List: 100 Items.
Big List: 1000 Items.

Algorithm 1; Heap Sort

  • Small List: 0.02533ms
  • Medium List: 0.67227ms
  • Big List: 57.64493ms

Algorithm 2; Insertion Sort

  • Small List: 0.01868ms
  • Medium List: 0.43559ms
  • Big List: 35.33016ms

Algorithm 3; Bubble Sort

  • Small List: 0.01749ms
  • Medium List: 0.62045ms
  • Big List: 59.63287ms

Code samples

  • Creating the Sorter Object
local sorter = require(script.Parent:WaitForChild("ModuleScript"))

SorterObj = -- get the sorter object
-- customise parameters
-- note: no need to assign them as they have default values
SorterObj.Ascending = true
SorterObj.Algorithm = 1
SorterObj.Type = 1

  • :Sort()
local array = {3, 1, 19, 15}
local sortedArray = SorterObj:Sort(array)
print(sortedArray) -- {1, 3, 15, 19}

SorterObj.Ascending = false
sortedArray = SorterObj:Sort(array)
print(sortedArray) -- {19, 15, 3, 1}

array = {3, "A", 19, "C", 5}
sortedArray = SorterObj:Sort(array)
print(sortedArray) -- {3, 5}

  • IncludeNonSorted
SorterObj.IncludeNonSorted = true

local array = {1, "test", 3, "B", 1, 3, 0} 
local sortedArray = SorterObj:Sort(array)
print(sortedArray) -- {0, 1, 1, 3, 3, "test", "B"}

array = {1, "test", {9, 4, 10}, "B", 8, 3}
sortedArray = SorterObh:Sort(array)
print(sortedArray) -- {1, 3, 8, "test", {9, 4, 10}, "B"}

  • :DeepSort()
SorterObj.Ascending = true
SorterObj.Algorithm = 1
SorterObj.Type = 1

local array = {1, 30, 41, 3, {3, 34, 1, 0, {5, 64, 10}}, {10, 31, 05, 10, 11}}
local sortedDeepArray = SorterObj:DeepSort(array)
print(sortedDeepArray) -- {1, 3, 30, 41, {0, 1, 3, 34, {5, 10, 64}}, {5, 10, 10, 11, 31}}
-- all nested arrays would be pushed to the very end in order

Error Codes

For your troubleshooting needs.
108 - Invalid SorterObj’s parameters.
350 - Not a fatal error, provided type property of SorterObj does not match the given table. Sorting will continue with the .Type property in SorterObj.
349 - SorterObj.Type is not a valid option.
801 - Amount of checks reached MaxRetries. Contact me if this happens.

Please note that this is the first time I am sharing something within community resources, thank you for your understanding.

Feedback would be most appreciated!
^ _ ^


I just want to say to people. This thing is super useful. I love using this for ordering my gui properly(etc). It has a bunch of built in methods that can be used.

1 Like

That really means a lot! <3
I do plan to release what I currently have, a few more algorithms with some cleaning up.
Though to me, I don’t see much use cases for this in games since this is somewhat only applicable on games that relies heavily on data.
It’s good learning opportunity for me either ways and for you to have benefitted from it seems not too shabby afterall.
Big thanks!

1 Like