Adds more docstrings to the sets module.

1 files changed, 374 insertions, 61 deletions

diff --git a/lib/pure/collections/sets.nim b/lib/pure/collections/sets.nim
index 988a68b98..f63805e4e 100644
--- a/lib/pure/collections/sets.nim
+++ b/lib/pure/collections/sets.nim
@@ -9,6 +9,10 @@
 
 ## The ``sets`` module implements an efficient hash set and ordered hash set.
 ##
+## Hash sets are different from the `built in set type
+## <manual.html#set-type>`_. Sets allow you to store any value that can be
+## `hashed <hashes.html>`_ and they don't contain duplicate entries.
+##
 ## **Note**: The data types declared here have *value semantics*: This means
 ## that ``=`` performs a copy of the set.
 
@@ -26,8 +30,8 @@ type
   TSet* {.final, myShallow.}[A] = object ## \
     ## A generic hash set.
     ##
-    ## Use `init() <#init,TSet[A]>`_ or `initSet[type]() <#initSet>`_ before
-    ## calling other procs on it.
+    ## Use `init() <#init,TSet[A],int>`_ or `initSet[type]() <#initSet>`_
+    ## before calling other procs on it.
     data: TKeyValuePairSeq[A]
     counter: int
 
@@ -36,7 +40,7 @@ proc isValid*[A](s: TSet[A]): bool =
   ##
   ## Most operations over an uninitialized set will crash at runtime and
   ## `assert <system.html#assert>`_ in debug builds. You can use this proc in
-  ## your own methods to verify that sets passed to your procs are correctly
+  ## your own procs to verify that sets passed to your procs are correctly
   ## initialized. Example:
   ##
   ## .. code-block :: nimrod
@@ -46,15 +50,42 @@ proc isValid*[A](s: TSet[A]): bool =
   result = not s.data.isNil
 
 proc len*[A](s: TSet[A]): int =
-  ## returns the number of keys in `s`.
+  ## Returns the number of keys in `s`.
+  ##
+  ## Due to an implementation detail you can call this proc on variables which
+  ## have not been initialized yet. The proc will return zero as the length
+  ## then. Example:
+  ##
+  ## .. code-block::
+  ##
+  ##   var values: TSet[int]
+  ##   assert(not values.isValid)
+  ##   assert values.len == 0
   result = s.counter
 
 proc card*[A](s: TSet[A]): int =
-  ## alias for `len`.
+  ## Alias for `len() <#len,TSet[A]>`_.
   result = s.counter
 
 iterator items*[A](s: TSet[A]): A =
-  ## iterates over any key in the table `t`.
+  ## Iterates over keys in the set `s`.
+  ##
+  ## If you need a sequence with the keys you can use `sequtils.toSeq()
+  ## <sequtils.html#toSeq>`_ on the iterator. Usage example:
+  ##
+  ## .. code-block::
+  ##   type
+  ##     pair = tuple[a, b: int]
+  ##   var
+  ##     a, b = initSet[pair]()
+  ##   a.incl((2, 3))
+  ##   a.incl((3, 2))
+  ##   a.incl((2, 3))
+  ##   for x, y in a.items:
+  ##     b.incl((x - 2, y + 1))
+  ##   assert a.len == 2
+  ##   echo b
+  ##   # --> {(a: 1, b: 3), (a: 0, b: 4)}
   assert s.isValid, "The set needs to be initialized."
   for h in 0..high(s.data):
     if s.data[h].slot == seFilled: yield s.data[h].key
@@ -98,7 +129,17 @@ proc mget*[A](s: var TSet[A], key: A): var A =
   else: raise newException(EInvalidKey, "key not found: " & $key)
 
 proc contains*[A](s: TSet[A], key: A): bool =
-  ## returns true iff `key` is in `s`.
+  ## Returns true iff `key` is in `s`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var values = initSet[int]()
+  ##   assert(not values.contains(2))
+  ##   values.incl(2)
+  ##   assert values.contains(2)
+  ##   values.excl(2)
+  ##   assert(not values.contains(2))
   assert s.isValid, "The set needs to be initialized."
   var index = rawGet(s, key)
   result = index >= 0
