diff --git a/CHANGELOG.md b/CHANGELOG.md index eb90c9e..ea03b57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -85,10 +85,10 @@ * Cleanup code and documentation a bit -## X.X.X.X -- XXXX.XX.XX +## 1.0.1.3 -- 2024-09-16 * Adjust README formatting * Add Hype section to README -* Some code cleanup +* Some code and documentation cleanup diff --git a/README.md b/README.md index 149f615..daa8298 100644 --- a/README.md +++ b/README.md @@ -170,8 +170,11 @@ falter without:
Comment from Ackley in the Beyond Efficiency code about Perl
-        updates breaking their code + alt="A screenshot from Ackley's code referenced in 'Beyond Efficiency': + 'Written by Dave Ackley in 2011-2012 and placed in the public + domain. Gah! Perl has messed with its sorting algorithms in + COMPLETELY NON-BACKWARD-COMPATIBLE WAYS! So require our version + (more or less, anyway) to try to stabilize these results!'">
@@ -1176,4 +1179,13 @@ I'd like to send a special thank you to the following people: ## Hype - - Dave Ackley read my paper!! And had [this](https://hachyderm.io/@livcomp/113016513691522706) to say about it: "Super great stuff! kabeech dives into iid errors in comparison sorting, ropes it, pulls it down, and hogties it six ways to Sunday." + - Dave Ackley read my paper!! And had + [this](https://hachyderm.io/@livcomp/113016513691522706) to say about it: + "Super great stuff! kabeech dives into iid errors in comparison sorting, + ropes it, pulls it down, and hogties it six ways to Sunday." + + - Ivan Reese also had + [very kind](https://futureofcoding.slack.com/archives/CCL5VVBAN/p1724550313800559?thread_ts=1724444821.212869&cid=CCL5VVBAN) + things to say: "Hats off Kyle. You've made something very cool and + technical and fascinating, but also woven charm and joy into its + presentation. Beautiful." diff --git a/src/Data/Tensort/OtherSorts/Mergesort.hs b/src/Data/Tensort/OtherSorts/Mergesort.hs index c742836..cdbbca7 100644 --- a/src/Data/Tensort/OtherSorts/Mergesort.hs +++ b/src/Data/Tensort/OtherSorts/Mergesort.hs @@ -1,11 +1,12 @@ --- | This module provides the mergesort function for sorting lists using the --- Sortable type +-- | This module provides an implementation of the mergesort algorithm suitable +-- for sorting lists using the Sortable type. module Data.Tensort.OtherSorts.Mergesort (mergesort) where import Data.Tensort.Utils.ComparisonFunctions (lessThanBit, lessThanRecord) import Data.Tensort.Utils.Types (Bit, Record, Sortable (..)) --- | Takes a Sortable and returns a sorted Sortable using a Mergesort algorithm +-- | Takes a Sortable and returns a sorted Sortable using a Mergesort +-- algorithm. -- | ==== __Examples__ -- >>> mergesort (SortBit [16, 23, 4, 8, 15, 42]) diff --git a/src/Data/Tensort/OtherSorts/Quicksort.hs b/src/Data/Tensort/OtherSorts/Quicksort.hs index 8bffc85..d5dd5f2 100644 --- a/src/Data/Tensort/OtherSorts/Quicksort.hs +++ b/src/Data/Tensort/OtherSorts/Quicksort.hs @@ -1,11 +1,12 @@ --- | This module provides the quicksort function for sorting lists using the --- Sortable type +-- | This module provides an implementation of the quicksort algorithm suitable +-- for sorting lists using the Sortable type. module Data.Tensort.OtherSorts.Quicksort (quicksort) where import Data.Tensort.Utils.ComparisonFunctions (greaterThanBit, greaterThanRecord) import Data.Tensort.Utils.Types (Bit, Record, Sortable (..)) --- | Takes a Sortable and returns a sorted Sortable using a Quicksort algorithm +-- | Takes a Sortable and returns a sorted Sortable using a Quicksort +-- algorithm. -- | ==== __Examples__ -- >>> quicksort (SortBit [16, 23, 4, 8, 15, 42]) diff --git a/src/Data/Tensort/Robustsort.hs b/src/Data/Tensort/Robustsort.hs index 9b48ead..2842b33 100644 --- a/src/Data/Tensort/Robustsort.hs +++ b/src/Data/Tensort/Robustsort.hs @@ -1,5 +1,5 @@ -- | This module provides variations of the Robustsort algorithm using the --- Sortable type +-- custom Sortable type for inputs and outputs module Data.Tensort.Robustsort ( robustsortP, robustsortB, @@ -138,11 +138,11 @@ supersortM = -- the base SortAlg to sort the records. -- -- Uses the base SortAlg once the bytesize is less than or equal to 27. This --- number is chosen because it is the natural logarithm of 27 is close to --- 3 (it's abuot 3.3) and the square root of 27 is 3, so it's likely to be an --- efficient choice. +-- number is chosen because the natural logarithm of 27 is close to 3 (it's +-- about 3.3) and the cube root of 27 is 3, so it's likely to be an efficient +-- choice. -- --- This confiuguration is tailored to using a standard basic Robustsort +-- This configuration is tailored to using a standard basic Robustsort -- algorithm (i.e. with a Bytesize of 3) as the base SortAlg. You're welcome -- to experiment with weirder setups too! -- @@ -161,6 +161,13 @@ robustsortRCustom baseSortAlg xs = ) xs +-- | Used to create SubAlgorithms for use in recursive Robustsort variants. See +-- also `robustsortRCustom`. +-- +-- Creates an algorithm that recursively applies Tensort with a Bytesize that +-- approximates the natural logarithm of the length of the input list until +-- the Bytesize is less than or equal to 27. At this point, the baseSortAlg +-- is used to sort the records. robustsortRecursive :: Int -> SortAlg -> SortAlg robustsortRecursive bytesize baseSortAlg -- ln (532048240602) ~= 27 @@ -168,8 +175,8 @@ robustsortRecursive bytesize baseSortAlg -- 3 ^ 3 = 27 -- So this is saying, if we have a bitesize of 532,048,240,602 or less, use -- one more iteration of Tensort to sort the records. This last iteration - -- will use the baseSortAlg (which by default is a standard version of - -- Robustsort with a bytesize of 3) to sort its records. + -- will use the baseSortAlg (such as the basic version of Robustsort with + -- bytesize of 3 used in this module) to sort its records. | bytesize <= 27 = baseSortAlg | otherwise = tensort diff --git a/src/Data/Tensort/Subalgorithms/Bogosort.hs b/src/Data/Tensort/Subalgorithms/Bogosort.hs index d7e3438..8ddd2c2 100644 --- a/src/Data/Tensort/Subalgorithms/Bogosort.hs +++ b/src/Data/Tensort/Subalgorithms/Bogosort.hs @@ -1,31 +1,29 @@ --- | This module provides the bogosort function for sorting lists using the --- Sortable type +-- | This module provides the bogosort function for sorting Sortable lists module Data.Tensort.Subalgorithms.Bogosort (bogosort, bogosortSeeded) where import Data.Tensort.Utils.Check (isSorted) import Data.Tensort.Utils.RandomizeList (randomizeList) import Data.Tensort.Utils.Types (Sortable (..)) --- | Takes a Sortable and returns a sorted Sortable using a Bogosort algorithm --- using the default seed for random generation +-- | Takes a Sortable and returns a sorted Sortable using a Bogosort algorithm. -- | ==== __Examples__ -- >>> bogosort (SortBit [16, 23, 4, 8, 15, 42]) -- SortBit [4,8,15,16,23,42] -- --- >>> bogosort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)]) +-- >>> bogosort (SortRec [(1, 16), (5, 23), (2, 4), (3, 8), (0, 15), (4, 42)]) -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)] bogosort :: Sortable -> Sortable bogosort = bogosortSeeded 143 -- | Takes a seed for use in random generation and a Sortable and returns a --- sorted Sortable using a Bogosort algorithm +-- sorted Sortable using a Bogosort algorithm. -- | ==== __Examples__ -- >>> bogosortSeeded 42 (SortBit [16, 23, 4, 8, 15, 42]) -- SortBit [4,8,15,16,23,42] -- --- >>> bogosortSeeded 24 (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)]) +-- >>> bogosortSeeded 24 (SortRec [(1, 16), (5, 23), (2, 4), (3, 8), (0, 15), (4, 42)]) -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)] bogosortSeeded :: Int -> Sortable -> Sortable bogosortSeeded seed xs diff --git a/src/Data/Tensort/Subalgorithms/Bubblesort.hs b/src/Data/Tensort/Subalgorithms/Bubblesort.hs index 5635788..1571984 100644 --- a/src/Data/Tensort/Subalgorithms/Bubblesort.hs +++ b/src/Data/Tensort/Subalgorithms/Bubblesort.hs @@ -1,5 +1,4 @@ --- | This module provides the bubblesort function for sorting lists using the --- Sortable type +-- | This module provides the bubblesort function for sorting Sortable lists module Data.Tensort.Subalgorithms.Bubblesort (bubblesort) where import Data.Tensort.Utils.ComparisonFunctions @@ -9,13 +8,13 @@ import Data.Tensort.Utils.ComparisonFunctions import Data.Tensort.Utils.Types (Sortable (..)) -- | Takes a Sortable and returns a sorted Sortable using a Bubblesort --- algorithm +-- algorithm. -- | ==== __Examples__ -- >>> bubblesort (SortBit [16, 23, 4, 8, 15, 42]) -- SortBit [4,8,15,16,23,42] -- --- >>> bubblesort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)]) +-- >>> bubblesort (SortRec [(1, 16), (5, 23), (2, 4), (3, 8), (0, 15), (4, 42)]) -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)] bubblesort :: Sortable -> Sortable bubblesort (SortBit bits) = diff --git a/src/Data/Tensort/Subalgorithms/Exchangesort.hs b/src/Data/Tensort/Subalgorithms/Exchangesort.hs index 2dcab3c..b3fd477 100644 --- a/src/Data/Tensort/Subalgorithms/Exchangesort.hs +++ b/src/Data/Tensort/Subalgorithms/Exchangesort.hs @@ -1,12 +1,11 @@ --- | This module provides the bubblesort function for sorting lists using the --- Sortable type +-- | This module provides the bubblesort function for sorting Sortable lists module Data.Tensort.Subalgorithms.Exchangesort (exchangesort) where import Data.Tensort.Utils.ComparisonFunctions (greaterThanBit, greaterThanRecord) import Data.Tensort.Utils.Types (Sortable (..)) -- | Takes a Sortable and returns a sorted Sortable using an Exchangesort --- algorithm +-- algorithm. -- | ==== __Examples__ -- >>> exchangesort (SortBit [16, 23, 4, 8, 15, 42]) diff --git a/src/Data/Tensort/Subalgorithms/Magicsort.hs b/src/Data/Tensort/Subalgorithms/Magicsort.hs index 7137ba9..e2b470f 100644 --- a/src/Data/Tensort/Subalgorithms/Magicsort.hs +++ b/src/Data/Tensort/Subalgorithms/Magicsort.hs @@ -1,5 +1,4 @@ --- | This module provides the magicsort function for sorting lists using the --- Sortable type +-- | This module provides the magicsort function for sorting Sortable lists module Data.Tensort.Subalgorithms.Magicsort ( magicsort, ) @@ -9,16 +8,17 @@ import Data.Tensort.Subalgorithms.Bogosort (bogosort) import Data.Tensort.Subalgorithms.Permutationsort (permutationsort) import Data.Tensort.Utils.Types (Sortable (..)) --- | Takes a Sortable and returns a sorted Sortable +-- | Takes a Sortable and returns a sorted Sortable. -- --- Adjudicates between three other sorting algorithms to return a robust --- solution +-- Runs both Permutationsort and Bogosort on the input Sortable and compares +-- the results. If the results agree, returns the result of Permutationsort, +-- otherwise repeats the process. -- | ==== __Examples__ -- >>> magicsort (SortBit [16, 23, 4, 8, 15, 42]) -- SortBit [4,8,15,16,23,42] -- --- >>> magicsort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15) , (4, 42)]) +-- >>> magicsort (SortRec [(1, 16), (5, 23), (2, 4) ,(3, 8), (0, 15), (4, 42)]) -- SortRec [(2,4),(3,8),(0,15),(1,16),(5,23),(4,42)] magicsort :: Sortable -> Sortable magicsort xs = do diff --git a/src/Data/Tensort/Subalgorithms/Permutationsort.hs b/src/Data/Tensort/Subalgorithms/Permutationsort.hs index 216ee14..7c49e86 100644 --- a/src/Data/Tensort/Subalgorithms/Permutationsort.hs +++ b/src/Data/Tensort/Subalgorithms/Permutationsort.hs @@ -1,5 +1,5 @@ --- | This module provides the permutationsort function for sorting lists using the --- Sortable type +-- | This module provides the permutationsort function for sorting Sortable +-- lists module Data.Tensort.Subalgorithms.Permutationsort (permutationsort) where import Data.List (permutations) @@ -12,7 +12,7 @@ import Data.Tensort.Utils.Types fromSortRec, ) --- | Takes a Sortable and returns a sorted Sortable using a Permutationsort +-- | Takes a Sortable and returns a sorted Sortable using Permutationsort -- algorithm -- | ==== __Examples__ diff --git a/src/Data/Tensort/Subalgorithms/Rotationsort.hs b/src/Data/Tensort/Subalgorithms/Rotationsort.hs index b85284d..64b469c 100644 --- a/src/Data/Tensort/Subalgorithms/Rotationsort.hs +++ b/src/Data/Tensort/Subalgorithms/Rotationsort.hs @@ -1,5 +1,4 @@ --- | This module provides Rotationsort variants for sorting lists using the --- Sortable type +-- | This module provides Rotationsort variants for sorting Sortable lists. -- -- | I was having some issues with the swaps for larger input lists, so for now -- these functions are only implemented for lists of length 3 or less. @@ -18,7 +17,7 @@ import Data.Tensort.Utils.ComparisonFunctions import Data.Tensort.Utils.Types (Sortable (..)) -- | Takes a Sortable and returns a sorted Sortable using a Rotationsort --- algorithm +-- algorithm. -- -- I was having some issues with the swaps for larger input lists, so for now -- this function is only implemented for lists of length 3 or less. @@ -40,7 +39,7 @@ rotationsort (SortRec recs) = in SortRec result -- | Takes a Sortable and returns a sorted Sortable using an Ambidextrous --- Rotationsort algorithm +-- Rotationsort algorithm. -- -- I was having some issues with the swaps for larger input lists, so for now -- this function is only implemented for lists of length 3 or less. @@ -62,7 +61,7 @@ rotationsortAmbi (SortRec recs) = in SortRec result -- | Takes a Sortable and returns a sorted Sortable using a Reverse --- Rotationsort algorithm +-- Rotationsort algorithm. -- -- I was having some issues with the swaps for larger input lists, so for now -- this function is only implemented for lists of length 3 or less. @@ -94,7 +93,7 @@ rotationsortReverse (SortRec recs) = in SortRec result -- | Takes a Sortable and returns a sorted Sortable using an Ambidextrous --- Reverse Rotationsort algorithm +-- Reverse Rotationsort algorithm. -- -- I was having some issues with the swaps for larger input lists, so for now -- this function is only implemented for lists of length 3 or less. diff --git a/src/Data/Tensort/Subalgorithms/Supersort.hs b/src/Data/Tensort/Subalgorithms/Supersort.hs index a9a8787..d411c7c 100755 --- a/src/Data/Tensort/Subalgorithms/Supersort.hs +++ b/src/Data/Tensort/Subalgorithms/Supersort.hs @@ -1,5 +1,5 @@ -- | This module provides functions for creating Supersort variants for --- adjudicating between 3 sorting algorithms that use the Sortable type +-- adjudicating between 3 sorting algorithms. module Data.Tensort.Subalgorithms.Supersort ( supersort, mundaneSuperStrat, @@ -13,8 +13,12 @@ import Data.Tensort.Utils.Types SupersortStrat, ) --- | Takes 3 sorting algorithms and a SuperStrat and returns a SortAlg that --- adjudicates between the 3 sorting algorithms using the provided SuperStrat +-- | Used for creating a Supersort algorithm that adjudicates between 3 sorting +-- algorithms. +-- +-- Takes 3 sorting algorithms and a SuperStrat and returns a SortAlg that +-- adjudicates between the 3 sorting algorithms using the provided +-- SuperStrat. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -37,8 +41,8 @@ supersort (subAlg1, subAlg2, subAlg3, superStrat) xs = do then result1 else superStrat (result1, result2, subAlg3 xs) --- | Takes 3 SortAlgs and adjudicates between them to find a common result to --- increase robustness +-- | Takes 3 SortAlgs and adjudicates between them to find a common result. +-- Optimized for use in Mundane Robustsort variants. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -53,12 +57,12 @@ supersort (subAlg1, subAlg2, subAlg3, superStrat) xs = do mundaneSuperStrat :: SupersortStrat mundaneSuperStrat (result1, result2, result3) = if result2 == result3 then result2 else result1 --- | Takes 3 SortAlgs and adjudicates between them to find a common result to --- increase robustness +-- | Takes 3 SortAlgs and adjudicates between them to find a common result. +-- Optimized for use in Magic Robustsort variants. -- -- Previously we used different SuperStrats for Mundane and Magic Supersorts. -- Currently there is no need to differentiate, but we keep this here for --- backwards compatibility and in case this changes again in the future +-- backwards compatibility and in case this changes again in the future. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) diff --git a/src/Data/Tensort/Tensort.hs b/src/Data/Tensort/Tensort.hs index 0970872..04a2247 100644 --- a/src/Data/Tensort/Tensort.hs +++ b/src/Data/Tensort/Tensort.hs @@ -1,5 +1,5 @@ -- | This module provides variations of the Tensort algorithm using the --- Sortable type +-- custom Sortable type for inputs and outputs module Data.Tensort.Tensort ( tensort, tensortB4, @@ -25,7 +25,8 @@ import Data.Tensort.Utils.Types -- | Sort a Sortable list using a custom Tensort algorithm -- --- Takes TensortProps and a Sortable and returns a sorted Sortable +-- Takes TensortProps (Bytesize and SubAlgorithm) and a Sortable and returns +-- a sorted Sortable -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -80,6 +81,9 @@ tensortBN :: Int -> Sortable -> Sortable tensortBN n = tensort (mkTsProps n bubblesort) -- | Sort a Sortable list using a Standard Logarithmic Tensort algorithm +-- +-- Standard Logarithmic Tensort uses a Bytesize that approximates the natural +-- logarithm of the length of the input list and a Bubblesort subalgorithm -- | ==== __Examples__ -- >>> tensortBL (SortBit [16, 23, 4, 8, 15, 42]) diff --git a/src/Data/Tensort/Utils/Compose.hs b/src/Data/Tensort/Utils/Compose.hs index 04f7c30..49ccfeb 100644 --- a/src/Data/Tensort/Utils/Compose.hs +++ b/src/Data/Tensort/Utils/Compose.hs @@ -1,12 +1,12 @@ --- | Module for creating Tensors from Bytes and Tensors +-- | Module for creating Tensors from Bytes and Tensors. -- -- Functions ending in "B" are for sorting Bits in a base (non-recursive) --- Tensort variant +-- Tensort variant. -- -- Functions ending in "R" are for sorting Records when used in a recursive --- Tensort variant +-- Tensort variant. -- --- TODO: See if we can clean up the type conversion here +-- TODO: See if we can clean up the type conversion here. module Data.Tensort.Utils.Compose ( createInitialTensors, createTensor, @@ -49,7 +49,7 @@ import Data.Tensort.Utils.Types -- | This is accomplished by making a Tensor for each Byte, converting that -- Tensor into a TensorStack (these are equivalent terms - see type --- definitions for more info) and collating the TensorStacks into a list +-- definitions for more info) and collating the TensorStacks into a list. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -84,9 +84,10 @@ createInitialTensorsR tsProps bytesR = (getTensorFromBytes (subAlgorithm tsProps) (SBytesRec byteR)) ] --- | Create a Tensor from a Memory +-- | Create a Tensor from a Memory. +-- -- Aliases to getTensorFromBytes for ByteMem and getTensorFromTensors for --- TensorMem +-- TensorMem. createTensor :: SortAlg -> SMemory -> STensor createTensor subAlg (SMemoryBit memory) = createTensorB subAlg memory createTensor subAlg (SMemoryRec memoryR) = createTensorR subAlg memoryR @@ -103,16 +104,16 @@ createTensorR subAlg (ByteMemR bytesR) = createTensorR subAlg (TensorMemR tensorsR) = getTensorFromTensors subAlg (STensorsRec tensorsR) --- | Convert a list of Bytes to a Tensor +-- | Convert a list of Bytes to a Tensor. -- | We do this by loading the list of Bytes into the new Tensor's Memory --- and adding a sorted Register containing References to each Byte in Memory +-- and adding a sorted Register containing References to each Byte in Memory. -- | Each Record contains an Address pointing to the index of the referenced -- Byte and a TopBit containing the value of the last (i.e. highest) Bit in --- the referenced Byte +-- the referenced Byte. --- | The Register is sorted by the TopBits of each Record +-- | The Register is sorted by the TopBits of each Record. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -153,7 +154,7 @@ getTensorFromBytesR subAlg bytesR = do acc remainingBytesR (registerR ++ [(i, last byteR)]) (i + 1) -- | Create a TensorStack with the collated and sorted References from the --- Tensors as the Register and the original Tensors as the data +-- Tensors as its Register and the original Tensors as its Memory. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -189,11 +190,15 @@ getTensorFromTensorsR subAlg tensorsR = do (fromSRecordArrayRec registerR) (registerR', TensorMemR tensorsR) --- | For each Tensor, produces a Record by combining the top bit of the --- Tensor with an index value for its Address +-- | Used in creating a Register for a newly-created Tensor which encloses +-- other Tensors. +-- +-- Takes a list of Tensors to be processed into the enclosing Tensor's +-- memory. For each Tensor in the list, produces a Record by combining the +-- top bit of the Tensor with an index value for its Address. -- | Note that this output is not sorted. Sorting is done in the --- getTensorFromTensors function +-- getTensorFromTensors function. -- | ==== __Examples__ -- >>> getRegisterFromTensors (STensorsBit [([(0,13),(1,18)],ByteMem [[11,13],[15,18]]),([(0,14),(1,17)],ByteMem [[12,14],[16,17]]),([(0,3),(1,7)],ByteMem [[1,3],[5,7]]),([(0,4),(1,8)],ByteMem [[2,4],[6,8]])]) @@ -242,13 +247,13 @@ getRegisterFromTensorsR tensorsR = acc tensorsR [] where i = length records --- | Get the top Bit from a TensorStack +-- | Get the top Bit from a TensorStack. -- | The top Bit is the last Bit in the last Byte referenced in the last record -- of the Tensor referenced in the last record of the last Tensor of... --- and so on until you reach the top level of the TensorStack +-- and so on until you reach the top level of the TensorStack. --- | This is also expected to be the highest value in the TensorStack +-- | This is also expected to be the highest value in the TensorStack. -- | ==== __Examples__ -- >>> getTopBitFromTensorStack (STensorBit ([(0,28),(1,38)],TensorMem [([(0,27),(1,28)],TensorMem [([(0,23),(1,27)],ByteMem [[21,23],[25,27]]),([(0,24),(1,28)],ByteMem [[22,24],[26,28]])]),([(1,37),(0,38)],TensorMem [([(0,33),(1,38)],ByteMem [[31,33],[35,38]]),([(0,34),(1,37)],ByteMem [[32,14],[36,37]])])])) diff --git a/src/Data/Tensort/Utils/Convert.hs b/src/Data/Tensort/Utils/Convert.hs index ebf3240..ab38646 100644 --- a/src/Data/Tensort/Utils/Convert.hs +++ b/src/Data/Tensort/Utils/Convert.hs @@ -1,6 +1,6 @@ --- | Module for converting raw input data to SBytes +-- | Module for converting raw input data into SBytes. -- --- TODO: See if we can clean up the type conversion here +-- TODO: See if we can clean up the type conversion here. module Data.Tensort.Utils.Convert (rawToBytes) where import Data.Tensort.Utils.Split (splitEvery) @@ -16,7 +16,7 @@ import Data.Tensort.Utils.Types ) -- | Convert a list of Bits to a list of Bytes of given bytesize, sorting --- each byte with the given subalgorithm. +-- each Byte with the given subalgorithm. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) diff --git a/src/Data/Tensort/Utils/LogNat.hs b/src/Data/Tensort/Utils/LogNat.hs index 28906ff..8c13055 100644 --- a/src/Data/Tensort/Utils/LogNat.hs +++ b/src/Data/Tensort/Utils/LogNat.hs @@ -1,10 +1,10 @@ -- | This module provides functions for calculating the natural logarithms in --- a way useful for creating logarithmic Bytesizes +-- a way useful for creating logarithmic Bytesizes. module Data.Tensort.Utils.LogNat (getLnBytesize, getLn) where import Data.Tensort.Utils.Types (Sortable (..)) --- | Calculate a suitable logarithmic Bytesize from a Sortable +-- | Calculates a suitable logarithmic Bytesize for a given Sortable list. -- | ==== __Examples__ -- >>> getLnBytesize (SortBit [1 .. 27]) @@ -16,8 +16,8 @@ getLnBytesize :: Sortable -> Int getLnBytesize (SortBit xs) = getLn (length xs) getLnBytesize (SortRec xs) = getLn (length xs) --- | Calculate a the natural logarithm of an Int, rounded up to the nearest --- integer +-- | Calculates the natural logarithm of an integer, rounded up to the nearest +-- integer. -- -- | ==== __Examples__ -- >>> getLn 27 diff --git a/src/Data/Tensort/Utils/MkTsProps.hs b/src/Data/Tensort/Utils/MkTsProps.hs index 82cff29..2bc5c26 100644 --- a/src/Data/Tensort/Utils/MkTsProps.hs +++ b/src/Data/Tensort/Utils/MkTsProps.hs @@ -1,8 +1,8 @@ --- | This module provides the mkTsProps function for creating TensortProps +-- | This module provides the mkTsProps function for creating TensortProps. module Data.Tensort.Utils.MkTsProps (mkTsProps) where import Data.Tensort.Utils.Types (SortAlg, TensortProps (..)) --- | Wraps in integer Bytesize and a SortAlg together as TensortProps +-- | Wraps in integer Bytesize and a SubAlgorithm together as TensortProps. mkTsProps :: Int -> SortAlg -> TensortProps mkTsProps bSize subAlg = TensortProps {bytesize = bSize, subAlgorithm = subAlg} diff --git a/src/Data/Tensort/Utils/RandomizeList.hs b/src/Data/Tensort/Utils/RandomizeList.hs index f9b1c53..44cdc7f 100644 --- a/src/Data/Tensort/Utils/RandomizeList.hs +++ b/src/Data/Tensort/Utils/RandomizeList.hs @@ -1,5 +1,5 @@ --- | This module prvodies the randomizeList function, which randomizes Sortable --- lists. +-- | This module prvodies the randomizeList function, which randomizes the +-- order of elements in Sortable lists. module Data.Tensort.Utils.RandomizeList (randomizeList) where import Data.Tensort.Utils.Types (Sortable (..)) diff --git a/src/Data/Tensort/Utils/Reduce.hs b/src/Data/Tensort/Utils/Reduce.hs index 5727abb..fc01e42 100644 --- a/src/Data/Tensort/Utils/Reduce.hs +++ b/src/Data/Tensort/Utils/Reduce.hs @@ -1,13 +1,13 @@ -- | This module provides functions to reduce a list of TensorStacks into a --- more compact list of TensorStacks +-- more compact list of TensorStacks. -- -- Functions ending in "B" are for sorting Bits in a base (non-recursive) --- Tensort variant +-- Tensort variant. -- -- Functions ending in "R" are for sorting Records when used in a recursive --- Tensort variant +-- Tensort variant. -- --- TODO: See if we can clean up the type conversion here +-- TODO: See if we can clean up the type conversion here. module Data.Tensort.Utils.Reduce (reduceTensorStacks) where import Data.Tensort.Utils.Compose (createTensor) @@ -28,9 +28,9 @@ import Data.Tensort.Utils.Types -- | Take a list of TensorStacks and group them together in new -- TensorStacks, each containing bytesize number of Tensors (former --- TensorStacks), until the number of TensorStacks is equal to the bytesize +-- TensorStacks), until the number of TensorStacks is equal to the bytesize. --- The Registers of the new TensorStacks are bubblesorted, as usual +-- The Registers of the new TensorStacks are bubblesorted, as usual. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -63,11 +63,11 @@ reduceTensorStacksR tsProps tensorStacks = do (SMemoryRec (TensorMemR newTensorStacks)) else reduceTensorStacksR tsProps newTensorStacks --- | Take a list of TensorStacks and group them together in new +-- | Take a list of TensorStacks and group them together in new -- TensorStacks each containing bytesize number of Tensors (former --- TensorStacks) +-- TensorStacks). --- The Registers of the new TensorStacks are bubblesorted, as usual +-- The Registers of the new TensorStacks are bubblesorted, as usual. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) diff --git a/src/Data/Tensort/Utils/Render.hs b/src/Data/Tensort/Utils/Render.hs index ead7e88..9069b63 100644 --- a/src/Data/Tensort/Utils/Render.hs +++ b/src/Data/Tensort/Utils/Render.hs @@ -1,12 +1,12 @@ --- | Module for rendering a sorted list of Bits from a list of TensorStacks +-- | Module for rendering a sorted list of Bits from a list of TensorStacks. -- -- Functions ending in "B" are for sorting Bits in a base (non-recursive) --- Tensort variant +-- Tensort variant. -- -- Functions ending in "R" are for sorting Records when used in a recursive --- Tensort variant +-- Tensort variant. -- --- TODO: See if we can clean up the type conversion here +-- TODO: See if we can clean up the type conversion here. module Data.Tensort.Utils.Render (getSortedBitsFromTensor) where import Data.Maybe (isNothing) @@ -33,7 +33,7 @@ import Data.Tensort.Utils.Types fromSortRec, ) --- | Compile a sorted list of Bits from a list of TensorStacks +-- | Compile a sorted list of Bits from a list of TensorStacks. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) @@ -71,10 +71,10 @@ getSortedBitsFromTensorR subAlg tensorRaw = acc tensorRaw [] else do acc (fromJust tensor') (nextBit' : sortedBits) --- | For use in compiling a list of Tensors into a sorted list of Bits +-- | For use in compiling a list of Tensors into a sorted list of Bits. -- -- | Removes the top Bit from a Tensor, rebalances the Tensor and returns --- the removed Bit along with the rebalanced Tensor +-- the removed Bit along with the rebalanced Tensor. -- | ==== __Examples__ -- >>> import Data.Tensort.Subalgorithms.Bubblesort (bubblesort) diff --git a/src/Data/Tensort/Utils/SimplifyRegister.hs b/src/Data/Tensort/Utils/SimplifyRegister.hs index c2dce71..14853ce 100644 --- a/src/Data/Tensort/Utils/SimplifyRegister.hs +++ b/src/Data/Tensort/Utils/SimplifyRegister.hs @@ -1,3 +1,5 @@ +-- | This module provides functions to simplify sorting Registers in Tensort +-- variants that are sorting Records in their input instead of Bits. module Data.Tensort.Utils.SimplifyRegister ( simplifyRegister, applySortingFromSimplifiedRegister, @@ -7,9 +9,22 @@ where import qualified Data.Bifunctor import Data.Tensort.Utils.Types (Record, RecordR) +-- | For use in Tensort variants that are sorting Records in their input +-- instead of Bits. +-- +-- This function simplifies the Register used for sorting Records by +-- replacing the TopRecord of each RecordR with its TopBit. This returns +-- a Register of standard Records that can be used for sorting. simplifyRegister :: [RecordR] -> [Record] simplifyRegister = map (Data.Bifunctor.second snd) +-- | For use in Tensort variants that are sorting Records in their input +-- instead of Bits. +-- +-- This function takes a simplified Register that has been sorted and the +-- unsimplified, unsorted, original RegisterR. It puts the elements of the +-- original RegisterR in the same order as the simplified, sorted Register +-- and returns the sorted RegisterR. applySortingFromSimplifiedRegister :: [Record] -> [RecordR] -> [RecordR] applySortingFromSimplifiedRegister sortedSimplifiedRegister diff --git a/src/Data/Tensort/Utils/Split.hs b/src/Data/Tensort/Utils/Split.hs index 456ca6a..e93d9eb 100644 --- a/src/Data/Tensort/Utils/Split.hs +++ b/src/Data/Tensort/Utils/Split.hs @@ -1,3 +1,5 @@ +-- | This module provides a function to split a list into chunks of a given +-- size. module Data.Tensort.Utils.Split (splitEvery) where -- | Split a list into chunks of a given size. diff --git a/src/Data/Tensort/Utils/Types.hs b/src/Data/Tensort/Utils/Types.hs index 59fe1fc..b462f86 100644 --- a/src/Data/Tensort/Utils/Types.hs +++ b/src/Data/Tensort/Utils/Types.hs @@ -1,46 +1,46 @@ {-# LANGUAGE GADTs #-} --- | This module provides types used in the Tensort package +-- | This module provides types used in the Tensort package. -- -- Since these packages are only for sorting Ints currently, every data --- type is a structure of Ints +-- type is a structure of Ints. module Data.Tensort.Utils.Types where -- | TensortProps contains the Bytesize and SubAlgorithm used in a Tensort --- algorithm +-- algorithm. data TensortProps = TensortProps {bytesize :: Int, subAlgorithm :: SortAlg} --- | A Bit is a single element of the list to be sorted. For --- our current purposes that means it is an Int +-- | A Bit is a single element of the list to be sorted. For our current +-- purposes that means it is an Int. --- The definition of a Bit may be expanded in the future to include any Ord +-- The definition of a Bit may be expanded in the future to include any Ord. type Bit = Int --- | A Byte is a list of Bits standardized to a fixed maximum length (Bytesize) +-- | A Byte is a list of Bits standardized to a fixed maximum length (Bytesize). -- The length should be set either in or upstream of any function that uses --- Bytes +-- Bytes. type Byte = [Bit] --- | An Address is a index number pointing to data stored in Memory +-- | An Address is a index number pointing to data stored in Memory. type Address = Int -- | A TopBit contains a copy of the last (i.e. highest) Bit in a Byte or --- Tensor +-- Tensor. type TopBit = Bit -- | A Record is an element in a Tensor's Register --- containing an Address pointer and a TopBit value +-- containing an Address pointer and a TopBit value. -- A Record's Address is an index number pointing to a Byte or Tensor in --- the Tensor's Memory +-- the Tensor's Memory. -- A Record's TopBit is a copy of the last (i.e. highest) Bit in the Byte or --- Tensor that the Record references +-- Tensor that the Record references. type Record = (Address, TopBit) -- | A Register is a list of Records allowing for easy access to data in a --- Tensor's Memory +-- Tensor's Memory. type Register = [Record] -- | A Memory contains the data to be sorted, either in the form of Bytes or @@ -65,20 +65,20 @@ type Tensor = (Register, Memory) -- TensorStacks. type TensorStack = Tensor --- | We use a Sortable type to sort Bits and Records +-- | We use a Sortable type to sort list of Bits and lists of Records. data Sortable = SortBit [Bit] | SortRec [Record] deriving (Show, Eq, Ord) --- | Converts a Sortable list to a list of Bits +-- | Converts a Sortable list to a list of Bits. fromSortBit :: Sortable -> [Bit] fromSortBit (SortBit bits) = bits fromSortBit (SortRec _) = error "From fromSortBit: This is for sorting Bits - you gave me Records" --- | Converts a Sortable list to a list of Records +-- | Converts a Sortable list to a list of Records. fromSortRec :: Sortable -> [Record] fromSortRec (SortRec recs) = recs fromSortRec (SortBit _) = @@ -86,18 +86,18 @@ fromSortRec (SortBit _) = "From fromSortRec: This is for sorting Records - you gave me Bits" -- | A sorting algorithm is a function that takes a Sortable and returns a --- sorted Sortable +-- sorted Sortable. type SortAlg = Sortable -> Sortable -- | SupersortProps consist of three sorting algorithms to adjuditcate between --- and a SupersortStrat that does the adjudication +-- and a SupersortStrat that does the adjudication. type SupersortProps = (SortAlg, SortAlg, SortAlg, SupersortStrat) -- | A SupersortStrat takes three Sortables and determines which of the three --- is most likely to be in the correct order +-- is most likely to be in the correct order. type SupersortStrat = (Sortable, Sortable, Sortable) -> Sortable --- | Convers a Maybe into a value or throws an error if the Maybe is Nothing +-- | Converts a Maybe into a value or throws an error if the Maybe is Nothing. fromJust :: Maybe a -> a fromJust (Just x) = x fromJust Nothing = error "fromJust: Nothing" @@ -107,57 +107,57 @@ fromJust Nothing = error "fromJust: Nothing" -------------------------------------- -- | This is a `Bit` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. type BitR = Record -- | This is a conversion type that allows for sorting both Bits and Records. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data SBit = SBitBit Bit | SBitRec Record deriving (Show, Eq, Ord) --- | Converts an SBit to a Bit +-- | Converts an SBit into a Bit. fromSBitBit :: SBit -> Bit fromSBitBit (SBitBit bit) = bit fromSBitBit (SBitRec _) = error "From fromSBitBit: This is for sorting Bits - you gave me Records" --- | Converts an SBit to a Record +-- | Converts an SBit into a Record. fromSBitRec :: SBit -> Record fromSBitRec (SBitRec record) = record fromSBitRec (SBitBit _) = error "From fromSBitRec: This is for sorting Records - you gave me Bits" --- | Converts a list of Bits to a Sortable +-- | Converts a list of Bits into a Sortable. fromSBitBits :: [SBit] -> Sortable fromSBitBits = SortBit . map fromSBitBit --- | Converts a list of Records to a Sortable +-- | Converts a list of Records into a Sortable. fromSBitRecs :: [SBit] -> Sortable fromSBitRecs = SortRec . map fromSBitRec -- | This is a `Byte` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. type ByteR = [Record] -- | This is a conversion type that allows for sorting both Bits and Records. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data SBytes = SBytesBit [Byte] | SBytesRec [ByteR] deriving (Show, Eq, Ord) --- | Converts an SBytes list to a list of Bytes +-- | Converts an SBytes list into a list of Bytes. fromSBytesBit :: SBytes -> [[Bit]] fromSBytesBit (SBytesBit bits) = bits fromSBytesBit (SBytesRec _) = error "From fromSBytesBit: This is for sorting Bits - you gave me Records" --- | Converts an SBytes list to a list of ByteRs +-- | Converts an SBytes list into a list of ByteRs. fromSBytesRec :: SBytes -> [[Record]] fromSBytesRec (SBytesRec recs) = recs fromSBytesRec (SBytesBit _) = @@ -165,28 +165,28 @@ fromSBytesRec (SBytesBit _) = "From fromSBytesRec: This is for sorting Records - you gave me Bits" -- | This is a `TopBit` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. type TopBitR = Record -- | This is a `Record` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. type RecordR = (Address, TopBitR) -- | This is a conversion type that allows for sorting both Records and Bits. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data SRecord = SRecordBit Record | SRecordRec RecordR deriving (Show, Eq, Ord) --- | Converts an SRecord to a Record +-- | Converts an SRecord into a Record. fromSRecordBit :: SRecord -> Record fromSRecordBit (SRecordBit record) = record fromSRecordBit (SRecordRec _) = error "From fromSRecordBit: This is for sorting Records - you gave me Bits" --- | Converts an SRecord to a RecordR +-- | Converts an SRecord into a RecordR. fromSRecordRec :: SRecord -> RecordR fromSRecordRec (SRecordRec record) = record fromSRecordRec (SRecordBit _) = @@ -194,60 +194,60 @@ fromSRecordRec (SRecordBit _) = "From fromSRecordRec: This is for sorting Bits - you gave me Records" -- | This is a conversion type that allows for sorting both Records and Bits. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data SRecords = SRecordsBit [Record] | SRecordsRec [RecordR] deriving (Show, Eq, Ord) --- | Converts an SRecords list to a list of Records +-- | Converts an SRecords list into a list of Records. fromSRecordsBit :: SRecords -> [Record] fromSRecordsBit (SRecordsBit records) = records fromSRecordsBit (SRecordsRec _) = error "From fromSRecordsBit: This is for sorting Records - you gave me Bits" --- | Converts an SRecords list to a list of RecordRs +-- | Converts an SRecords list into a list of RecordRs. fromSRecordsRec :: SRecords -> [RecordR] fromSRecordsRec (SRecordsRec records) = records fromSRecordsRec (SRecordsBit _) = error "From fromSRecordsRec: This is for sorting Bits - you gave me Records" --- | Converts a list of SRecords to a list of Records +-- | Converts a list of SRecords into a list of Records. fromSRecordArrayBit :: [SRecord] -> [Record] fromSRecordArrayBit = map fromSRecordBit --- | Converts a list of SRecords to a list of RecordRs +-- | Converts a list of SRecords into a list of RecordRs. fromSRecordArrayRec :: [SRecord] -> [RecordR] fromSRecordArrayRec = map fromSRecordRec -- | This is a `Register` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. type RegisterR = [RecordR] -- | This is a `Memory` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. data MemoryR = ByteMemR [ByteR] | TensorMemR [TensorR] deriving (Show, Eq, Ord) -- | This is a conversion type that allows for sorting both Bits and Records. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data SMemory = SMemoryBit Memory | SMemoryRec MemoryR deriving (Show, Eq, Ord) --- | Converts an SMemory to a Memory +-- | Converts an SMemory to a Memory. fromSMemoryBit :: SMemory -> Memory fromSMemoryBit (SMemoryBit memory) = memory fromSMemoryBit (SMemoryRec _) = error "From fromSTensorsRec: This is for sorting Bits - you gave me Records" --- | Converts an SMemory to a MemoryR +-- | Converts an SMemory to a MemoryR. fromSMemoryRec :: SMemory -> MemoryR fromSMemoryRec (SMemoryRec memory) = memory fromSMemoryRec (SMemoryBit _) = @@ -255,24 +255,24 @@ fromSMemoryRec (SMemoryBit _) = "From fromSMemoryRec: This is for sorting Records - you gave me Bits" -- | This is a `Tensor` type that is used when sorting Records in a recursive --- Tensort variant +-- Tensort variant. type TensorR = (RegisterR, MemoryR) -- | This is a conversion type that allows for sorting both Bits and Records. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data STensor = STensorBit Tensor | STensorRec TensorR deriving (Show, Eq, Ord) --- | Converts an STensor to a Tensor +-- | Converts an STensor into a Tensor. fromSTensorBit :: STensor -> Tensor fromSTensorBit (STensorBit tensor) = tensor fromSTensorBit (STensorRec _) = error "From fromSTensorBit: This is for sorting Tensors - you gave me Records" --- | Converts an STensor to a TensorR +-- | Converts an STensor into a TensorR. fromSTensorRec :: STensor -> TensorR fromSTensorRec (STensorRec tensor) = tensor fromSTensorRec (STensorBit _) = @@ -280,20 +280,20 @@ fromSTensorRec (STensorBit _) = "From fromSTensorRec: This is for sorting Records - you gave me Tensors" -- | This is a conversion type that allows for sorting both Bits and Records. --- It is useful in recursive Tensort variants +-- It is useful in recursive Tensort variants. data STensors = STensorsBit [Tensor] | STensorsRec [TensorR] deriving (Show, Eq, Ord) --- | Converts an STensors list to a list of Tensors +-- | Converts an STensors list into a list of Tensors. fromSTensorsBit :: STensors -> [Tensor] fromSTensorsBit (STensorsBit tensors) = tensors fromSTensorsBit (STensorsRec _) = error "From fromSTensorsBit: This is for sorting Tensors - you gave me Records" --- | Converts an STensors list to a list of TensorRs +-- | Converts an STensors list into a list of TensorRs. fromSTensorsRec :: STensors -> [TensorR] fromSTensorsRec (STensorsRec tensors) = tensors fromSTensorsRec (STensorsBit _) = @@ -301,13 +301,13 @@ fromSTensorsRec (STensorsBit _) = "From fromSTensorsRec: This is for sorting Records - you gave me Tensors" -- | This is a `TensorStack` type that is used when sorting Records in a --- recursive Tensort variant +-- recursive Tensort variant. type TensorStackR = TensorR -- | This is a conversion type that allows for sorting both Tensors and --- Records. It is useful in recursive Tensort variants +-- Records. It is useful in recursive Tensort variants. type STensorStack = STensor -- | This is a conversion type that allows for sorting both Tensors and --- Records. It is useful in recursive Tensort variants +-- Records. It is useful in recursive Tensort variants. type STensorStacks = STensors diff --git a/src/Data/Tensort/Utils/WrapSortAlg.hs b/src/Data/Tensort/Utils/WrapSortAlg.hs index 34afcc5..048e08d 100644 --- a/src/Data/Tensort/Utils/WrapSortAlg.hs +++ b/src/Data/Tensort/Utils/WrapSortAlg.hs @@ -1,6 +1,6 @@ -- | This module provides convenience functions to wrap sorting algorithms -- that use the Sortable type so they can be used without worrying about --- type conversion +-- type conversion. module Data.Tensort.Utils.WrapSortAlg ( wrapSortAlg, ) @@ -9,7 +9,7 @@ where import Data.Tensort.Utils.Types (Bit, SortAlg, Sortable (SortBit), fromSortBit) -- | Wraps a sorting algorithm that uses the Sortable type so it can be used --- to sort Bits without worrying about type conversion +-- to sort Bits without worrying about type conversion. -- | ==== __Examples__ -- >>> import Data.Tensort.Robustsort (robustsortM) diff --git a/tensort.cabal b/tensort.cabal index a581b91..d14cf2e 100644 --- a/tensort.cabal +++ b/tensort.cabal @@ -20,7 +20,7 @@ name: tensort -- PVP summary: +-+------- breaking API changes -- | | +----- non-breaking API additions -- | | | +--- code changes with no API change -version: 1.0.1.2 +version: 1.0.1.3 tested-with: GHC==9.8.2, GHC==9.6.4,