diff --git a/doc/helpdb.jl b/doc/helpdb.jl index 0b2bf6702ad1a..3d61286216f2a 100644 --- a/doc/helpdb.jl +++ b/doc/helpdb.jl @@ -342,7 +342,7 @@ (E"All Objects",E"Base",E"finalizer",E"finalizer(x, function) - Register a function to be called on \"x\" when there are no + Register a function \"f(x)\" to be called when there are no program-accessible references to \"x\". The behavior of this function is unpredictable if \"x\" is of a bits type. @@ -6378,23 +6378,13 @@ eval_tab_col(glp_prob, k) "), -(E"Base.Sort",E"Base.Sort",E"sort",E"sort(v[, dim]) +(E"Base.Sort",E"Base.Sort",E"sort",E"sort(v[, alg[, ord]]) - Sort a vector in ascending order. If \"dim\" is provided, sort - along the given dimension. - -"), - -(E"Base.Sort",E"Base.Sort",E"sort",E"sort(lessthan, v[, dim]) - - Sort with a custom comparison function. - -"), - -(E"Base.Sort",E"Base.Sort",E"sort",E"sort(alg, ...) - - Sort using a specific sorting algorithm (InsertionSort, QuickSort, - MergeSort, or TimSort). + Sort a vector in ascending order. Specify \"alg\" to choose a + particular sorting algorithm (\"Sort.InsertionSort\", + \"Sort.QuickSort\", \"Sort.MergeSort\", or \"Sort.TimSort\"), and + \"ord\" to sort with a custom ordering (e.g., Sort.Reverse or a + comparison function). "), @@ -6404,17 +6394,11 @@ eval_tab_col(glp_prob, k) "), -(E"Base.Sort",E"Base.Sort",E"sortby",E"sortby(by, v[, dim]) +(E"Base.Sort",E"Base.Sort",E"sortby",E"sortby(v, by[, alg]) - Sort a vector according to \"by(v)\". If \"dim\" is provided, - sort along the given dimension. - -"), - -(E"Base.Sort",E"Base.Sort",E"sortby",E"sortby(alg, ...) - - \"sortby\" using a specific sorting algorithm (\"InsertionSort\", - \"QuickSort\", \"MergeSort\", or \"TimSort\"). + Sort a vector according to \"by(v)\". Specify \"alg\" to choose a + particular sorting algorithm (\"Sort.InsertionSort\", + \"Sort.QuickSort\", \"Sort.MergeSort\", or \"Sort.TimSort\"). "), @@ -6424,224 +6408,62 @@ eval_tab_col(glp_prob, k) "), -(E"Base.Sort",E"Base.Sort",E"sortperm",E"sortperm(v) +(E"Base.Sort",E"Base.Sort",E"sortperm",E"sortperm(v[, alg[, ord]]) Return a permutation vector, which when applied to the input vector - \"v\" will sort it. - -"), - -(E"Base.Sort",E"Base.Sort",E"sortperm",E"sortperm(lessthan, v) - - Return a permutation vector, which when applied to the input vector - \"v\" will sort it, using the specified \"lessthan\" comparison - function. - -"), - -(E"Base.Sort",E"Base.Sort",E"sortperm",E"sortperm(alg, ...) - - \"sortperm\" using a specific sorting algorithm (\"InsertionSort\", - \"QuickSort\", \"MergeSort\", or \"TimSort\"). - -"), - -(E"Base.Sort",E"Base.Sort",E"sortperm!",E"sortperm!(...) - - In-place \"sortperm\". - -"), - -(E"Base.Sort",E"Base.Sort",E"issorted",E"issorted(v) - - Test whether a vector is in ascending sorted order + \"v\" will sort it. Specify \"alg\" to choose a particular sorting + algorithm (\"Sort.InsertionSort\", \"Sort.QuickSort\", + \"Sort.MergeSort\", or \"Sort.TimSort\"), and \"ord\" to sort with + a custom ordering (e.g., Sort.Reverse or a comparison function). "), -(E"Base.Sort",E"Base.Sort",E"issortedr",E"issortedr(v) +(E"Base.Sort",E"Base.Sort",E"issorted",E"issorted(v[, ord]) - Test whether a vector is in descending sorted order + Test whether a vector is in ascending sorted order. If specified, + \"ord\" gives the ordering to test. "), -(E"Base.Sort",E"Base.Sort",E"issortedby",E"issortedby(by, v) +(E"Base.Sort",E"Base.Sort",E"searchsorted",E"searchsorted(a, x[, ord]) - Test whether a vector is sorted according to \"by(v)\". - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsorted",E"searchsorted(a, x[, lo, hi]) - - For \"a\" sorted low to high, returns the index of the first value - \">=x\". - - \"lo\" and \"hi\" optionally limit the search range. - - Alias for \"searchsortedfirst()\" - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsorted",E"searchsorted(lt, a, x[, lo, hi]) - - For \"a\" sorted using \"lt(x,y)\", returns the index of the first - value \">=x\" according to the induced order - - \"lo\" and \"hi\" optionally limit the search range. + Returns the index of the first value of \"a\" equal to or + succeeding \"x\", according to ordering \"ord\" (default: + \"Sort.Forward\"). Alias for \"searchsortedfirst()\" "), -(E"Base.Sort",E"Base.Sort",E"searchsortedr",E"searchsortedr(a, x[, lo, hi]) - - For \"a\" sorted high to low, returns the index of the first value - \"<=x\". - - \"lo\" and \"hi\" optionally limit the search range. - - Alias for \"searchsortedfirstr()\" - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedby",E"searchsortedby(by, a, x[, lo, hi]) - - For \"a\" sorted according to \"by(a)\", returns the index of the - first value \">=x\" according to the induced order. - - \"lo\" and \"hi\" optionally limit the search range. - - Alias for \"searchsortedfirstby()\" - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedfirst",E"searchsortedfirst(a, x[, lo, hi]) - - For \"a\" sorted low to high, returns the index of the first value - \">=x\". +(E"Base.Sort",E"Base.Sort",E"searchsortedfirst",E"searchsortedfirst(a, x[, ord]) - \"lo\" and \"hi\" optionally limit the search range. + Returns the index of the first value of \"a\" equal to or + succeeding \"x\", according to ordering \"ord\" (default: + \"Sort.Forward\"). "), -(E"Base.Sort",E"Base.Sort",E"searchsortedfirst",E"searchsortedfirst(lt, a, x[, lo, hi]) +(E"Base.Sort",E"Base.Sort",E"searchsortedlast",E"searchsortedlast(a, x[, ord]) - For \"a\" sorted using ordering function \"lt(x,y)\", returns the - index of the first value \">=x\" according to the induced order. - - \"lo\" and \"hi\" optionally limit the search range. - - Alias for \"searchsortedfirst()\" + Returns the index of the last value of \"a\" preceding or equal to + \"x\", according to ordering \"ord\" (default: \"Sort.Forward\"). "), -(E"Base.Sort",E"Base.Sort",E"searchsortedfirstr",E"searchsortedfirstr(a, x[, lo, hi]) - - For \"a\" sorted high to low, returns the index of the first value - \"<=x\". - - \"lo\" and \"hi\" optionally limit the search range. - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedfirstby",E"searchsortedfirstby(by, a, x[, lo, hi]) - - For \"a\" sorted according to \"by(a)\", returns the index of the - first value \">=x\" according to the induced order. - - \"lo\" and \"hi\" optionally limit the search range. - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedlast",E"searchsortedlast(a, x[, lo, hi]) - - For \"a\" sorted low to high, returns the index of the last value - \"<=x\". - - \"lo\" and \"hi\" optionally limit the search range. - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedlast",E"searchsortedlast(lt, a, x[, lo, hi]) - - For \"a\" sorted low to high, returns the index of the last value - \"<=x\" according to the induced order. - - \"lo\" and \"hi\" optionally limit the search range. - - Alias for \"searchsortedlast()\" - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedlastr",E"searchsortedlastr(a, x[, lo, hi]) - - For \"a\" sorted high to low, returns the index of the last value - \">=x\". - - \"lo\" and \"hi\" optionally limit the search range. - -"), - -(E"Base.Sort",E"Base.Sort",E"searchsortedlastby",E"searchsortedlastby(by, a, x[, lo, hi]) - - For \"a\" sorted according to \"by(a)\", returns the index of the - last value \"<=x\" according to the induced order. - - \"lo\" and \"hi\" optionally limit the search range. - -"), - -(E"Base.Sort",E"Base.Sort",E"select",E"select(v, k) +(E"Base.Sort",E"Base.Sort",E"select",E"select(v, k[, ord]) Find the element in position \"k\" in the sorted vector \"v\" - without sorting - -"), - -(E"Base.Sort",E"Base.Sort",E"select!",E"select!(v, k) - - Version of \"select\" which permutes the input vector in place. + without sorting, according to ordering \"ord\" (default: + \"Sort.Forward\"). "), -(E"Base.Sort",E"Base.Sort",E"select",E"select(lt, v, k) - - Find the element in position \"k\" in the vector \"v\" ordered by - \"lt\", without sorting. - -"), - -(E"Base.Sort",E"Base.Sort",E"select!",E"select!(lt, v, k) +(E"Base.Sort",E"Base.Sort",E"select!",E"select!(v, k[, ord]) Version of \"select\" which permutes the input vector in place. "), -(E"Base.Sort",E"Base.Sort",E"selectr",E"selectr(v, k) - - Find the element in position \"k\" in the reverse sorted vector - \"v\", without sorting. - -"), - -(E"Base.Sort",E"Base.Sort",E"selectr!",E"selectr!(v, k) - - Version of \"selectr\" which permutes the input vector in place. - -"), - -(E"Base.Sort",E"Base.Sort",E"selectby",E"selectby(by, v, k) - - Find the element in position \"k\" in the vector \"v\" as if sorted - by sortby, without sorting. - -"), - -(E"Base.Sort",E"Base.Sort",E"selectby!",E"selectby!(by, v, k) - - Version of \"selectby\" which permutes the input vector in place. - -"), - (E"Sound",E"Sound",E"wavread",E"wavread(io[, options]) Reads and returns the samples from a RIFF/WAVE file. The samples diff --git a/doc/stdlib/sort.rst b/doc/stdlib/sort.rst index 3ddcc12dca201..1b4721519a148 100644 --- a/doc/stdlib/sort.rst +++ b/doc/stdlib/sort.rst @@ -31,7 +31,7 @@ allow sorting in ascending or descending order,:: julia> sort([2,3,1]) == [1,2,3] true - julia> sortr([2,3,1]) == [3,2,1] + julia> sort(Sort.Reverse, [2,3,1]) == [3,2,1] true return a permutation,:: @@ -55,7 +55,7 @@ and use a custom extractor function to order inputs:: julia> canonicalize(s) = filter(c -> ('A'<=c<='Z' || 'a'<=c<='z'), s) | uppercase - julia> sortby(canonicalize, ["New York", "New Jersey", "Nevada", "Nebraska", "Newark"]) + julia> sortby(["New York", "New Jersey", "Nevada", "Nebraska", "Newark"], canonicalize) 5-element ASCIIString Array: "Nebraska" "Nevada" @@ -63,9 +63,10 @@ and use a custom extractor function to order inputs:: "New Jersey" "New York" -Note that none of the variants above modify the original arrays. To sort in-place (which is often more efficient), each sort function has a mutating version which ends with an exclamation point (``sort!``, ``sortr!``, and ``sortby!``). - -There are also versions of these functions which, in addition to returning a sorted array, will return the permutation of original indices which create the sorted array. These are ``sortperm``, ``sortpermr``, and ``sortpermby``, along with mutating versions ``sortperm!``, ``sortpermr!``, and ``sortpermby!``. +Note that none of the variants above modify the original arrays. To +sort in-place (which is often more efficient), each sort function has +a mutating version which ends with an exclamation point (:func:`sort!` +and :func:`sortby!`). These sort functions use reasonable default algorithms, but if you want more control or want to see if a different sort algorithm will @@ -96,7 +97,9 @@ takes advantage of sorted runs which exist in many real world datasets. The sort functions select a reasonable default algorithm, depending on -the type of the target array. +the type of the target array. To force a specific algorithm to be +used, append ``Sort.`` to the argument list (e.g., use +``sort!(v, Sort.TimSort)`` to force the use of the Timsort algorithm). Mutating and non-mutating versions of the sort functions using each of the algorithms above are exported and available for use by @@ -109,184 +112,70 @@ Functions ---------------------- General Sort Functions ---------------------- -.. function:: sort(v[, dim]) - - Sort a vector in ascending order. If ``dim`` is provided, sort - along the given dimension. - -.. function:: sort(lessthan, v[, dim]) - - Sort with a custom comparison function. - -.. function:: sort(alg, ...) +.. function:: sort(v[, alg[, ord]]) - Sort using a specific sorting algorithm (InsertionSort, QuickSort, - MergeSort, or TimSort). + Sort a vector in ascending order. Specify ``alg`` to choose a + particular sorting algorithm (``Sort.InsertionSort``, + ``Sort.QuickSort``, ``Sort.MergeSort``, or ``Sort.TimSort``), and + ``ord`` to sort with a custom ordering (e.g., Sort.Reverse or a + comparison function). .. function:: sort!(...) In-place sort. -.. function:: sortby(by, v[, dim]) +.. function:: sortby(v, by[, alg]) - Sort a vector according to ``by(v)``. If ``dim`` is provided, - sort along the given dimension. - -.. function:: sortby(alg, ...) - - ``sortby`` using a specific sorting algorithm (``InsertionSort``, - ``QuickSort``, ``MergeSort``, or ``TimSort``). + Sort a vector according to ``by(v)``. Specify ``alg`` to choose a + particular sorting algorithm (``Sort.InsertionSort``, + ``Sort.QuickSort``, ``Sort.MergeSort``, or ``Sort.TimSort``). .. function:: sortby!(...) In-place ``sortby``. -.. function:: sortperm(v) - - Return a permutation vector, which when applied to the input vector ``v`` will sort it. - -.. function:: sortperm(lessthan, v) +.. function:: sortperm(v, [alg[, ord]]) - Return a permutation vector, which when applied to the input vector ``v`` will sort it, using the specified ``lessthan`` comparison function. - -.. function:: sortperm(alg, ...) - - ``sortperm`` using a specific sorting algorithm (``InsertionSort``, - ``QuickSort``, ``MergeSort``, or ``TimSort``). - -.. function:: sortperm!(...) - - In-place ``sortperm``. + Return a permutation vector, which when applied to the input vector + ``v`` will sort it. Specify ``alg`` to choose a particular sorting + algorithm (``Sort.InsertionSort``, ``Sort.QuickSort``, + ``Sort.MergeSort``, or ``Sort.TimSort``), and ``ord`` to sort with + a custom ordering (e.g., Sort.Reverse or a comparison function). ------------------------- Sorting-related Functions ------------------------- -.. function:: issorted(v) - - Test whether a vector is in ascending sorted order - -.. function:: issortedr(v) - - Test whether a vector is in descending sorted order - -.. function:: issortedby(by,v) - - Test whether a vector is sorted according to ``by(v)``. - -.. function:: searchsorted(a, x[, lo, hi]) - - For ``a`` sorted low to high, returns the index of the first value ``>=x``. - - ``lo`` and ``hi`` optionally limit the search range. - - Alias for ``searchsortedfirst()`` - -.. function:: searchsorted(lt, a, x[, lo, hi]) - - For ``a`` sorted using ``lt(x,y)``, returns the index of the first value ``>=x`` according to the induced order - - ``lo`` and ``hi`` optionally limit the search range. - - Alias for ``searchsortedfirst()`` - -.. function:: searchsortedr(a, x[, lo, hi]) - - For ``a`` sorted high to low, returns the index of the first value ``<=x``. - - ``lo`` and ``hi`` optionally limit the search range. - - Alias for ``searchsortedfirstr()`` - -.. function:: searchsortedby(by, a, x[, lo, hi]) - - For ``a`` sorted according to ``by(a)``, returns the index of the first value ``>=x`` according to the induced order. +.. function:: issorted(v[, ord]) - ``lo`` and ``hi`` optionally limit the search range. + Test whether a vector is in ascending sorted order. If specified, + ``ord`` gives the ordering to test. - Alias for ``searchsortedfirstby()`` +.. function:: searchsorted(a, x[, ord]) -.. function:: searchsortedfirst(a, x[, lo, hi]) - - For ``a`` sorted low to high, returns the index of the first value ``>=x``. - - ``lo`` and ``hi`` optionally limit the search range. - -.. function:: searchsortedfirst(lt, a, x[, lo, hi]) - - For ``a`` sorted using ordering function ``lt(x,y)``, returns the index of the first value ``>=x`` according to the induced order. - - ``lo`` and ``hi`` optionally limit the search range. + Returns the index of the first value of ``a`` equal to or + succeeding ``x``, according to ordering ``ord`` (default: + ``Sort.Forward``). Alias for ``searchsortedfirst()`` -.. function:: searchsortedfirstr(a, x[, lo, hi]) - - For ``a`` sorted high to low, returns the index of the first value ``<=x``. - - ``lo`` and ``hi`` optionally limit the search range. - -.. function:: searchsortedfirstby(by, a, x[, lo, hi]) - - For ``a`` sorted according to ``by(a)``, returns the index of the first value ``>=x`` according to the induced order. - - ``lo`` and ``hi`` optionally limit the search range. - -.. function:: searchsortedlast(a, x[, lo, hi]) - - For ``a`` sorted low to high, returns the index of the last value ``<=x``. - - ``lo`` and ``hi`` optionally limit the search range. - -.. function:: searchsortedlast(lt, a, x[, lo, hi]) - - For ``a`` sorted low to high, returns the index of the last value ``<=x`` according to the induced order. - - ``lo`` and ``hi`` optionally limit the search range. - - Alias for ``searchsortedlast()`` +.. function:: searchsortedfirst(a, x[, ord]) -.. function:: searchsortedlastr(a, x[, lo, hi]) + Returns the index of the first value of ``a`` equal to or + succeeding ``x``, according to ordering ``ord`` (default: + ``Sort.Forward``). - For ``a`` sorted high to low, returns the index of the last value ``>=x``. +.. function:: searchsortedlast(a, x[, ord]) - ``lo`` and ``hi`` optionally limit the search range. + Returns the index of the last value of ``a`` preceding or equal to + ``x``, according to ordering ``ord`` (default: ``Sort.Forward``). -.. function:: searchsortedlastby(by, a, x[, lo, hi]) +.. function:: select(v, k[, ord]) - For ``a`` sorted according to ``by(a)``, returns the index of the last value ``<=x`` according to the induced order. + Find the element in position ``k`` in the sorted vector ``v`` + without sorting, according to ordering ``ord`` (default: + ``Sort.Forward``). - ``lo`` and ``hi`` optionally limit the search range. - -.. function:: select(v, k) - - Find the element in position ``k`` in the sorted vector ``v`` without sorting - -.. function:: select!(v, k) +.. function:: select!(v, k[, ord]) Version of ``select`` which permutes the input vector in place. - -.. function:: select(lt, v, k) - - Find the element in position ``k`` in the vector ``v`` ordered by ``lt``, without sorting. - -.. function:: select!(lt, v, k) - - Version of ``select`` which permutes the input vector in place. - -.. function:: selectr(v, k) - - Find the element in position ``k`` in the reverse sorted vector ``v``, without sorting. - -.. function:: selectr!(v, k) - - Version of ``selectr`` which permutes the input vector in place. - -.. function:: selectby(by, v, k) - - Find the element in position ``k`` in the vector ``v`` as if sorted by sortby, without sorting. - -.. function:: selectby!(by, v, k) - - Version of ``selectby`` which permutes the input vector in place. -