@@ -130,18 +171,43 @@ template containsOrInclImpl() {.dirty.} =
     inc(s.counter)
 
 proc incl*[A](s: var TSet[A], key: A) =
-  ## includes an element `key` in `s`.
+  ## Includes an element `key` in `s`.
+  ##
+  ## This doesn't do anything if `key` is already in `s`. Example:
+  ##
+  ## .. code-block::
+  ##   var values = initSet[int]()
+  ##   values.incl(2)
+  ##   values.incl(2)
+  ##   assert values.len == 1
   assert s.isValid, "The set needs to be initialized."
   inclImpl()
 
 proc incl*[A](s: var TSet[A], other: TSet[A]) =
-  ## includes everything in `other` in `s`
+  ## Includes all elements from `other` into `s`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var values = initSet[int]()
+  ##   values.incl(2)
+  ##   var others = toSet([6, 7])
+  ##   values.incl(others)
+  ##   assert values.len == 3
   assert s.isValid, "The set `s` needs to be initialized."
   assert other.isValid, "The set `other` needs to be initialized."
   for item in other: incl(s, item)
 
 proc excl*[A](s: var TSet[A], key: A) =
-  ## excludes `key` from the set `s`.
+  ## Excludes `key` from the set `s`.
+  ##
+  ## This doesn't do anything if `key` is not found in `s`. Example:
+  ##
+  ## .. code-block::
+  ##   var s = toSet([2, 3, 6, 7])
+  ##   s.excl(2)
+  ##   s.excl(2)
+  ##   assert s.len == 3
   assert s.isValid, "The set needs to be initialized."
   var index = rawGet(s, key)
   if index >= 0:
@@ -149,14 +215,33 @@ proc excl*[A](s: var TSet[A], key: A) =
     dec(s.counter)
 
 proc excl*[A](s: var TSet[A], other: TSet[A]) =
-  ## excludes everything in `other` from `s`.
+  ## Excludes everything in `other` from `s`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     numbers = toSet([1, 2, 3, 4, 5])
+  ##     even = toSet([2, 4, 6, 8])
+  ##   numbers.excl(even)
+  ##   echo numbers
+  ##   # --> {1, 3, 5}
   assert s.isValid, "The set `s` needs to be initialized."
   assert other.isValid, "The set `other` needs to be initialized."
   for item in other: excl(s, item)
 
 proc containsOrIncl*[A](s: var TSet[A], key: A): bool =
-  ## returns true if `s` contains `key`, otherwise `key` is included in `s`
-  ## and false is returned.
+  ## Includes `key` in the set `s` and tells if `key` was added to `s`.
+  ##
+  ## The difference with regards to the `incl() <#incl,TSet[A],A>`_ proc is
+  ## that this proc returns `true` if `key` was already present in `s`. The
+  ## proc will return false if `key` was added as a new value to `s` during
+  ## this call. Example:
+  ##
+  ## .. code-block::
+  ##   var values = initSet[int]()
+  ##   assert values.containsOrIncl(2) == false
+  ##   assert values.containsOrIncl(2) == true
   assert s.isValid, "The set needs to be initialized."
   containsOrInclImpl()
 
@@ -169,7 +254,7 @@ proc init*[A](s: var TSet[A], initialSize=64) =
   ## with other procs from this module with the exception of `isValid()
   ## <#isValid,TSet[A]>`_ and `len() <#len,TSet[A]>`_.
   ##
-  ## You can call this method on a previously initialized hash set, which will
+  ## You can call this proc on a previously initialized hash set, which will
   ## discard all its values. This might be more convenient than iterating over
   ## existing values and calling `excl() <#excl,TSet[A],A>`_ on them. Example:
   ##
@@ -184,7 +269,8 @@ proc init*[A](s: var TSet[A], initialSize=64) =
   newSeq(s.data, initialSize)
 
 proc initSet*[A](initialSize=64): TSet[A] =
