jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Algorithm improvements (#16529)

Browse source 
* Improve documentation for algorithm

Remove unused import in algorithm tests
Improve formatting

* Reapply fix for reverse on empty openArray

* Use 3rd person singular

Add more explanations.
This commit is contained in:
konsumlamm 2021-01-02 20:28:59 +01:00 • committed by GitHub
commit 2eccef7ad6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 144 additions and 136 deletions
Download patch file Download diff file Expand all files Collapse all files

258
lib/pure/algorithm.nim
View file

@ -7,7 +7,7 @@
# distribution, for details about the copyright. # distribution, for details about the copyright.
# #
## This module implements some common generic algorithms. ## This module implements some common generic algorithms on `openArray`s.
## ##
## Basic usage ## Basic usage
## =========== ## ===========
@ -30,9 +30,7 @@ runnableExamples:
(year: 2010, name: "Jane")] (year: 2010, name: "Jane")]
proc myCmp(x, y: People): int = proc myCmp(x, y: People): int =
if x.name < y.name: -1 cmp(x.name, y.name)
elif x.name == y.name: 0
else: 1
# Sorting with custom proc # Sorting with custom proc
a.sort(myCmp) a.sort(myCmp)
@ -49,18 +47,18 @@ type
Descending, Ascending Descending, Ascending
proc `*`*(x: int, order: SortOrder): int {.inline.} = proc `*`*(x: int, order: SortOrder): int {.inline.} =
## Flips ``x`` if ``order == Descending``. ## Flips the sign of `x` if `order == Descending`.
## If ``order == Ascending`` then ``x`` is returned. ## If `order == Ascending` then `x` is returned.
## ##
## ``x`` is supposed to be the result of a comparator, i.e. ## `x` is supposed to be the result of a comparator, i.e.
## | ``< 0`` for *less than*, ## | `< 0` for *less than*,
## | ``== 0`` for *equal*, ## | `== 0` for *equal*,
## | ``> 0`` for *greater than*. ## | `> 0` for *greater than*.
runnableExamples: runnableExamples:
assert `*`(-123, Descending) == 123 assert -123 * Descending == 123
assert `*`(123, Descending) == -123 assert 123 * Descending == -123
assert `*`(-123, Ascending) == -123 assert -123 * Ascending == -123
assert `*`(123, Ascending) == 123 assert 123 * Ascending == 123
var y = order.ord - 1 var y = order.ord - 1
result = (x xor y) - y result = (x xor y) - y
@ -71,9 +69,9 @@ template fillImpl[T](a: var openArray[T], first, last: int, value: T) =
inc(x) inc(x)
proc fill*[T](a: var openArray[T], first, last: Natural, value: T) = proc fill*[T](a: var openArray[T], first, last: Natural, value: T) =
## Fills the slice ``a[first..last]`` with ``value``. ## Assigns `value` to all elements of the slice `a[first..last]`.
## ##
## If an invalid range is passed, it raises IndexDefect. ## If an invalid range is passed, it raises `IndexDefect`.
runnableExamples: runnableExamples:
var a: array[6, int] var a: array[6, int]
a.fill(1, 3, 9) a.fill(1, 3, 9)
@ -84,7 +82,7 @@ proc fill*[T](a: var openArray[T], first, last: Natural, value: T) =
fillImpl(a, first, last, value) fillImpl(a, first, last, value)
proc fill*[T](a: var openArray[T], value: T) = proc fill*[T](a: var openArray[T], value: T) =
## Fills the container ``a`` with ``value``. ## Assigns `value` to all elements of the container `a`.
runnableExamples: runnableExamples:
var a: array[6, int] var a: array[6, int]
a.fill(9) a.fill(9)
@ -95,13 +93,13 @@ proc fill*[T](a: var openArray[T], value: T) =
proc reverse*[T](a: var openArray[T], first, last: Natural) = proc reverse*[T](a: var openArray[T], first, last: Natural) =
## Reverses the slice ``a[first..last]``. ## Reverses the slice `a[first..last]`.
## ##
## If an invalid range is passed, it raises IndexDefect. ## If an invalid range is passed, it raises `IndexDefect`.
## ##
## **See also:** ## **See also:**
## * `reversed proc<#reversed,openArray[T],Natural,int>`_ reverse a slice and returns a ``seq[T]`` ## * `reversed proc<#reversed,openArray[T],Natural,int>`_ reverse a slice and returns a `seq[T]`
## * `reversed proc<#reversed,openArray[T]>`_ reverse and returns a ``seq[T]`` ## * `reversed proc<#reversed,openArray[T]>`_ reverse and returns a `seq[T]`
runnableExamples: runnableExamples:
var a = [1, 2, 3, 4, 5, 6] var a = [1, 2, 3, 4, 5, 6]
a.reverse(1, 3) a.reverse(1, 3)
@ -117,23 +115,24 @@ proc reverse*[T](a: var openArray[T], first, last: Natural) =
inc(x) inc(x)
proc reverse*[T](a: var openArray[T]) = proc reverse*[T](a: var openArray[T]) =
## Reverses the contents of the container ``a``. ## Reverses the contents of the container `a`.
## ##
## **See also:** ## **See also:**
## * `reversed proc<#reversed,openArray[T],Natural,int>`_ reverse a slice and returns a ``seq[T]`` ## * `reversed proc<#reversed,openArray[T],Natural,int>`_ reverse a slice and returns a `seq[T]`
## * `reversed proc<#reversed,openArray[T]>`_ reverse and returns a ``seq[T]`` ## * `reversed proc<#reversed,openArray[T]>`_ reverse and returns a `seq[T]`
runnableExamples: runnableExamples:
var a = [1, 2, 3, 4, 5, 6] var a = [1, 2, 3, 4, 5, 6]
a.reverse() a.reverse()
assert a == [6, 5, 4, 3, 2, 1] assert a == [6, 5, 4, 3, 2, 1]
a.reverse() a.reverse()
assert a == [1, 2, 3, 4, 5, 6] assert a == [1, 2, 3, 4, 5, 6]
# the max is needed, since a.high is -1 if a is empty
reverse(a, 0, max(0, a.high)) reverse(a, 0, max(0, a.high))
proc reversed*[T](a: openArray[T], first: Natural, last: int): seq[T] = proc reversed*[T](a: openArray[T], first: Natural, last: int): seq[T] =
## Returns the reverse of the slice ``a[first..last]``. ## Returns the reverse of the slice `a[first..last]`.
## ##
## If an invalid range is passed, it raises IndexDefect. ## If an invalid range is passed, it raises `IndexDefect`.
## ##
## **See also:** ## **See also:**
## * `reverse proc<#reverse,openArray[T],Natural,Natural>`_ reverse a slice ## * `reverse proc<#reverse,openArray[T],Natural,Natural>`_ reverse a slice
@ -153,7 +152,7 @@ proc reversed*[T](a: openArray[T], first: Natural, last: int): seq[T] =
inc(x) inc(x)
proc reversed*[T](a: openArray[T]): seq[T] = proc reversed*[T](a: openArray[T]): seq[T] =
## Returns the reverse of the container ``a``. ## Returns the reverse of the container `a`.
## ##
## **See also:** ## **See also:**
## * `reverse proc<#reverse,openArray[T],Natural,Natural>`_ reverse a slice ## * `reverse proc<#reverse,openArray[T],Natural,Natural>`_ reverse a slice
@ -167,18 +166,19 @@ proc reversed*[T](a: openArray[T]): seq[T] =
proc binarySearch*[T, K](a: openArray[T], key: K, proc binarySearch*[T, K](a: openArray[T], key: K,
cmp: proc (x: T, y: K): int {.closure.}): int = cmp: proc (x: T, y: K): int {.closure.}): int =
## Binary search for ``key`` in ``a``. Returns -1 if not found. ## Binary search for `key` in `a`. Return the index of `key` or -1 if not found.
## Assumes that `a` is sorted according to `cmp`.
## ##
## ``cmp`` is the comparator function to use, the expected return values are ## `cmp` is the comparator function to use, the expected return values are
## the same as that of system.cmp. ## the same as those of system.cmp.
runnableExamples: runnableExamples:
assert binarySearch(["a", "b", "c", "d"], "d", system.cmp[string]) == 3 assert binarySearch(["a", "b", "c", "d"], "d", system.cmp[string]) == 3
assert binarySearch(["a", "b", "d", "c"], "d", system.cmp[string]) == 2 assert binarySearch(["a", "b", "c", "d"], "c", system.cmp[string]) == 2
if a.len == 0:
return -1
let len = a.len let len = a.len
if len == 0:
return -1
if len == 1: if len == 1:
if cmp(a[0], key) == 0: if cmp(a[0], key) == 0:
return 0 return 0
@ -196,7 +196,7 @@ proc binarySearch*[T, K](a: openArray[T], key: K,
if cmpRes == 0: if cmpRes == 0:
return i return i
if cmpRes < 1: if cmpRes < 0:
result = i result = i
step = step shr 1 step = step shr 1
if cmp(a[result], key) != 0: result = -1 if cmp(a[result], key) != 0: result = -1
@ -216,30 +216,32 @@ proc binarySearch*[T, K](a: openArray[T], key: K,
if result >= len or cmp(a[result], key) != 0: result = -1 if result >= len or cmp(a[result], key) != 0: result = -1
proc binarySearch*[T](a: openArray[T], key: T): int = proc binarySearch*[T](a: openArray[T], key: T): int =
## Binary search for ``key`` in ``a``. Returns -1 if not found. ## Binary search for `key` in `a`. Return the index of `key` or -1 if not found.
## Assumes that `a` is sorted.
runnableExamples: runnableExamples:
assert binarySearch([0, 1, 2, 3, 4], 4) == 4 assert binarySearch([0, 1, 2, 3, 4], 4) == 4
assert binarySearch([0, 1, 4, 2, 3], 4) == 2 assert binarySearch([0, 1, 2, 3, 4], 2) == 2
binarySearch(a, key, cmp[T]) binarySearch(a, key, cmp[T])
const const
onlySafeCode = true onlySafeCode = true
proc lowerBound*[T, K](a: openArray[T], key: K, cmp: proc(x: T, k: K): int {. proc lowerBound*[T, K](a: openArray[T], key: K,
closure.}): int = cmp: proc(x: T, k: K): int {.closure.}): int =
## Returns a position to the first element in the ``a`` that is greater than ## Returns the index of the first element in `a` that is not less than
## ``key``, or last if no such element is found. ## (i.e. greater or equal to) `key`, or last if no such element is found.
## In other words if you have a sorted sequence and you call ## In other words if you have a sorted sequence and you call
## ``insert(thing, elm, lowerBound(thing, elm))`` ## `insert(thing, elm, lowerBound(thing, elm))`
## the sequence will still be sorted. ## the sequence will still be sorted.
## Assumes that `a` is sorted according to `cmp`.
## ##
## If an invalid range is passed, it raises IndexDefect. ## If an invalid range is passed, it raises `IndexDefect`.
## ##
## The version uses ``cmp`` to compare the elements. ## This version uses `cmp` to compare the elements.
## The expected return values are the same as that of ``system.cmp``. ## The expected return values are the same as those of `system.cmp`.
## ##
## **See also:** ## **See also:**
## * `upperBound proc<#upperBound,openArray[T],K,proc(T,K)>`_ sorted by ``cmp`` in the specified order ## * `upperBound proc<#upperBound,openArray[T],K,proc(T,K)>`_ sorted by `cmp` in the specified order
## * `upperBound proc<#upperBound,openArray[T],T>`_ ## * `upperBound proc<#upperBound,openArray[T],T>`_
runnableExamples: runnableExamples:
var arr = @[1, 2, 3, 5, 6, 7, 8, 9] var arr = @[1, 2, 3, 5, 6, 7, 8, 9]
@ -261,33 +263,35 @@ proc lowerBound*[T, K](a: openArray[T], key: K, cmp: proc(x: T, k: K): int {.
count = step count = step
proc lowerBound*[T](a: openArray[T], key: T): int = lowerBound(a, key, cmp[T]) proc lowerBound*[T](a: openArray[T], key: T): int = lowerBound(a, key, cmp[T])
## Returns a position to the first element in the ``a`` that is greater than ## Returns the index of the first element in `a` that is not less than
## ``key``, or last if no such element is found. ## (i.e. greater or equal to) `key`, or last if no such element is found.
## In other words if you have a sorted sequence and you call ## In other words if you have a sorted sequence and you call
## ``insert(thing, elm, lowerBound(thing, elm))`` ## `insert(thing, elm, lowerBound(thing, elm))`
## the sequence will still be sorted. ## the sequence will still be sorted.
## Assumes that `a` is sorted.
## ##
## The version uses the default comparison function ``cmp``. ## This version uses the default comparison function `cmp`.
## ##
## **See also:** ## **See also:**
## * `upperBound proc<#upperBound,openArray[T],K,proc(T,K)>`_ sorted by ``cmp`` in the specified order ## * `upperBound proc<#upperBound,openArray[T],K,proc(T,K)>`_ sorted by `cmp` in the specified order
## * `upperBound proc<#upperBound,openArray[T],T>`_ ## * `upperBound proc<#upperBound,openArray[T],T>`_
proc upperBound*[T, K](a: openArray[T], key: K, cmp: proc(x: T, k: K): int {. proc upperBound*[T, K](a: openArray[T], key: K,
closure.}): int = cmp: proc(x: T, k: K): int {.closure.}): int =
## Returns a position to the first element in the ``a`` that is not less ## Returns the index of the first element in `a` that is greater than
## (i.e. greater or equal to) than ``key``, or last if no such element is found. ## `key`, or last if no such element is found.
## In other words if you have a sorted sequence and you call ## In other words if you have a sorted sequence and you call
## ``insert(thing, elm, upperBound(thing, elm))`` ## `insert(thing, elm, upperBound(thing, elm))`
## the sequence will still be sorted. ## the sequence will still be sorted.
## Assumes that `a` is sorted according to `cmp`.
## ##
## If an invalid range is passed, it raises IndexDefect. ## If an invalid range is passed, it raises `IndexDefect`.
## ##
## The version uses ``cmp`` to compare the elements. The expected ## This version uses `cmp` to compare the elements. The expected
## return values are the same as that of ``system.cmp``. ## return values are the same as those of `system.cmp`.
## ##
## **See also:** ## **See also:**
## * `lowerBound proc<#lowerBound,openArray[T],K,proc(T,K)>`_ sorted by ``cmp`` in the specified order ## * `lowerBound proc<#lowerBound,openArray[T],K,proc(T,K)>`_ sorted by `cmp` in the specified order
## * `lowerBound proc<#lowerBound,openArray[T],T>`_ ## * `lowerBound proc<#lowerBound,openArray[T],T>`_
runnableExamples: runnableExamples:
var arr = @[1, 2, 3, 5, 6, 7, 8, 9] var arr = @[1, 2, 3, 5, 6, 7, 8, 9]
@ -309,16 +313,17 @@ proc upperBound*[T, K](a: openArray[T], key: K, cmp: proc(x: T, k: K): int {.
count = step count = step
proc upperBound*[T](a: openArray[T], key: T): int = upperBound(a, key, cmp[T]) proc upperBound*[T](a: openArray[T], key: T): int = upperBound(a, key, cmp[T])
## Returns a position to the first element in the ``a`` that is not less ## Returns the index of the first element in `a` that is greater than
## (i.e. greater or equal to) than ``key``, or last if no such element is found. ## `key`, or last if no such element is found.
## In other words if you have a sorted sequence and you call ## In other words if you have a sorted sequence and you call
## ``insert(thing, elm, upperBound(thing, elm))`` ## `insert(thing, elm, upperBound(thing, elm))`
## the sequence will still be sorted. ## the sequence will still be sorted.
## Assumes that `a` is sorted.
## ##
## The version uses the default comparison function ``cmp``. ## This version uses the default comparison function `cmp`.
## ##
## **See also:** ## **See also:**
## * `lowerBound proc<#lowerBound,openArray[T],K,proc(T,K)>`_ sorted by ``cmp`` in the specified order ## * `lowerBound proc<#lowerBound,openArray[T],K,proc(T,K)>`_ sorted by `cmp` in the specified order
## * `lowerBound proc<#lowerBound,openArray[T],T>`_ ## * `lowerBound proc<#lowerBound,openArray[T],T>`_
template `<-`(a, b) = template `<-`(a, b) =
@ -331,10 +336,10 @@ template `<-` (a, b) =
proc merge[T](a, b: var openArray[T], lo, m, hi: int, proc merge[T](a, b: var openArray[T], lo, m, hi: int,
cmp: proc (x, y: T): int {.closure.}, order: SortOrder) = cmp: proc (x, y: T): int {.closure.}, order: SortOrder) =
# optimization: If max(left) <= min(right) there is nothing to do! # Optimization: If max(left) <= min(right) there is nothing to do!
# 1 2 3 4 ## 5 6 7 8 # 1 2 3 4 ## 5 6 7 8
# -> O(n) for sorted arrays. # -> O(n) for sorted arrays.
# On random data this safes up to 40% of merge calls # On random data this saves up to 40% of merge calls.
if cmp(a[m], a[m+1]) * order <= 0: return if cmp(a[m], a[m+1]) * order <= 0: return
var j = lo var j = lo
# copy a[j..m] into b: # copy a[j..m] into b:
@ -372,14 +377,15 @@ func sort*[T](a: var openArray[T],
cmp: proc (x, y: T): int {.closure.}, cmp: proc (x, y: T): int {.closure.},
order = SortOrder.Ascending) = order = SortOrder.Ascending) =
## Default Nim sort (an implementation of merge sort). The sorting ## Default Nim sort (an implementation of merge sort). The sorting
## is guaranteed to be stable and the worst case is guaranteed to ## is guaranteed to be stable (that is, equal elements stay in the same order)
## be O(n log n). ## and the worst case is guaranteed to be O(n log n).
## Sorts by `cmp` in the specified `order`.
## ##
## The current implementation uses an iterative ## The current implementation uses an iterative
## mergesort to achieve this. It uses a temporary sequence of ## mergesort to achieve this. It uses a temporary sequence of
## length ``a.len div 2``. If you do not wish to provide your own ## length `a.len div 2`. If you do not wish to provide your own
## ``cmp``, you may use ``system.cmp`` or instead call the overloaded ## `cmp`, you may use `system.cmp` or instead call the overloaded
## version of ``sort``, which uses ``system.cmp``. ## version of `sort`, which uses `system.cmp`.
## ##
## .. code-block:: nim ## .. code-block:: nim
## ##
@ -400,7 +406,7 @@ func sort*[T](a: var openArray[T],
## ##
## **See also:** ## **See also:**
## * `sort proc<#sort,openArray[T]>`_ ## * `sort proc<#sort,openArray[T]>`_
## * `sorted proc<#sorted,openArray[T],proc(T,T)>`_ sorted by ``cmp`` in the specified order ## * `sorted proc<#sorted,openArray[T],proc(T,T)>`_ sorted by `cmp` in the specified order
## * `sorted proc<#sorted,openArray[T]>`_ ## * `sorted proc<#sorted,openArray[T]>`_
## * `sortedByIt template<#sortedByIt.t,untyped,untyped>`_ ## * `sortedByIt template<#sortedByIt.t,untyped,untyped>`_
runnableExamples: runnableExamples:
@ -411,8 +417,7 @@ func sort*[T](a: var openArray[T],
sort(d, myCmp) sort(d, myCmp)
assert d == ["fo", "qux", "boo", "barr"] assert d == ["fo", "qux", "boo", "barr"]
var n = a.len var n = a.len
var b: seq[T] var b = newSeq[T](n div 2)
newSeq(b, n div 2)
var s = 1 var s = 1
while s < n: while s < n:
var m = n-1-s var m = n-1-s
@ -423,17 +428,17 @@ func sort*[T](a: var openArray[T],
proc sort*[T](a: var openArray[T], order = SortOrder.Ascending) = sort[T](a, proc sort*[T](a: var openArray[T], order = SortOrder.Ascending) = sort[T](a,
system.cmp[T], order) system.cmp[T], order)
## Shortcut version of ``sort`` that uses ``system.cmp[T]`` as the comparison function. ## Shortcut version of `sort` that uses `system.cmp[T]` as the comparison function.
## ##
## **See also:** ## **See also:**
## * `sort func<#sort,openArray[T],proc(T,T)>`_ ## * `sort func<#sort,openArray[T],proc(T,T)>`_
## * `sorted proc<#sorted,openArray[T],proc(T,T)>`_ sorted by ``cmp`` in the specified order ## * `sorted proc<#sorted,openArray[T],proc(T,T)>`_ sorted by `cmp` in the specified order
## * `sorted proc<#sorted,openArray[T]>`_ ## * `sorted proc<#sorted,openArray[T]>`_
## * `sortedByIt template<#sortedByIt.t,untyped,untyped>`_ ## * `sortedByIt template<#sortedByIt.t,untyped,untyped>`_
proc sorted*[T](a: openArray[T], cmp: proc(x, y: T): int {.closure.}, proc sorted*[T](a: openArray[T], cmp: proc(x, y: T): int {.closure.},
order = SortOrder.Ascending): seq[T] = order = SortOrder.Ascending): seq[T] =
## Returns ``a`` sorted by ``cmp`` in the specified ``order``. ## Returns `a` sorted by `cmp` in the specified `order`.
## ##
## **See also:** ## **See also:**
## * `sort func<#sort,openArray[T],proc(T,T)>`_ ## * `sort func<#sort,openArray[T],proc(T,T)>`_
@ -454,7 +459,7 @@ proc sorted*[T](a: openArray[T], cmp: proc(x, y: T): int {.closure.},
sort(result, cmp, order) sort(result, cmp, order)
proc sorted*[T](a: openArray[T], order = SortOrder.Ascending): seq[T] = proc sorted*[T](a: openArray[T], order = SortOrder.Ascending): seq[T] =
## Shortcut version of ``sorted`` that uses ``system.cmp[T]`` as the comparison function. ## Shortcut version of `sorted` that uses `system.cmp[T]` as the comparison function.
## ##
## **See also:** ## **See also:**
## * `sort func<#sort,openArray[T],proc(T,T)>`_ ## * `sort func<#sort,openArray[T],proc(T,T)>`_
@ -472,18 +477,18 @@ proc sorted*[T](a: openArray[T], order = SortOrder.Ascending): seq[T] =
sorted[T](a, system.cmp[T], order) sorted[T](a, system.cmp[T], order)
template sortedByIt*(seq1, op: untyped): untyped = template sortedByIt*(seq1, op: untyped): untyped =
## Convenience template around the ``sorted`` proc to reduce typing. ## Convenience template around the `sorted` proc to reduce typing.
## ##
## The template injects the ``it`` variable which you can use directly in an ## The template injects the `it` variable which you can use directly in an
## expression. ## expression.
## ##
## Because the underlying ``cmp()`` is defined for tuples you can do ## Because the underlying `cmp()` is defined for tuples you can also do
## a nested sort. ## a nested sort.
## ##
## **See also:** ## **See also:**
## * `sort func<#sort,openArray[T],proc(T,T)>`_ ## * `sort func<#sort,openArray[T],proc(T,T)>`_
## * `sort proc<#sort,openArray[T]>`_ ## * `sort proc<#sort,openArray[T]>`_
## * `sorted proc<#sorted,openArray[T],proc(T,T)>`_ sorted by ``cmp`` in the specified order ## * `sorted proc<#sorted,openArray[T],proc(T,T)>`_ sorted by `cmp` in the specified order
## * `sorted proc<#sorted,openArray[T]>`_ ## * `sorted proc<#sorted,openArray[T]>`_
runnableExamples: runnableExamples:
type Person = tuple[name: string, age: int] type Person = tuple[name: string, age: int]
@ -510,9 +515,9 @@ template sortedByIt*(seq1, op: untyped): untyped =
func isSorted*[T](a: openArray[T], func isSorted*[T](a: openArray[T],
cmp: proc(x, y: T): int {.closure.}, cmp: proc(x, y: T): int {.closure.},
order = SortOrder.Ascending): bool = order = SortOrder.Ascending): bool =
## Checks to see whether ``a`` is already sorted in ``order`` ## Checks to see whether `a` is already sorted in `order`
## using ``cmp`` for the comparison. Parameters identical ## using `cmp` for the comparison. The parameters are identical
## to ``sort``. Requires O(n) time. ## to `sort`. Requires O(n) time.
## ##
## **See also:** ## **See also:**
## * `isSorted proc<#isSorted,openArray[T]>`_ ## * `isSorted proc<#isSorted,openArray[T]>`_
@ -535,7 +540,7 @@ func isSorted*[T](a: openArray[T],
return false return false
proc isSorted*[T](a: openArray[T], order = SortOrder.Ascending): bool = proc isSorted*[T](a: openArray[T], order = SortOrder.Ascending): bool =
## Shortcut version of ``isSorted`` that uses ``system.cmp[T]`` as the comparison function. ## Shortcut version of `isSorted` that uses `system.cmp[T]` as the comparison function.
## ##
## **See also:** ## **See also:**
## * `isSorted func<#isSorted,openArray[T],proc(T,T)>`_ ## * `isSorted func<#isSorted,openArray[T],proc(T,T)>`_
@ -555,8 +560,10 @@ proc isSorted*[T](a: openArray[T], order = SortOrder.Ascending): bool =
isSorted(a, system.cmp[T], order) isSorted(a, system.cmp[T], order)
proc product*[T](x: openArray[seq[T]]): seq[seq[T]] = proc product*[T](x: openArray[seq[T]]): seq[seq[T]] =
## Produces the Cartesian product of the array. Warning: complexity ## Produces the Cartesian product of the array.
## may explode. ## Every element of the result is a combination of one element from each seq in `x`,
## with the ith element coming from `x[i]`.
## Warning: complexity may explode.
runnableExamples: runnableExamples:
assert product(@[@[1], @[2]]) == @[@[1, 2]] assert product(@[@[1], @[2]]) == @[@[1, 2]]
assert product(@[@["A", "K"], @["Q"]]) == @[@["K", "Q"], @["A", "Q"]] assert product(@[@["A", "K"], @["Q"]]) == @[@["K", "Q"], @["A", "Q"]]
@ -567,34 +574,33 @@ proc product*[T](x: openArray[seq[T]]): seq[seq[T]] =
result = @x result = @x
return return
var var
indexes = newSeq[int](x.len) indices = newSeq[int](x.len)
initial = newSeq[int](x.len) initial = newSeq[int](x.len)
index = 0 index = 0
var next = newSeq[T]() var next = newSeq[T](x.len)
next.setLen(x.len)
for i in 0..(x.len-1): for i in 0..(x.len-1):
if len(x[i]) == 0: return if len(x[i]) == 0: return
initial[i] = len(x[i]) - 1 initial[i] = len(x[i]) - 1
indexes = initial indices = initial
while true: while true:
while indexes[index] == -1: while indices[index] == -1:
indexes[index] = initial[index] indices[index] = initial[index]
index += 1 index += 1
if index == x.len: return if index == x.len: return
indexes[index] -= 1 indices[index] -= 1
for ni, i in indexes: for ni, i in indices:
next[ni] = x[ni][i] next[ni] = x[ni][i]
result.add(next) result.add(next)
index = 0 index = 0
indexes[index] -= 1 indices[index] -= 1
proc nextPermutation*[T](x: var openArray[T]): bool {.discardable.} = proc nextPermutation*[T](x: var openArray[T]): bool {.discardable.} =
## Calculates the next lexicographic permutation, directly modifying ``x``. ## Calculates the next lexicographic permutation, directly modifying `x`.
## The result is whether a permutation happened, otherwise we have reached ## The result is whether a permutation happened, otherwise we have reached
## the last-ordered permutation. ## the last-ordered permutation.
## ##
## If you start with an unsorted array/seq, the repeated permutations ## If you start with an unsorted array/seq, the repeated permutations
## will **not** give you all permutations but stop with last. ## will **not** give you all permutations but stop with the last.
## ##
## **See also:** ## **See also:**
## * `prevPermutation proc<#prevPermutation,openArray[T]>`_ ## * `prevPermutation proc<#prevPermutation,openArray[T]>`_
@ -630,7 +636,7 @@ proc nextPermutation*[T](x: var openArray[T]): bool {.discardable.} =
proc prevPermutation*[T](x: var openArray[T]): bool {.discardable.} = proc prevPermutation*[T](x: var openArray[T]): bool {.discardable.} =
## Calculates the previous lexicographic permutation, directly modifying ## Calculates the previous lexicographic permutation, directly modifying
## ``x``. The result is whether a permutation happened, otherwise we have ## `x`. The result is whether a permutation happened, otherwise we have
## reached the first-ordered permutation. ## reached the first-ordered permutation.
## ##
## **See also:** ## **See also:**
@ -664,7 +670,8 @@ proc prevPermutation*[T](x: var openArray[T]): bool {.discardable.} =
result = true result = true
proc rotateInternal[T](arg: var openArray[T]; first, middle, last: int): int = proc rotateInternal[T](arg: var openArray[T]; first, middle, last: int): int =
## A port of std::rotate from c++. Ported from `this reference <http://www.cplusplus.com/reference/algorithm/rotate/>`_. ## A port of std::rotate from C++.
## Ported from [this reference](http://www.cplusplus.com/reference/algorithm/rotate/).
result = first + last - middle result = first + last - middle
if first == middle or middle == last: if first == middle or middle == last:
@ -718,28 +725,28 @@ proc rotatedInternal[T](arg: openArray[T]; first, middle, last: int): seq[T] =
proc rotateLeft*[T](arg: var openArray[T]; slice: HSlice[int, int]; proc rotateLeft*[T](arg: var openArray[T]; slice: HSlice[int, int];
dist: int): int {.discardable.} = dist: int): int {.discardable.} =
## Performs a left rotation on a range of elements. If you want to rotate ## Performs a left rotation on a range of elements. If you want to rotate
## right, use a negative ``dist``. Specifically, ``rotateLeft`` rotates ## right, use a negative `dist`. Specifically, `rotateLeft` rotates
## the elements at ``slice`` by ``dist`` positions. ## the elements at `slice` by `dist` positions.
## ##
## | The element at index ``slice.a + dist`` will be at index ``slice.a``. ## | The element at index `slice.a + dist` will be at index `slice.a`.
## | The element at index ``slice.b`` will be at ``slice.a + dist -1``. ## | The element at index `slice.b` will be at `slice.a + dist - 1`.
## | The element at index ``slice.a`` will be at ``slice.b + 1 - dist``. ## | The element at index `slice.a` will be at `slice.b + 1 - dist`.
## | The element at index ``slice.a + dist - 1`` will be at ``slice.b``. ## | The element at index `slice.a + dist - 1` will be at `slice.b`.
## ##
## Elements outside of ``slice`` will be left unchanged. ## Elements outside of `slice` will be left unchanged.
## The time complexity is linear to ``slice.b - slice.a + 1``. ## The time complexity is linear to `slice.b - slice.a + 1`.
## If an invalid range (``HSlice``) is passed, it raises IndexDefect. ## If an invalid range (`HSlice`) is passed, it raises `IndexDefect`.
## ##
## ``slice`` ## `slice`
## The indices of the element range that should be rotated. ## The indices of the element range that should be rotated.
## ##
## ``dist`` ## `dist`
## The distance in amount of elements that the data should be rotated. ## The distance in amount of elements that the data should be rotated.
## Can be negative, can be any number. ## Can be negative, can be any number.
## ##
## **See also:** ## **See also:**
## * `rotateLeft proc<#rotateLeft,openArray[T],int>`_ for a version which rotates the whole container ## * `rotateLeft proc<#rotateLeft,openArray[T],int>`_ for a version which rotates the whole container
## * `rotatedLeft proc<#rotatedLeft,openArray[T],HSlice[int,int],int>`_ for a version which returns a ``seq[T]`` ## * `rotatedLeft proc<#rotatedLeft,openArray[T],HSlice[int,int],int>`_ for a version which returns a `seq[T]`
runnableExamples: runnableExamples:
var a = [0, 1, 2, 3, 4, 5] var a = [0, 1, 2, 3, 4, 5]
a.rotateLeft(1 .. 4, 3) a.rotateLeft(1 .. 4, 3)
@ -754,12 +761,13 @@ proc rotateLeft*[T](arg: var openArray[T]; slice: HSlice[int, int];
arg.rotateInternal(slice.a, slice.a + distLeft, slice.b + 1) arg.rotateInternal(slice.a, slice.a + distLeft, slice.b + 1)
proc rotateLeft*[T](arg: var openArray[T]; dist: int): int {.discardable.} = proc rotateLeft*[T](arg: var openArray[T]; dist: int): int {.discardable.} =
## Default arguments for slice, so that this procedure operates on the entire ## Same as `rotateLeft`, but with default arguments for slice,
## ``arg``, and not just on a part of it. ## so that this procedure operates on the entire
## `arg`, and not just on a part of it.
## ##
## **See also:** ## **See also:**
## * `rotateLeft proc<#rotateLeft,openArray[T],HSlice[int,int],int>`_ for a version which rotates a range ## * `rotateLeft proc<#rotateLeft,openArray[T],HSlice[int,int],int>`_ for a version which rotates a range
## * `rotatedLeft proc<#rotatedLeft,openArray[T],int>`_ for a version which returns a ``seq[T]`` ## * `rotatedLeft proc<#rotatedLeft,openArray[T],int>`_ for a version which returns a `seq[T]`
runnableExamples: runnableExamples:
var a = [1, 2, 3, 4, 5] var a = [1, 2, 3, 4, 5]
a.rotateLeft(2) a.rotateLeft(2)
@ -774,16 +782,16 @@ proc rotateLeft*[T](arg: var openArray[T]; dist: int): int {.discardable.} =
proc rotatedLeft*[T](arg: openArray[T]; slice: HSlice[int, int], proc rotatedLeft*[T](arg: openArray[T]; slice: HSlice[int, int],
dist: int): seq[T] = dist: int): seq[T] =
## Same as ``rotateLeft``, just with the difference that it does ## Same as `rotateLeft`, just with the difference that it does
## not modify the argument. It creates a new ``seq`` instead. ## not modify the argument. It creates a new `seq` instead.
## ##
## Elements outside of ``slice`` will be left unchanged. ## Elements outside of `slice` will be left unchanged.
## If an invalid range (``HSlice``) is passed, it raises IndexDefect. ## If an invalid range (`HSlice`) is passed, it raises `IndexDefect`.
## ##
## ``slice`` ## `slice`
## The indices of the element range that should be rotated. ## The indices of the element range that should be rotated.
## ##
## ``dist`` ## `dist`
## The distance in amount of elements that the data should be rotated. ## The distance in amount of elements that the data should be rotated.
## Can be negative, can be any number. ## Can be negative, can be any number.
## ##
@ -803,8 +811,8 @@ proc rotatedLeft*[T](arg: openArray[T]; slice: HSlice[int, int],
arg.rotatedInternal(slice.a, slice.a+distLeft, slice.b+1) arg.rotatedInternal(slice.a, slice.a+distLeft, slice.b+1)
proc rotatedLeft*[T](arg: openArray[T]; dist: int): seq[T] = proc rotatedLeft*[T](arg: openArray[T]; dist: int): seq[T] =
## Same as ``rotateLeft``, just with the difference that it does ## Same as `rotateLeft`, just with the difference that it does
## not modify the argument. It creates a new ``seq`` instead. ## not modify the argument. It creates a new `seq` instead.
## ##
## **See also:** ## **See also:**
## * `rotateLeft proc<#rotateLeft,openArray[T],int>`_ for the in-place version of this proc ## * `rotateLeft proc<#rotateLeft,openArray[T],int>`_ for the in-place version of this proc

2
tests/stdlib/talgorithm.nim
View file

@ -3,7 +3,7 @@ discard """
''' '''
""" """
#12928,10456 #12928,10456
import sequtils, strutils, algorithm, json import sequtils, algorithm, json
proc test() = proc test() =
try: try: