deques minor improvement (#16084)

lib/pure/collections/deques.nim

@@ -77,7 +77,7 @@ template checkIfInitialized(deq: typed) =
       initImpl(deq, defaultInitialSize)
 
 proc initDeque*[T](initialSize: int = 4): Deque[T] =
-  ## Create a new empty deque.
+  ## Creates a new empty deque.
   ##
   ## Optionally, the initial capacity can be reserved via `initialSize`
   ## as a performance optimization.
@@ -103,7 +103,7 @@ proc toDeque*[T](x: openArray[T]): Deque[T] {.since: (1, 3).} =
     result.addLast(item)
 
 proc len*[T](deq: Deque[T]): int {.inline.} =
-  ## Return the number of elements of `deq`.
+  ## Returns the number of elements of `deq`.
   result = deq.count
 
 template emptyCheck(deq) =
@@ -123,7 +123,7 @@ template xBoundsCheck(deq, i) =
                          "Out of bounds: " & $i & " < 0")
 
 proc `[]`*[T](deq: Deque[T], i: Natural): T {.inline.} =
-  ## Access the i-th element of `deq`.
+  ## Accesses the i-th element of `deq`.
   runnableExamples:
     var a = initDeque[int]()
     for i in 1 .. 5:
@@ -136,7 +136,7 @@ proc `[]`*[T](deq: Deque[T], i: Natural): T {.inline.} =
   return deq.data[(deq.head + i) and deq.mask]
 
 proc `[]`*[T](deq: var Deque[T], i: Natural): var T {.inline.} =
-  ## Access the i-th element of `deq` and return a mutable
+  ## Accesses the i-th element of `deq` and return a mutable
   ## reference to it.
   runnableExamples:
     var a = initDeque[int]()
@@ -150,7 +150,7 @@ proc `[]`*[T](deq: var Deque[T], i: Natural): var T {.inline.} =
   return deq.data[(deq.head + i) and deq.mask]
 
 proc `[]=`*[T](deq: var Deque[T], i: Natural, val: T) {.inline.} =
-  ## Change the i-th element of `deq`.
+  ## Changes the i-th element of `deq`.
   runnableExamples:
     var a = initDeque[int]()
     for i in 1 .. 5:
@@ -164,7 +164,7 @@ proc `[]=`*[T](deq: var Deque[T], i: Natural, val: T) {.inline.} =
   deq.data[(deq.head + i) and deq.mask] = val
 
 proc `[]`*[T](deq: Deque[T], i: BackwardsIndex): T {.inline.} =
-  ## Access the backwards indexed i-th element.
+  ## Accesses the backwards indexed i-th element.
   ##
   ## `deq[^1]` is the last element.
   runnableExamples:
@@ -179,7 +179,7 @@ proc `[]`*[T](deq: Deque[T], i: BackwardsIndex): T {.inline.} =
   return deq[deq.len - int(i)]
 
 proc `[]`*[T](deq: var Deque[T], i: BackwardsIndex): var T {.inline.} =
-  ## Access the backwards indexed i-th element.
+  ## Accesses the backwards indexed i-th element.
   ##
   ## `deq[^1]` is the last element.
   runnableExamples:
@@ -194,7 +194,7 @@ proc `[]`*[T](deq: var Deque[T], i: BackwardsIndex): var T {.inline.} =
   return deq[deq.len - int(i)]
 
 proc `[]=`*[T](deq: var Deque[T], i: BackwardsIndex, x: T) {.inline.} =
-  ## Change the backwards indexed i-th element.
+  ## Changes the backwards indexed i-th element.
   ##
   ## `deq[^1]` is the last element.
   runnableExamples:
@@ -210,7 +210,7 @@ proc `[]=`*[T](deq: var Deque[T], i: BackwardsIndex, x: T) {.inline.} =
   deq[deq.len - int(i)] = x
 
 iterator items*[T](deq: Deque[T]): T =
-  ## Yield every element of `deq`.
+  ## Yields every element of `deq`.
   ##
   ## **Examples:**
   ##
@@ -232,7 +232,7 @@ iterator items*[T](deq: Deque[T]): T =
     i = (i + 1) and deq.mask
 
 iterator mitems*[T](deq: var Deque[T]): var T =
-  ## Yield every element of `deq`, which can be modified.
+  ## Yields every element of `deq`, which can be modified.
   runnableExamples:
     var a = initDeque[int]()
     for i in 1 .. 5:
@@ -248,7 +248,7 @@ iterator mitems*[T](deq: var Deque[T]): var T =
     i = (i + 1) and deq.mask
 
 iterator pairs*[T](deq: Deque[T]): tuple[key: int, val: T] =
-  ## Yield every (position, value) of `deq`.
+  ## Yields every (position, value) of `deq`.
   ##
   ## **Examples:**
   ##
@@ -270,7 +270,7 @@ iterator pairs*[T](deq: Deque[T]): tuple[key: int, val: T] =
     i = (i + 1) and deq.mask
 
 proc contains*[T](deq: Deque[T], item: T): bool {.inline.} =