-  ## Convenience wrapper around `init() <#init,TSet[A]>`_.
+  ## Wrapper around `init() <#init,TSet[A],int>`_ for initialization of hash
+  ## sets.
   ##
   ## Returns an empty hash set you can assign directly in ``var`` blocks in a
   ## single line. Example:
@@ -195,7 +281,14 @@ proc initSet*[A](initialSize=64): TSet[A] =
   result.init(initialSize)
 
 proc toSet*[A](keys: openArray[A]): TSet[A] =
-  ## creates a new hash set that contains the given `keys`.
+  ## Creates a new hash set that contains the given `keys`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var numbers = toSet([1, 2, 3, 4, 5])
+  ##   assert numbers.contains(2)
+  ##   assert numbers.contains(4)
   result = initSet[A](nextPowerOfTwo(keys.len+10))
   for key in items(keys): result.incl(key)
 
@@ -207,20 +300,51 @@ template dollarImpl(): stmt {.dirty.} =
   result.add("}")
 
 proc `$`*[A](s: TSet[A]): string =
-  ## The `$` operator for hash sets.
+  ## Converts the set `s` to a string, mostly for logging purposes.
+  ##
+  ## Don't use this proc for serialization, the representation may change at
+  ## any moment and values are not escaped. Example:
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   echo toSet([2, 4, 5])
+  ##   # --> {2, 4, 5}
+  ##   echo toSet(["no", "esc'aping", "is \" provided"])
+  ##   # --> {no, esc'aping, is " provided}
   assert s.isValid, "The set needs to be initialized."
   dollarImpl()
 
 proc union*[A](s1, s2: TSet[A]): TSet[A] =
-  ## returns a new set of all items that are contained in at
-  ## least one of `s1` and `s2`
+  ## Returns the union of the sets `s1` and `s2`.
+  ##
+  ## The union of two sets is represented mathematically as *A ∪ B* and is the
+  ## set of all objects that are members of `s1`, `s2` or both. Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##     c = union(a, b)
+  ##   assert c == toSet(["a", "b", "c"])
   assert s1.isValid, "The set `s1` needs to be initialized."
   assert s2.isValid, "The set `s2` needs to be initialized."
   result = s1
   incl(result, s2)
 
 proc intersection*[A](s1, s2: TSet[A]): TSet[A] =
-  ## returns a new set of all items that are contained in both `s1` and `s2`
+  ## Returns the intersection of the sets `s1` and `s2`.
+  ##
+  ## The intersection of two sets is represented mathematically as *A ∩ B* and
+  ## is the set of all objects that are members of `s1` and `s2` at the same
+  ## time. Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##     c = intersection(a, b)
+  ##   assert c == toSet(["b"])
   assert s1.isValid, "The set `s1` needs to be initialized."
   assert s2.isValid, "The set `s2` needs to be initialized."
   result = initSet[A](min(s1.data.len, s2.data.len))
@@ -228,7 +352,18 @@ proc intersection*[A](s1, s2: TSet[A]): TSet[A] =
     if item in s2: incl(result, item)
 
 proc difference*[A](s1, s2: TSet[A]): TSet[A] =
-  ## returns a new set of all items that are contained in `s1`, but not in `s2`
+  ## Returns the difference of the sets `s1` and `s2`.
+  ##
+  ## The difference of two sets is represented mathematically as *A \ B* and is
+  ## the set of all objects that are members of `s1` and not members of `s2`.
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##     c = difference(a, b)
+  ##   assert c == toSet(["a"])
   assert s1.isValid, "The set `s1` needs to be initialized."
   assert s2.isValid, "The set `s2` needs to be initialized."
   result = initSet[A]()
@@ -237,8 +372,18 @@ proc difference*[A](s1, s2: TSet[A]): TSet[A] =
       incl(result, item)
 
 proc symmetricDifference*[A](s1, s2: TSet[A]): TSet[A] =
