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

IntSet documentation notes (#10051)

Browse source
This commit is contained in:
Alexis Hope 2018-12-22 08:55:58 +11:00 • committed by Andreas Rumpf
commit bec493925f
1 changed files with 27 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

35
lib/pure/collections/intsets.nim
View file

@ -9,9 +9,12 @@
## The ``intsets`` module implements an efficient int set implemented as a ## The ``intsets`` module implements an efficient int set implemented as a
## `sparse bit set`:idx:. ## `sparse bit set`:idx:.
## **Note**: Since Nim currently does not allow the assignment operator to
## be overloaded, ``=`` for int sets performs some rather meaningless shallow ## **Note**: Currently the assignment operator ``=`` for ``intsets``
## copy; use ``assign`` to get a deep copy. ## performs some rather meaningless shallow copy. Since Nim currently does
## not allow the assignment operator to be overloaded, use ``assign`` to
## get a deep copy.
import import
hashes, math hashes, math
@ -94,7 +97,7 @@ proc intSetPut(t: var IntSet, key: int): PTrunk =
t.data[h] = result t.data[h] = result
proc contains*(s: IntSet, key: int): bool = proc contains*(s: IntSet, key: int): bool =
## returns true iff `key` is in `s`. ## Returns true iff `key` is in `s`.
if s.elems <= s.a.len: if s.elems <= s.a.len:
for i in 0..<s.elems: for i in 0..<s.elems:
if s.a[i] == key: return true if s.a[i] == key: return true
@ -107,7 +110,7 @@ proc contains*(s: IntSet, key: int): bool =
result = false result = false
iterator items*(s: IntSet): int {.inline.} = iterator items*(s: IntSet): int {.inline.} =
## iterates over any included element of `s`. ## Iterates over any included element of `s`.
if s.elems <= s.a.len: if s.elems <= s.a.len:
for i in 0..<s.elems: for i in 0..<s.elems:
yield s.a[i] yield s.a[i]
@ -135,7 +138,7 @@ proc bitincl(s: var IntSet, key: int) {.inline.} =
`shl`(1, u and IntMask) `shl`(1, u and IntMask)
proc incl*(s: var IntSet, key: int) = proc incl*(s: var IntSet, key: int) =
## includes an element `key` in `s`. ## Includes an element `key` in `s`.
if s.elems <= s.a.len: if s.elems <= s.a.len:
for i in 0..<s.elems: for i in 0..<s.elems:
if s.a[i] == key: return if s.a[i] == key: return
@ -170,7 +173,7 @@ proc exclImpl(s: var IntSet, key: int) =
not `shl`(1, u and IntMask) not `shl`(1, u and IntMask)
proc excl*(s: var IntSet, key: int) = proc excl*(s: var IntSet, key: int) =
## excludes `key` from the set `s`. ## Excludes `key` from the set `s`.
exclImpl(s, key) exclImpl(s, key)
proc excl*(s: var IntSet, other: IntSet) = proc excl*(s: var IntSet, other: IntSet) =
@ -178,14 +181,14 @@ proc excl*(s: var IntSet, other: IntSet) =
for item in other: excl(s, item) for item in other: excl(s, item)
proc missingOrExcl*(s: var IntSet, key: int) : bool = proc missingOrExcl*(s: var IntSet, key: int) : bool =
## returns true if `s` does not contain `key`, otherwise ## Returns true if `s` does not contain `key`, otherwise
## `key` is removed from `s` and false is returned. ## `key` is removed from `s` and false is returned.
var count = s.elems var count = s.elems
exclImpl(s, key) exclImpl(s, key)
result = count == s.elems result = count == s.elems
proc containsOrIncl*(s: var IntSet, key: int): bool = proc containsOrIncl*(s: var IntSet, key: int): bool =
## returns true if `s` contains `key`, otherwise `key` is included in `s` ## Returns true if `s` contains `key`, otherwise `key` is included in `s`
## and false is returned. ## and false is returned.
if s.elems <= s.a.len: if s.elems <= s.a.len:
for i in 0..<s.elems: for i in 0..<s.elems:
@ -206,7 +209,11 @@ proc containsOrIncl*(s: var IntSet, key: int): bool =
result = false result = false
proc initIntSet*: IntSet = proc initIntSet*: IntSet =
## creates a new int set that is empty. ## Returns an empty IntSet. Example:
##
## .. code-block ::
## var a = initIntSet()
## a.incl(2)
# newSeq(result.data, InitIntSetSize) # newSeq(result.data, InitIntSetSize)
# result.max = InitIntSetSize-1 # result.max = InitIntSetSize-1
@ -220,6 +227,8 @@ proc initIntSet*: IntSet =
result.elems = 0 result.elems = 0
proc clear*(result: var IntSet) = proc clear*(result: var IntSet) =
## Clears the IntSet back to an empty state.
# setLen(result.data, InitIntSetSize) # setLen(result.data, InitIntSetSize)
# for i in 0..InitIntSetSize-1: result.data[i] = nil # for i in 0..InitIntSetSize-1: result.data[i] = nil
# result.max = InitIntSetSize-1 # result.max = InitIntSetSize-1
@ -304,7 +313,7 @@ proc `-`*(s1, s2: IntSet): IntSet {.inline.} =
result = difference(s1, s2) result = difference(s1, s2)
proc disjoint*(s1, s2: IntSet): bool = proc disjoint*(s1, s2: IntSet): bool =
## Returns true iff the sets `s1` and `s2` have no items in common. ## Returns true if the sets `s1` and `s2` have no items in common.
for item in s1: for item in s1:
if contains(s2, item): if contains(s2, item):
return false return false
@ -320,7 +329,7 @@ proc len*(s: IntSet): int {.inline.} =
inc(result) inc(result)
proc card*(s: IntSet): int {.inline.} = proc card*(s: IntSet): int {.inline.} =
## alias for `len() <#len>` _. ## Alias for `len() <#len>` _.
result = s.len() result = s.len()
proc `<=`*(s1, s2: IntSet): bool = proc `<=`*(s1, s2: IntSet): bool =
@ -350,7 +359,7 @@ proc `$`*(s: IntSet): string =
dollarImpl() dollarImpl()
proc empty*(s: IntSet): bool {.inline, deprecated.} = proc empty*(s: IntSet): bool {.inline, deprecated.} =
## returns true if `s` is empty. This is safe to call even before ## Returns true if `s` is empty. This is safe to call even before
## the set has been initialized with `initIntSet`. Note this never ## the set has been initialized with `initIntSet`. Note this never
## worked reliably and so is deprecated. ## worked reliably and so is deprecated.
result = s.counter == 0 result = s.counter == 0