-  ## Return true if `item` is in `deq` or false if not found.
+  ## Returns true if `item` is in `deq` or false if not found.
   ##
   ## Usually used via the ``in`` operator.
   ## It is the equivalent of ``deq.find(item) >= 0``.
@@ -298,7 +298,7 @@ proc expandIfNeeded[T](deq: var Deque[T]) =
     deq.head = 0
 
 proc addFirst*[T](deq: var Deque[T], item: T) =
-  ## Add an `item` to the beginning of the `deq`.
+  ## Adds an `item` to the beginning of the `deq`.
   ##
   ## See also:
   ## * `addLast proc <#addLast,Deque[T],T>`_
@@ -318,7 +318,7 @@ proc addFirst*[T](deq: var Deque[T], item: T) =
   deq.data[deq.head] = item
 
 proc addLast*[T](deq: var Deque[T], item: T) =
-  ## Add an `item` to the end of the `deq`.
+  ## Adds an `item` to the end of the `deq`.
   ##
   ## See also:
   ## * `addFirst proc <#addFirst,Deque[T],T>`_
@@ -421,7 +421,7 @@ template destroy(x: untyped) =
   reset(x)
 
 proc popFirst*[T](deq: var Deque[T]): T {.inline, discardable.} =
-  ## Remove and returns the first element of the `deq`.
+  ## Removes and returns the first element of the `deq`.
   ##
   ## See also:
   ## * `addFirst proc <#addFirst,Deque[T],T>`_
@@ -446,7 +446,7 @@ proc popFirst*[T](deq: var Deque[T]): T {.inline, discardable.} =
   deq.head = (deq.head + 1) and deq.mask
 
 proc popLast*[T](deq: var Deque[T]): T {.inline, discardable.} =
-  ## Remove and returns the last element of the `deq`.
+  ## Removes and returns the last element of the `deq`.
   ##
   ## See also:
   ## * `addFirst proc <#addFirst,Deque[T],T>`_
@@ -489,7 +489,7 @@ proc clear*[T](deq: var Deque[T]) {.inline.} =
   deq.tail = deq.head
 
 proc shrink*[T](deq: var Deque[T], fromFirst = 0, fromLast = 0) =
-  ## Remove `fromFirst` elements from the front of the deque and
+  ## Removes `fromFirst` elements from the front of the deque and
   ## `fromLast` elements from the back.
   ##
   ## If the supplied number of elements exceeds the total number of elements
@@ -520,120 +520,9 @@ proc shrink*[T](deq: var Deque[T], fromFirst = 0, fromLast = 0) =
   dec deq.count, fromFirst + fromLast
 
 proc `$`*[T](deq: Deque[T]): string =
-  ## Turn a deque into its string representation.
+  ## Turns a deque into its string representation.
   result = "["
   for x in deq:
     if result.len > 1: result.add(", ")
     result.addQuoted(x)
   result.add("]")