-  ## returns a new set of all items that are contained in either
-  ## `s1` or `s2`, but not both
+  ## Returns the symmetric difference of the sets `s1` and `s2`.
+  ##
+  ## The symmetric difference of two sets is represented mathematically as *A △
+  ## B* or *A ⊖ B* and is the set of all objects that are members of `s1` or
+  ## `s2` but not both at the same time. Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##     c = symmetricDifference(a, b)
+  ##   assert c == toSet(["a", "c"])
   assert s1.isValid, "The set `s1` needs to be initialized."
   assert s2.isValid, "The set `s2` needs to be initialized."
   result = s1
@@ -246,23 +391,32 @@ proc symmetricDifference*[A](s1, s2: TSet[A]): TSet[A] =
     if containsOrIncl(result, item): excl(result, item)
 
 proc `+`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
-  ## alias for `union`
+  ## Alias for `union(s1, s2) <#union>`_.
   result = union(s1, s2)
 
 proc `*`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
-  ## alias for `intersection`
+  ## Alias for `intersection(s1, s2) <#intersection>`_.
   result = intersection(s1, s2)
 
 proc `-`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
-  ## alias for `difference`
+  ## Alias for `difference(s1, s2) <#difference>`_.
   result = difference(s1, s2)
 
 proc `-+-`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
-  ## alias for `symmetricDifference`
+  ## Alias for `symmetricDifference(s1, s2) <#symmetricDifference>`_.
   result = symmetricDifference(s1, s2)
 
 proc disjoint*[A](s1, s2: TSet[A]): bool =
-  ## returns true iff `s1` and `s2` have no items in common
+  ## Returns true iff the sets `s1` and `s2` have no items in common.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##   assert disjoint(a, b) == false
+  ##   assert disjoint(a, b - a) == true
   assert s1.isValid, "The set `s1` needs to be initialized."
   assert s2.isValid, "The set `s2` needs to be initialized."
   for item in s1:
@@ -270,11 +424,33 @@ proc disjoint*[A](s1, s2: TSet[A]): bool =
   return true
 
 proc `<`*[A](s, t: TSet[A]): bool =
-  ## Is s a strict subset of t?
+  ## Returns true if `s` is a strict or proper subset of `t`.
+  ##
+  ## A strict or proper subset `s` has all of its members in `t` but `t` has
+  ## more elements than `s`. Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##     c = intersection(a, b)
+  ##   assert c < a and c < b
+  ##   assert((a < a) == false)
   s.counter != t.counter and s <= t
 
 proc `<=`*[A](s, t: TSet[A]): bool =
-  ## Is s a subset of t?
+  ## Returns true if `s` is subset of `t`.
+  ##
+  ## A subset `s` has all of its members in `t` and `t` doesn't necessarily
+  ## have more members than `s`. That is, `s` can be equal to `t`. Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet(["a", "b"])
+  ##     b = toSet(["b", "c"])
+  ##     c = intersection(a, b)
+  ##   assert c <= a and c <= b
+  ##   assert((a <= a))
   result = false
   if s.counter > t.counter: return
   result = true
@@ -284,9 +460,27 @@ proc `<=`*[A](s, t: TSet[A]): bool =
       return
 
 proc `==`*[A](s, t: TSet[A]): bool =
+  ## Returns true if both `s` and `t` have the same members and set size.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var
+  ##     a = toSet([1, 2])
+  ##     b = toSet([1])
+  ##   b.incl(2)
+  ##   assert a == b
   s.counter == t.counter and s <= t
 
 proc map*[A, B](data: TSet[A], op: proc (x: A): B {.closure.}): TSet[B] =
+  ## Returns a new set after applying `op` on each of the elements of `data`.
+  ##
+  ## You can use this proc to transform the elements from a set. Example:
+  ##
+  ## .. code-block::
+  ##   var a = toSet([1, 2, 3])
+  ##   var b = a.map(proc (x: int): string = $x)
+  ##   assert b == toSet(["1", "2", "3"])
   result = initSet[B]()
   for item in data: result.incl(op(item))
 
@@ -300,7 +494,7 @@ type
       final, myShallow.}[A] = object ## \
     ## A generic hash set that remembers insertion order.
     ##
