From 42606e5490fd37dfa14213e1d67f7237fc9958b2 Mon Sep 17 00:00:00 2001 From: Richard Barrell Date: Wed, 29 Aug 2018 09:01:57 +0100 Subject: [PATCH] Make README verbose - Add a "Parameters" section to README.md that explains each parameter one by one. Move the existing explanations of the parameters into it. - Add a section called "Return values" to README.md that explains, for each case (needle found, needle too small, needle between two elements, needle too big) what value `bs()` will return. --- README.md | 49 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e02805a..091f4a7 100644 --- a/README.md +++ b/README.md @@ -16,26 +16,53 @@ Example ```js var bs = require("binary-search"); -bs([1, 2, 3, 4], 3, function(element, needle) { return element - needle; }); +bs([1, 2, 4, 5], 4, function(element, needle) { return element - needle; }); // => 2 bs([1, 2, 4, 5], 3, function(element, needle) { return element - needle; }); // => -3 + +bs([1, 2, 4, 5], 8, function(element, needle) { return element - needle; }); +// => -5 + +bs([1, 2, 4, 5], 0, function(element, needle) { return element - needle; }); +// => -1 ``` -Be advised that passing in a comparator function is *required*. Since you're -probably using one for your sort function anyway, this isn't a big deal. +Parameters +---------- -The comparator takes a 1st and 2nd argument of element and needle, respectively. +- `haystack` - an array. `haystack` must already be sorted. +- `needle` - the value you want to search for. +- `comparator(element, needle, [index, array])` - compare an element from + `haystack` with the `needle`. + - Must return a positive number if the `element` is larger than `needle`, + - Must return `0` if they are equal, and + - Must return a negative number if `element` is smaller than `needle`. + - The comparator function will often be the same function that was used to + sort `haystack`. If not, it must rank elements in the same order as the + comparator that was used to sort `haystack`. + - You shouldn't normally need the index or array to compare values, but they + are there if you do. +- `minimumIndex` - (optional) - the index of the smallest element in `haystack` + which should be included in the search. By default this is 0. +- `maximumIndex` - (optional) - the index of the largest element in `haystack` + which should be included in the search. By default this is `haystack.length - 1` + - `minimumIndex` and `maximumIndex` let you specify an input range, in case + you want to limit the search to a particular range of inputs. + - Be advised that this is generally a bad idea. + - (But sometimes bad ideas are necessary.) + - By default `bs()` will search the entire `haystack`. -The comparator also takes a 3rd and 4th argument, the current index and array, -respectively. You shouldn't normally need the index or array to compare values, -but it's there if you do. +Return values +------------- -You may also, optionally, specify an input range as the final two parameters, -in case you want to limit the search to a particular range of inputs. However, -be advised that this is generally a bad idea (but sometimes bad ideas are -necessary). +- If the needle is equal to an element in the haystack, `bs()` will return that element's index. +- If the needle is smaller than any element of the haystack, `bs()` returns `minimumIndex - 1`. + - If you didn't specify `minimumIndex` and `maximumIndex`, the return value will be `-1` in this case. +- If the needle is larger than any element of the haystack, `bs()` returns `-1 * (largestIndex + 2)`, where `largestIndex` is the index of the last element in the haystack. + - If you didn't specify `minimumIndex` and `maximumIndex`, the return value will be `-1 * (haystack.length + 1)`. +- If the needle is in between two elements of the haystack, `bs()` returns `-1 * (largerIndex + 1)`, where `largerIndex` is the index of the larger or the two elements which the `needle` sits between. License -------