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

Adds more docstrings to the sets module.

Browse source
This commit is contained in:
Grzegorz Adam Hankiewicz 2014-07-26 22:42:32 +02:00
commit 48a13a76c8
1 changed files with 374 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

435
lib/pure/collections/sets.nim
View file

@ -9,6 +9,10 @@
## The ``sets`` module implements an efficient hash set and ordered hash set. ## 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 ## **Note**: The data types declared here have *value semantics*: This means
## that ``=`` performs a copy of the set. ## that ``=`` performs a copy of the set.
@ -26,8 +30,8 @@ type
TSet* {.final, myShallow.}[A] = object ## \ TSet* {.final, myShallow.}[A] = object ## \
## A generic hash set. ## A generic hash set.
## ##
## Use `init() <#init,TSet[A]>`_ or `initSet[type]() <#initSet>`_ before ## Use `init() <#init,TSet[A],int>`_ or `initSet[type]() <#initSet>`_
## calling other procs on it. ## before calling other procs on it.
data: TKeyValuePairSeq[A] data: TKeyValuePairSeq[A]
counter: int counter: int
@ -36,7 +40,7 @@ proc isValid*[A](s: TSet[A]): bool =
## ##
## Most operations over an uninitialized set will crash at runtime and ## Most operations over an uninitialized set will crash at runtime and
## `assert <system.html#assert>`_ in debug builds. You can use this proc in ## `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: ## initialized. Example:
## ##
## .. code-block :: nimrod ## .. code-block :: nimrod
@ -46,15 +50,42 @@ proc isValid*[A](s: TSet[A]): bool =
result = not s.data.isNil result = not s.data.isNil
proc len*[A](s: TSet[A]): int = 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 result = s.counter
proc card*[A](s: TSet[A]): int = proc card*[A](s: TSet[A]): int =
## alias for `len`. ## Alias for `len() <#len,TSet[A]>`_.
result = s.counter result = s.counter
iterator items*[A](s: TSet[A]): A = 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." assert s.isValid, "The set needs to be initialized."
for h in 0..high(s.data): for h in 0..high(s.data):
if s.data[h].slot == seFilled: yield s.data[h].key 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) else: raise newException(EInvalidKey, "key not found: " & $key)
proc contains*[A](s: TSet[A], key: A): bool = 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." assert s.isValid, "The set needs to be initialized."
var index = rawGet(s, key) var index = rawGet(s, key)
result = index >= 0 result = index >= 0
@ -130,18 +171,43 @@ template containsOrInclImpl() {.dirty.} =
inc(s.counter) inc(s.counter)
proc incl*[A](s: var TSet[A], key: A) = 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." assert s.isValid, "The set needs to be initialized."
inclImpl() inclImpl()
proc incl*[A](s: var TSet[A], other: TSet[A]) = 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 s.isValid, "The set `s` needs to be initialized."
assert other.isValid, "The set `other` needs to be initialized." assert other.isValid, "The set `other` needs to be initialized."
for item in other: incl(s, item) for item in other: incl(s, item)
proc excl*[A](s: var TSet[A], key: A) = 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." assert s.isValid, "The set needs to be initialized."
var index = rawGet(s, key) var index = rawGet(s, key)
if index >= 0: if index >= 0:
@ -149,14 +215,33 @@ proc excl*[A](s: var TSet[A], key: A) =
dec(s.counter) dec(s.counter)
proc excl*[A](s: var TSet[A], other: TSet[A]) = 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 s.isValid, "The set `s` needs to be initialized."
assert other.isValid, "The set `other` needs to be initialized." assert other.isValid, "The set `other` needs to be initialized."
for item in other: excl(s, item) for item in other: excl(s, item)
proc containsOrIncl*[A](s: var TSet[A], key: A): bool = proc containsOrIncl*[A](s: var TSet[A], key: A): bool =
## returns true if `s` contains `key`, otherwise `key` is included in `s` ## Includes `key` in the set `s` and tells if `key` was added to `s`.
## and false is returned. ##
## 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." assert s.isValid, "The set needs to be initialized."
containsOrInclImpl() 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() ## with other procs from this module with the exception of `isValid()
## <#isValid,TSet[A]>`_ and `len() <#len,TSet[A]>`_. ## <#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 ## discard all its values. This might be more convenient than iterating over
## existing values and calling `excl() <#excl,TSet[A],A>`_ on them. Example: ## 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) newSeq(s.data, initialSize)
proc initSet*[A](initialSize=64): TSet[A] = 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 ## Returns an empty hash set you can assign directly in ``var`` blocks in a
## single line. Example: ## single line. Example:
@ -195,7 +281,14 @@ proc initSet*[A](initialSize=64): TSet[A] =
result.init(initialSize) result.init(initialSize)
proc toSet*[A](keys: openArray[A]): TSet[A] = 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)) result = initSet[A](nextPowerOfTwo(keys.len+10))
for key in items(keys): result.incl(key) for key in items(keys): result.incl(key)
@ -207,20 +300,51 @@ template dollarImpl(): stmt {.dirty.} =
result.add("}") result.add("}")
proc `$`*[A](s: TSet[A]): string = 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." assert s.isValid, "The set needs to be initialized."
dollarImpl() dollarImpl()
proc union*[A](s1, s2: TSet[A]): TSet[A] = proc union*[A](s1, s2: TSet[A]): TSet[A] =
## returns a new set of all items that are contained in at ## Returns the union of the sets `s1` and `s2`.
## least one of `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 s1.isValid, "The set `s1` needs to be initialized."
assert s2.isValid, "The set `s2` needs to be initialized." assert s2.isValid, "The set `s2` needs to be initialized."
result = s1 result = s1
incl(result, s2) incl(result, s2)
proc intersection*[A](s1, s2: TSet[A]): TSet[A] = 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 s1.isValid, "The set `s1` needs to be initialized."
assert s2.isValid, "The set `s2` needs to be initialized." assert s2.isValid, "The set `s2` needs to be initialized."
result = initSet[A](min(s1.data.len, s2.data.len)) 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) if item in s2: incl(result, item)
proc difference*[A](s1, s2: TSet[A]): TSet[A] = 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 s1.isValid, "The set `s1` needs to be initialized."
assert s2.isValid, "The set `s2` needs to be initialized." assert s2.isValid, "The set `s2` needs to be initialized."
result = initSet[A]() result = initSet[A]()
@ -237,8 +372,18 @@ proc difference*[A](s1, s2: TSet[A]): TSet[A] =
incl(result, item) incl(result, item)
proc symmetricDifference*[A](s1, s2: TSet[A]): TSet[A] = proc symmetricDifference*[A](s1, s2: TSet[A]): TSet[A] =
## returns a new set of all items that are contained in either ## Returns the symmetric difference of the sets `s1` and `s2`.
## `s1` or `s2`, but not both ##
## 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 s1.isValid, "The set `s1` needs to be initialized."
assert s2.isValid, "The set `s2` needs to be initialized." assert s2.isValid, "The set `s2` needs to be initialized."
result = s1 result = s1
@ -246,23 +391,32 @@ proc symmetricDifference*[A](s1, s2: TSet[A]): TSet[A] =
if containsOrIncl(result, item): excl(result, item) if containsOrIncl(result, item): excl(result, item)
proc `+`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} = proc `+`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
## alias for `union` ## Alias for `union(s1, s2) <#union>`_.
result = union(s1, s2) result = union(s1, s2)
proc `*`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} = proc `*`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
## alias for `intersection` ## Alias for `intersection(s1, s2) <#intersection>`_.
result = intersection(s1, s2) result = intersection(s1, s2)
proc `-`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} = proc `-`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
## alias for `difference` ## Alias for `difference(s1, s2) <#difference>`_.
result = difference(s1, s2) result = difference(s1, s2)
proc `-+-`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} = proc `-+-`*[A](s1, s2: TSet[A]): TSet[A] {.inline.} =
## alias for `symmetricDifference` ## Alias for `symmetricDifference(s1, s2) <#symmetricDifference>`_.
result = symmetricDifference(s1, s2) result = symmetricDifference(s1, s2)
proc disjoint*[A](s1, s2: TSet[A]): bool = 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 s1.isValid, "The set `s1` needs to be initialized."
assert s2.isValid, "The set `s2` needs to be initialized." assert s2.isValid, "The set `s2` needs to be initialized."
for item in s1: for item in s1:
@ -270,11 +424,33 @@ proc disjoint*[A](s1, s2: TSet[A]): bool =
return true return true
proc `<`*[A](s, t: TSet[A]): bool = 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 s.counter != t.counter and s <= t
proc `<=`*[A](s, t: TSet[A]): bool = 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 result = false
if s.counter > t.counter: return if s.counter > t.counter: return
result = true result = true
@ -284,9 +460,27 @@ proc `<=`*[A](s, t: TSet[A]): bool =
return return
proc `==`*[A](s, t: TSet[A]): bool = 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 s.counter == t.counter and s <= t
proc map*[A, B](data: TSet[A], op: proc (x: A): B {.closure.}): TSet[B] = 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]() result = initSet[B]()
for item in data: result.incl(op(item)) for item in data: result.incl(op(item))
@ -300,7 +494,7 @@ type
final, myShallow.}[A] = object ## \ final, myShallow.}[A] = object ## \
## A generic hash set that remembers insertion order. ## 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. ## <#initOrderedSet>`_ before calling other procs on it.
data: TOrderedKeyValuePairSeq[A] data: TOrderedKeyValuePairSeq[A]
counter, first, last: int 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 ## Most operations over an uninitialized ordered set will crash at runtime
## and `assert <system.html#assert>`_ in debug builds. You can use this proc ## 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: ## correctly initialized. Example:
## ##
## .. code-block :: nimrod ## .. code-block :: nimrod
@ -321,11 +515,21 @@ proc isValid*[A](s: TOrderedSet[A]): bool =
result = not s.data.isNil result = not s.data.isNil
proc len*[A](s: TOrderedSet[A]): int {.inline.} = 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 result = s.counter
proc card*[A](s: TOrderedSet[A]): int {.inline.} = proc card*[A](s: TOrderedSet[A]): int {.inline.} =
## alias for `len`. ## Alias for `len() <#len,TOrderedSet[A]>`_.
result = s.counter result = s.counter
template forAllOrderedPairs(yieldStmt: stmt) {.dirty, immediate.} = template forAllOrderedPairs(yieldStmt: stmt) {.dirty, immediate.} =
@ -336,7 +540,23 @@ template forAllOrderedPairs(yieldStmt: stmt) {.dirty, immediate.} =
h = nxt h = nxt
iterator items*[A](s: TOrderedSet[A]): A = 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." assert s.isValid, "The set needs to be initialized."
forAllOrderedPairs: forAllOrderedPairs:
yield s.data[h].key yield s.data[h].key
@ -345,7 +565,15 @@ proc rawGet[A](s: TOrderedSet[A], key: A): int =
rawGetImpl() rawGetImpl()
proc contains*[A](s: TOrderedSet[A], key: A): bool = 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." assert s.isValid, "The set needs to be initialized."
var index = rawGet(s, key) var index = rawGet(s, key)
result = index >= 0 result = index >= 0
@ -372,19 +600,45 @@ proc enlarge[A](s: var TOrderedSet[A]) =
swap(s.data, n) swap(s.data, n)
proc incl*[A](s: var TOrderedSet[A], key: A) = 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." assert s.isValid, "The set needs to be initialized."
inclImpl() inclImpl()
proc incl*[A](s: var TSet[A], other: TOrderedSet[A]) = 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 s.isValid, "The set `s` needs to be initialized."
assert other.isValid, "The set `other` needs to be initialized." assert other.isValid, "The set `other` needs to be initialized."
for item in other: incl(s, item) for item in other: incl(s, item)
proc containsOrIncl*[A](s: var TOrderedSet[A], key: A): bool = proc containsOrIncl*[A](s: var TOrderedSet[A], key: A): bool =
## returns true if `s` contains `key`, otherwise `key` is included in `s` ## Includes `key` in the set `s` and tells if `key` was added to `s`.
## and false is returned. ##
## 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." assert s.isValid, "The set needs to be initialized."
containsOrInclImpl() 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() ## with other procs from this module with the exception of `isValid()
## <#isValid,TOrderedSet[A]>`_ and `len() <#len,TOrderedSet[A]>`_. ## <#isValid,TOrderedSet[A]>`_ and `len() <#len,TOrderedSet[A]>`_.
## ##
## You can call this method on a previously initialized ordered hash set to ## You can call this proc on a previously initialized ordered hash set to
## discard its values. At the moment this is the only method to remove ## discard its values. At the moment this is the only proc to remove elements
## elements from an ordered hash set. Example: ## from an ordered hash set. Example:
## ##
## .. code-block :: ## .. code-block ::
## var a: TOrderedSet[int] ## var a: TOrderedSet[int]
@ -414,7 +668,8 @@ proc init*[A](s: var TOrderedSet[A], initialSize=64) =
newSeq(s.data, initialSize) newSeq(s.data, initialSize)
proc initOrderedSet*[A](initialSize=64): TOrderedSet[A] = 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`` ## Returns an empty ordered hash set you can assign directly in ``var``
## blocks in a single line. Example: ## blocks in a single line. Example:
@ -425,12 +680,30 @@ proc initOrderedSet*[A](initialSize=64): TOrderedSet[A] =
result.init(initialSize) result.init(initialSize)
proc toOrderedSet*[A](keys: openArray[A]): TOrderedSet[A] = 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)) result = initOrderedSet[A](nextPowerOfTwo(keys.len+10))
for key in items(keys): result.incl(key) for key in items(keys): result.incl(key)
proc `$`*[A](s: TOrderedSet[A]): string = 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." assert s.isValid, "The set needs to be initialized."
dollarImpl() dollarImpl()
@ -459,7 +732,7 @@ proc testModule() =
b.incl((x - 2, y + 1)) b.incl((x - 2, y + 1))
assert a.len == b.card assert a.len == b.card
assert a.len == 2 assert a.len == 2
echo b #echo b
block setContains: block setContains:
var values = initSet[int]() var values = initSet[int]()
@ -469,40 +742,73 @@ proc testModule() =
values.excl(2) values.excl(2)
assert(not values.contains(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: block toSeqAndString:
var a = toSet[int]([2, 4, 5]) var a = toSet([2, 4, 5])
var b = initSet[int]() var b = initSet[int]()
for x in [2, 4, 5]: b.incl(x) for x in [2, 4, 5]: b.incl(x)
assert($a == $b) 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: block setOperations:
var var
a = toset[string](["a", "b"]) a = toSet(["a", "b"])
b = toset[string](["b", "c"]) b = toSet(["b", "c"])
c = union(a, b) c = union(a, b)
assert c == toSet[string](["a", "b", "c"]) assert c == toSet(["a", "b", "c"])
var d = intersection(a, b) var d = intersection(a, b)
assert d == toSet[string](["b"]) assert d == toSet(["b"])
var e = difference(a, b) var e = difference(a, b)
assert e == toSet[string](["a"]) assert e == toSet(["a"])
var f = symmetricDifference(a, b) var f = symmetricDifference(a, b)
assert f == toSet[string](["a", "c"]) assert f == toSet(["a", "c"])
assert d < a and d < b assert d < a and d < b
assert((a < a) == false) assert((a < a) == false)
assert d <= a and d <= b assert d <= a and d <= b
assert((a <= a)) assert((a <= a))
# Alias test. # Alias test.
assert a + b == toSet[string](["a", "b", "c"]) assert a + b == toSet(["a", "b", "c"])
assert a * b == toSet[string](["b"]) assert a * b == toSet(["b"])
assert a - b == toSet[string](["a"]) assert a - b == toSet(["a"])
assert a -+- b == toSet[string](["a", "c"]) assert a -+- b == toSet(["a", "c"])
assert disjoint(a, b) == false assert disjoint(a, b) == false
assert disjoint(a, b - a) == true assert disjoint(a, b - a) == true
block mapSet: block mapSet:
var a = toSet[int]([1, 2, 3]) var a = toSet([1, 2, 3])
var b = a.map(proc (x: int): string = $x) var b = a.map(proc (x: int): string = $x)
assert b == toSet[string](["1", "2", "3"]) assert b == toSet(["1", "2", "3"])
block isValidTest: block isValidTest:
var cards: TOrderedSet[string] var cards: TOrderedSet[string]
@ -528,6 +834,13 @@ proc testModule() =
assert a.len == b.card assert a.len == b.card
assert a.len == 2 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: block setContains:
var values = initOrderedSet[int]() var values = initOrderedSet[int]()
assert(not values.contains(2)) assert(not values.contains(2))
@ -535,7 +848,7 @@ proc testModule() =
assert values.contains(2) assert values.contains(2)
block toSeqAndString: block toSeqAndString:
var a = toOrderedSet[int]([2, 4, 5]) var a = toOrderedSet([2, 4, 5])
var b = initOrderedSet[int]() var b = initOrderedSet[int]()
for x in [2, 4, 5]: b.incl(x) for x in [2, 4, 5]: b.incl(x)
assert($a == $b) assert($a == $b)