hare

commit 896ca140dc9300485fe5e94ad2f8b9cb730227c7
parent 66cf3ede04bfc4d4e87b6b6ead619bb7549138be
Author: Sebastian <sebastian@sebsite.pw>
Date:   Sat,  2 Apr 2022 00:05:23 -0400

sort: improve documentation

Signed-off-by: Sebastian <sebastian@sebsite.pw>

Diffstat:
M
sort/search.ha
 | 
7
++-----
M
sort/sort.ha
 | 
10
+++-------

2 files changed, 5 insertions(+), 12 deletions(-)
diff --git a/sort/search.ha b/sort/search.ha
@@ -1,11 +1,8 @@
 // License: MPL-2.0
 // (c) 2021 Drew DeVault <sir@cmpwn.com>
 
-// Performs a binary search over a sorted slice. 'in' shall be the sorted slice,
-// and 'sz' shall be the size of each array member. The 'cmp' function will be
-// called with the key value and an array member, and shall return an integer
-// less than, equal to, or greater than zero if the key is, respectively, less
-// than, equal to, or greater than the array member.
+// Performs a binary search over a sorted slice. If the key is found, a pointer
+// to the matching item in the slice is returned. Otherwise, null is returned.
 export fn search(
 	in: []const void,
 	sz: size,
diff --git a/sort/sort.ha b/sort/sort.ha
@@ -2,14 +2,10 @@
 // (c) 2021 Drew DeVault <sir@cmpwn.com>
 // (c) 2021 Steven Guikal <void@fluix.one>
 
-// Sorts a slice of items in place. Provide a slice of 'items', the size of each
-// member, and a function to compare one member to another. The 'cmp' function
-// will be called with two pointers to values within the items slice, and shall
-// return an integer less than, equal to, or greater than zero if the first
-// argument is, respectively, less than, equal to, or greater than the second
-// argument.
+// Sorts a slice of items in place.
 //
-// This implementation provides a stable sort.
+// Note that this function may (temporarily) allocate, and will abort on
+// allocation failure.
 export fn sort(items: []void, itemsz: size, cmp: *cmpfunc) void = {
 	if (len(items) < 256) {
 		insort(items, itemsz, cmp);