-    ## Use `init() <#init,TOrderedSet[A]>`_ or `initOrderedSet[type]()
+    ## Use `init() <#init,TOrderedSet[A],int>`_ or `initOrderedSet[type]()
     ## <#initOrderedSet>`_ before calling other procs on it.
     data: TOrderedKeyValuePairSeq[A]
     counter, first, last: int
@@ -311,7 +505,7 @@ proc isValid*[A](s: TOrderedSet[A]): bool =
   ##
   ## Most operations over an uninitialized ordered set will crash at runtime
   ## and `assert <system.html#assert>`_ in debug builds. You can use this proc
-  ## in your own methods to verify that ordered sets passed to your procs are
+  ## in your own procs to verify that ordered sets passed to your procs are
   ## correctly initialized. Example:
   ##
   ## .. code-block :: nimrod
@@ -321,11 +515,21 @@ proc isValid*[A](s: TOrderedSet[A]): bool =
   result = not s.data.isNil
 
 proc len*[A](s: TOrderedSet[A]): int {.inline.} =
-  ## returns the number of keys in `s`.
+  ## Returns the number of keys in `s`.
+  ##
+  ## Due to an implementation detail you can call this proc on variables which
+  ## have not been initialized yet. The proc will return zero as the length
+  ## then. Example:
+  ##
+  ## .. code-block::
+  ##
+  ##   var values: TOrderedSet[int]
+  ##   assert(not values.isValid)
+  ##   assert values.len == 0
   result = s.counter
 
 proc card*[A](s: TOrderedSet[A]): int {.inline.} =
-  ## alias for `len`.
+  ## Alias for `len() <#len,TOrderedSet[A]>`_.
   result = s.counter
 
 template forAllOrderedPairs(yieldStmt: stmt) {.dirty, immediate.} =
@@ -336,7 +540,23 @@ template forAllOrderedPairs(yieldStmt: stmt) {.dirty, immediate.} =
     h = nxt
 
 iterator items*[A](s: TOrderedSet[A]): A =
-  ## iterates over any key in the set `s` in insertion order.
+  ## Iterates over keys in the ordered set `s` in insertion order.
+  ##
+  ## If you need a sequence with the keys you can use `sequtils.toSeq()
+  ## <sequtils.html#toSeq>`_ on the iterator. Usage example:
+  ##
+  ## .. code-block::
+  ##   var a = initOrderedSet[int]()
+  ##   for value in [9, 2, 1, 5, 1, 8, 4, 2]:
+  ##     a.incl(value)
+  ##   for value in a.items:
+  ##     echo "Got ", value
+  ##   # --> Got 9
+  ##   # --> Got 2
+  ##   # --> Got 1
+  ##   # --> Got 5
+  ##   # --> Got 8
+  ##   # --> Got 4
   assert s.isValid, "The set needs to be initialized."
   forAllOrderedPairs:
     yield s.data[h].key
@@ -345,7 +565,15 @@ proc rawGet[A](s: TOrderedSet[A], key: A): int =
   rawGetImpl()
 
 proc contains*[A](s: TOrderedSet[A], key: A): bool =
-  ## returns true iff `key` is in `s`.
+  ## Returns true iff `key` is in `s`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var values = initOrderedSet[int]()
+  ##   assert(not values.contains(2))
+  ##   values.incl(2)
+  ##   assert values.contains(2)
   assert s.isValid, "The set needs to be initialized."
   var index = rawGet(s, key)
   result = index >= 0
@@ -372,19 +600,45 @@ proc enlarge[A](s: var TOrderedSet[A]) =
   swap(s.data, n)
 
 proc incl*[A](s: var TOrderedSet[A], key: A) =
-  ## includes an element `key` in `s`.
+  ## Includes an element `key` in `s`.
+  ##
+  ## This doesn't do anything if `key` is already in `s`. Example:
+  ##
+  ## .. code-block::
+  ##   var values = initOrderedSet[int]()
+  ##   values.incl(2)
+  ##   values.incl(2)
+  ##   assert values.len == 1
   assert s.isValid, "The set needs to be initialized."
   inclImpl()
 
 proc incl*[A](s: var TSet[A], other: TOrderedSet[A]) =
