add enumutils.items for sparse enums, typetraits.SomeSparseEnum (#17080)

* add enumutils.items for enum with holes
* changelog
* ref in lib.rst
* use `type SomeSparseEnum* = (not Ordinal) and enum` instead of concept
* address comment: rename back to enum with holes

lib/pure/typetraits.nim

@@ -15,6 +15,17 @@
 import std/private/since
 export system.`$` # for backward compatibility
 
+type SomeEnumWithHoles* = (not Ordinal) and enum ## Enum with holes.
+
+runnableExamples:
+  type A = enum a0 = 2, a1 = 4, a2
+  type B = enum b0 = 2, b1, b2
+  assert A is SomeEnumWithHoles
+  assert B isnot SomeEnumWithHoles
+  assert int isnot SomeEnumWithHoles
+  type C[T] = enum h0 = 2, h1 = 4
+  assert C[float] is SomeEnumWithHoles
+
 proc name*(t: typedesc): string {.magic: "TypeTrait".} =
   ## Returns the name of the given type.
   ##

lib/std/enumutils.nim

@@ -7,7 +7,9 @@
 #    distribution, for details about the copyright.
 #
 
-import macros
+import std/macros
+
+# xxx `genEnumCaseStmt` needs tests and runnableExamples
 
 macro genEnumCaseStmt*(typ: typedesc, argSym: typed, default: typed, 
             userMin, userMax: static[int], normalizer: static[proc(s :string): string]): untyped =
@@ -61,4 +63,17 @@ macro genEnumCaseStmt*(typ: typedesc, argSym: typed, default: typed,
     result.add nnkElse.newTree(raiseStmt)
   else:
     expectKind(default, nnkSym)
-    result.add nnkElse.newTree(default)
+    result.add nnkElse.newTree(default)
+
+macro enumWithHolesFullRange(a: typed): untyped = 
+  newNimNode(nnkCurly).add(a.getType[1][1..^1])
+
+iterator items*[T: enum and not Ordinal](E: typedesc[T]): T =
+  ## Iterates over an enum with holes.
+  runnableExamples:
+    type A = enum a0 = 2, a1 = 4, a2
+    type B[T] = enum b0 = 2, b1 = 4
+    from std/sequtils import toSeq
+    assert A.toSeq == [a0, a1, a2]
+    assert B[float].toSeq == [B[float].b0, B[float].b1]
+  for a in enumWithHolesFullRange(E): yield a

lib/system/iterators.nim

@@ -82,8 +82,13 @@ iterator mitems*(a: var cstring): var char {.inline.} =
       yield a[i]
       inc(i)
 
-iterator items*[T: enum](E: typedesc[T]): T =
-  ## Iterates over the values of the enum ``E``.
+iterator items*[T: enum and Ordinal](E: typedesc[T]): T =
+  ## Iterates over the values of `E`.
+  ## See also `enumutils.items` for enums with holes.
+  runnableExamples:
+    type Goo = enum g0 = 2, g1, g2
+    from std/sequtils import toSeq
+    assert Goo.toSeq == [g0, g1, g2]
   for v in low(E) .. high(E):
     yield v