Set type

The set type models the mathematical notion of a set. The set’s basetype can only be an ordinal type of a certain size, namely:

  • int8-int16
  • uint8/byte-uint16
  • char
  • enum
  • Ordinal subrange types, i.e. range[-10..10]

or equivalent. When constructing a set with signed integer literals, the set’s base type is defined to be in the range 0 .. DefaultSetElements-1 where DefaultSetElements is currently always 2^8. The maximum range length for the base type of a set is MaxSetElements which is currently always 2^16. Types with a bigger range length are coerced into the range 0 .. MaxSetElements-1.

The reason is that sets are implemented as high performance bit vectors. Attempting to declare a set with a larger type will result in an error:

  1.   var s: set[int64] # Error: set is too large; use `std/sets` for ordinal types
  2.                     # with more than 2^16 elements

Note: Nim also offers hash sets (which you need to import with import std/sets), which have no such restrictions.

Sets can be constructed via the set constructor: {} is the empty set. The empty set is type compatible with any concrete set type. The constructor can also be used to include elements (and ranges of elements):

  1. type
  2.   CharSet = set[char]
  3. var
  4.   x: CharSet
  5. x = {'a'..'z', '0'..'9'} # This constructs a set that contains the
  6.                          # letters from 'a' to 'z' and the digits
  7.                          # from '0' to '9'

The module `std/setutils` provides a way to initialize a set from an iterable:

  1. import std/setutils
  3. let uniqueChars = myString.toSet

These operations are supported by sets:

operationmeaning
A + Bunion of two sets
A * Bintersection of two sets
A - Bdifference of two sets (A without B’s elements)
A == Bset equality
A <= Bsubset relation (A is subset of B or equal to B)
A < Bstrict subset relation (A is a proper subset of B)
e in Aset membership (A contains element e)
e notin AA does not contain element e
contains(A, e)A contains element e
card(A)the cardinality of A (number of elements in A)
incl(A, elem)same as A = A + {elem}
excl(A, elem)same as A = A - {elem}

Bit fields

Sets are often used to define a type for the flags of a procedure. This is a cleaner (and type safe) solution than defining integer constants that have to be or’ed together.

Enum, sets and casting can be used together as in:

  1. type
  2.   MyFlag* {.size: sizeof(cint).} = enum
  3.     A
  4.     B
  5.     C
  6.     D
  7.   MyFlags = set[MyFlag]
  9. proc toNum(f: MyFlags): int = cast[cint](f)
  10. proc toFlags(v: int): MyFlags = cast[MyFlags](v)
  12. assert toNum({}) == 0
  13. assert toNum({A}) == 1
  14. assert toNum({D}) == 8
  15. assert toNum({A, C}) == 5
  16. assert toFlags(0) == {}
  17. assert toFlags(7) == {A, B, C}

Note how the set turns enum values into powers of 2.

If using enums and sets with C, use distinct cint.

For interoperability with C see also the bitsize pragma.