-  ## includes everything in `other` in `s`
+  ## Includes all elements from `other` into `s`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var values = initOrderedSet[int]()
+  ##   values.incl(2)
+  ##   var others = toOrderedSet([6, 7])
+  ##   values.incl(others)
+  ##   assert values.len == 3
   assert s.isValid, "The set `s` needs to be initialized."
   assert other.isValid, "The set `other` needs to be initialized."
   for item in other: incl(s, item)
 
 proc containsOrIncl*[A](s: var TOrderedSet[A], key: A): bool =
-  ## returns true if `s` contains `key`, otherwise `key` is included in `s`
-  ## and false is returned.
+  ## Includes `key` in the set `s` and tells if `key` was added to `s`.
+  ##
+  ## The difference with regards to the `incl() <#incl,TOrderedSet[A],A>`_ proc
+  ## is that this proc returns `true` if `key` was already present in `s`. The
+  ## proc will return false if `key` was added as a new value to `s` during
+  ## this call. Example:
+  ##
+  ## .. code-block::
+  ##   var values = initOrderedSet[int]()
+  ##   assert values.containsOrIncl(2) == false
+  ##   assert values.containsOrIncl(2) == true
   assert s.isValid, "The set needs to be initialized."
   containsOrInclImpl()
 
@@ -397,9 +651,9 @@ proc init*[A](s: var TOrderedSet[A], initialSize=64) =
   ## with other procs from this module with the exception of `isValid()
   ## <#isValid,TOrderedSet[A]>`_ and `len() <#len,TOrderedSet[A]>`_.
   ##
-  ## You can call this method on a previously initialized ordered hash set to
-  ## discard its values. At the moment this is the only method to remove
-  ## elements from an ordered hash set. Example:
+  ## You can call this proc on a previously initialized ordered hash set to
+  ## discard its values. At the moment this is the only proc to remove elements
+  ## from an ordered hash set. Example:
   ##
   ## .. code-block ::
   ##   var a: TOrderedSet[int]
@@ -414,7 +668,8 @@ proc init*[A](s: var TOrderedSet[A], initialSize=64) =
   newSeq(s.data, initialSize)
 
 proc initOrderedSet*[A](initialSize=64): TOrderedSet[A] =
-  ## Convenience wrapper around `init() <#init,TOrderedSet[A]>`_.
+  ## Wrapper around `init() <#init,TOrderedSet[A],int>`_ for initialization of
+  ## ordered hash sets.
   ##
   ## Returns an empty ordered hash set you can assign directly in ``var``
   ## blocks in a single line. Example:
@@ -425,12 +680,30 @@ proc initOrderedSet*[A](initialSize=64): TOrderedSet[A] =
   result.init(initialSize)
 
 proc toOrderedSet*[A](keys: openArray[A]): TOrderedSet[A] =
-  ## creates a new ordered hash set that contains the given `keys`.
+  ## Creates a new ordered hash set that contains the given `keys`.
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   var numbers = toOrderedSet([1, 2, 3, 4, 5])
+  ##   assert numbers.contains(2)
+  ##   assert numbers.contains(4)
   result = initOrderedSet[A](nextPowerOfTwo(keys.len+10))
   for key in items(keys): result.incl(key)
 
 proc `$`*[A](s: TOrderedSet[A]): string =
-  ## The `$` operator for ordered hash sets.
+  ## Converts the ordered hash set `s` to a string, mostly for logging purposes.
+  ##
+  ## Don't use this proc for serialization, the representation may change at
+  ## any moment and values are not escaped. Example:
+  ##
+  ## Example:
+  ##
+  ## .. code-block::
+  ##   echo toOrderedSet([2, 4, 5])
+  ##   # --> {2, 4, 5}
+  ##   echo toOrderedSet(["no", "esc'aping", "is \" provided"])
+  ##   # --> {no, esc'aping, is " provided}
   assert s.isValid, "The set needs to be initialized."
   dollarImpl()
 