-
-
-
-when isMainModule:
-  var deq = initDeque[int](1)
-  deq.addLast(4)
-  deq.addFirst(9)
-  deq.addFirst(123)
-  var first = deq.popFirst()
-  deq.addLast(56)
-  assert(deq.peekLast() == 56)
-  deq.addLast(6)
-  assert(deq.peekLast() == 6)
-  var second = deq.popFirst()
-  deq.addLast(789)
-  assert(deq.peekLast() == 789)
-
-  assert first == 123
-  assert second == 9
-  assert($deq == "[4, 56, 6, 789]")
-  assert deq == [4, 56, 6, 789].toDeque
-
-  assert deq[0] == deq.peekFirst and deq.peekFirst == 4
-  #assert deq[^1] == deq.peekLast and deq.peekLast == 789
-  deq[0] = 42
-  deq[deq.len - 1] = 7
-
-  assert 6 in deq and 789 notin deq
-  assert deq.find(6) >= 0
-  assert deq.find(789) < 0
-
-  block:
-    var d = initDeque[int](1)
-    d.addLast 7
-    d.addLast 8
-    d.addLast 10
-    d.addFirst 5
-    d.addFirst 2
-    d.addFirst 1
-    d.addLast 20
-    d.shrink(fromLast = 2)
-    doAssert($d == "[1, 2, 5, 7, 8]")
-    d.shrink(2, 1)
-    doAssert($d == "[5, 7]")
-    d.shrink(2, 2)
-    doAssert d.len == 0
-
-  for i in -2 .. 10:
-    if i in deq:
-      assert deq.contains(i) and deq.find(i) >= 0
-    else:
-      assert(not deq.contains(i) and deq.find(i) < 0)
-
-  when compileOption("boundChecks"):
-    try:
-      echo deq[99]
-      assert false
-    except IndexDefect:
-      discard
-
-    try:
-      assert deq.len == 4
-      for i in 0 ..< 5: deq.popFirst()
-      assert false
-    except IndexDefect:
-      discard
-
-  # grabs some types of resize error.
-  deq = initDeque[int]()
-  for i in 1 .. 4: deq.addLast i
-  deq.popFirst()
-  deq.popLast()
-  for i in 5 .. 8: deq.addFirst i
-  assert $deq == "[8, 7, 6, 5, 2, 3]"
-
-  # Similar to proc from the documentation example
-  proc foo(a, b: Positive) = # assume random positive values for `a` and `b`.
-    var deq = initDeque[int]()
-    assert deq.len == 0
-    for i in 1 .. a: deq.addLast i
-
-    if b < deq.len: # checking before indexed access.
-      assert deq[b] == b + 1
-
-    # The following two lines don't need any checking on access due to the logic
-    # of the program, but that would not be the case if `a` could be 0.
-    assert deq.peekFirst == 1
-    assert deq.peekLast == a
-
-    while deq.len > 0: # checking if the deque is empty
-      assert deq.popFirst() > 0
-
-  #foo(0,0)
-  foo(8, 5)
-  foo(10, 9)
-  foo(1, 1)
-  foo(2, 1)
-  foo(1, 5)
-  foo(3, 2)
-
-  import sets
-  block t13310:
-    proc main() =
-      var q = initDeque[HashSet[int16]](2)
-      q.addFirst([1'i16].toHashSet)
-      q.addFirst([2'i16].toHashSet)
-      q.addFirst([3'i16].toHashSet)
-      assert $q == "[{3}, {2}, {1}]"
-
-    static:
-      main()

tests/stdlib/tdeque.nim

@@ -0,0 +1,111 @@
+import deques
+
+
+var deq = initDeque[int](1)
+deq.addLast(4)
+deq.addFirst(9)
+deq.addFirst(123)
+var first = deq.popFirst()
+deq.addLast(56)
+assert(deq.peekLast() == 56)
+deq.addLast(6)
+assert(deq.peekLast() == 6)
+var second = deq.popFirst()
+deq.addLast(789)
+assert(deq.peekLast() == 789)
+
+assert first == 123
+assert second == 9
+assert($deq == "[4, 56, 6, 789]")
+assert deq == [4, 56, 6, 789].toDeque
+
+assert deq[0] == deq.peekFirst and deq.peekFirst == 4
+#assert deq[^1] == deq.peekLast and deq.peekLast == 789
+deq[0] = 42
+deq[deq.len - 1] = 7
+
+assert 6 in deq and 789 notin deq
+assert deq.find(6) >= 0
+assert deq.find(789) < 0
+
+block:
+  var d = initDeque[int](1)
+  d.addLast 7
+  d.addLast 8
+  d.addLast 10
+  d.addFirst 5
+  d.addFirst 2
+  d.addFirst 1
+  d.addLast 20
+  d.shrink(fromLast = 2)
+  doAssert($d == "[1, 2, 5, 7, 8]")
+  d.shrink(2, 1)
+  doAssert($d == "[5, 7]")
+  d.shrink(2, 2)
+  doAssert d.len == 0
+
+for i in -2 .. 10:
+  if i in deq:
+    assert deq.contains(i) and deq.find(i) >= 0
+  else:
+    assert(not deq.contains(i) and deq.find(i) < 0)
+
+when compileOption("boundChecks"):
+  try:
+    echo deq[99]
+    assert false
+  except IndexDefect:
+    discard
+
+  try:
+    assert deq.len == 4
+    for i in 0 ..< 5: deq.popFirst()
+    assert false
+  except IndexDefect:
+    discard
+
+# grabs some types of resize error.
+deq = initDeque[int]()
+for i in 1 .. 4: deq.addLast i
+deq.popFirst()
+deq.popLast()
+for i in 5 .. 8: deq.addFirst i
+assert $deq == "[8, 7, 6, 5, 2, 3]"
+
+# Similar to proc from the documentation example
+proc foo(a, b: Positive) = # assume random positive values for `a` and `b`.
+  var deq = initDeque[int]()
+  assert deq.len == 0
+  for i in 1 .. a: deq.addLast i
+
+  if b < deq.len: # checking before indexed access.
+    assert deq[b] == b + 1
+
+  # The following two lines don't need any checking on access due to the logic
+  # of the program, but that would not be the case if `a` could be 0.
+  assert deq.peekFirst == 1
+  assert deq.peekLast == a
+
+  while deq.len > 0: # checking if the deque is empty
+    assert deq.popFirst() > 0
+
+#foo(0,0)
+foo(8, 5)
+foo(10, 9)
+foo(1, 1)
+foo(2, 1)
+foo(1, 5)
+foo(3, 2)
+
+import sets
+
+block t13310:
+  proc main() =
+    var q = initDeque[HashSet[int16]](2)
+    q.addFirst([1'i16].toHashSet)
+    q.addFirst([2'i16].toHashSet)
+    q.addFirst([3'i16].toHashSet)
+    assert $q == "[{3}, {2}, {1}]"
+
+  static:
+    main()