@@ -459,7 +732,7 @@ proc testModule() =
       b.incl((x - 2, y + 1))
     assert a.len == b.card
     assert a.len == 2
-    echo b
+    #echo b
 
   block setContains:
     var values = initSet[int]()
@@ -469,40 +742,73 @@ proc testModule() =
     values.excl(2)
     assert(not values.contains(2))
 
+    values.incl(4)
+    var others = toSet([6, 7])
+    values.incl(others)
+    assert values.len == 3
+
+    values.init
+    assert values.containsOrIncl(2) == false
+    assert values.containsOrIncl(2) == true
+    var
+      a = toSet([1, 2])
+      b = toSet([1])
+    b.incl(2)
+    assert a == b
+
+  block exclusions:
+    var s = toSet([2, 3, 6, 7])
+    s.excl(2)
+    s.excl(2)
+    assert s.len == 3
+
+    var
+      numbers = toSet([1, 2, 3, 4, 5])
+      even = toSet([2, 4, 6, 8])
+    numbers.excl(even)
+    #echo numbers
+    # --> {1, 3, 5}
+
   block toSeqAndString:
-    var a = toSet[int]([2, 4, 5])
+    var a = toSet([2, 4, 5])
     var b = initSet[int]()
     for x in [2, 4, 5]: b.incl(x)
     assert($a == $b)
+    #echo a
+    #echo toSet(["no", "esc'aping", "is \" provided"])
+
+  #block orderedToSeqAndString:
+  #  echo toOrderedSet([2, 4, 5])
+  #  echo toOrderedSet(["no", "esc'aping", "is \" provided"])
 
   block setOperations:
     var
-      a = toset[string](["a", "b"])
-      b = toset[string](["b", "c"])
+      a = toSet(["a", "b"])
+      b = toSet(["b", "c"])
       c = union(a, b)
-    assert c == toSet[string](["a", "b", "c"])
+    assert c == toSet(["a", "b", "c"])
     var d = intersection(a, b)
-    assert d == toSet[string](["b"])
+    assert d == toSet(["b"])
     var e = difference(a, b)
-    assert e == toSet[string](["a"])
+    assert e == toSet(["a"])
     var f = symmetricDifference(a, b)
-    assert f == toSet[string](["a", "c"])
+    assert f == toSet(["a", "c"])
     assert d < a and d < b
     assert((a < a) == false)
     assert d <= a and d <= b
     assert((a <= a))
     # Alias test.
-    assert a + b == toSet[string](["a", "b", "c"])
-    assert a * b == toSet[string](["b"])
-    assert a - b == toSet[string](["a"])
-    assert a -+- b == toSet[string](["a", "c"])
+    assert a + b == toSet(["a", "b", "c"])
+    assert a * b == toSet(["b"])
+    assert a - b == toSet(["a"])
+    assert a -+- b == toSet(["a", "c"])
     assert disjoint(a, b) == false
     assert disjoint(a, b - a) == true
 
   block mapSet:
-    var a = toSet[int]([1, 2, 3])
+    var a = toSet([1, 2, 3])
     var b = a.map(proc (x: int): string = $x)
-    assert b == toSet[string](["1", "2", "3"])
+    assert b == toSet(["1", "2", "3"])
 
   block isValidTest:
     var cards: TOrderedSet[string]
@@ -528,6 +834,13 @@ proc testModule() =
     assert a.len == b.card
     assert a.len == 2
 
+  #block orderedSetIterator:
+  #  var a = initOrderedSet[int]()
+  #  for value in [9, 2, 1, 5, 1, 8, 4, 2]:
+  #    a.incl(value)
+  #  for value in a.items:
+  #    echo "Got ", value
+
   block setContains:
     var values = initOrderedSet[int]()
     assert(not values.contains(2))
@@ -535,7 +848,7 @@ proc testModule() =
     assert values.contains(2)
 
   block toSeqAndString:
-    var a = toOrderedSet[int]([2, 4, 5])
+    var a = toOrderedSet([2, 4, 5])
     var b = initOrderedSet[int]()
     for x in [2, 4, 5]: b.incl(x)
     assert($a == $b)