std/typetraits

Source Edit

This module defines compile-time reflection procs for working with types.

Unstable API.

Example:

import std/typetraits
type A = enum a0 = 2, a1 = 4, a2
type B = enum b0 = 2, b1, b2
assert A is enum
assert A is HoleyEnum
assert A isnot OrdinalEnum
assert B isnot HoleyEnum
assert B is OrdinalEnum
assert int isnot HoleyEnum
type C[T] = enum h0 = 2, h1 = 4
assert C[float] is HoleyEnum

Imports

since, macros

Types

HoleyEnum = (not Ordinal) and enum

Enum with holes. Source Edit

OrdinalEnum = Ordinal and enum

Enum without holes. Source Edit

StaticParam[value] = object

Used to wrap a static value in genericParams. Source Edit

Procs

proc arity(t: typedesc): int {.magic: "TypeTrait", ...raises: [], tags: [],
                               forbids: [].}

Returns the arity of t. This is the number of "type" components or the number of generic parameters a given type t has.

Example:

doAssert arity(int) == 0
doAssert arity(seq[string]) == 1
doAssert arity(array[3, int]) == 2
doAssert arity((int, int, float, string)) == 4

Source Edit

proc distinctBase(T: typedesc; recursive: static bool = true): typedesc {.
    magic: "TypeTrait", ...raises: [], tags: [], forbids: [].}

Returns the base type for distinct types, or the type itself otherwise. If recursive is false, only the immediate distinct base will be returned.

See also:

• distinctBase template

Example:

type MyInt = distinct int
type MyOtherInt = distinct MyInt
doAssert distinctBase(MyInt) is int
doAssert distinctBase(MyOtherInt) is int
doAssert distinctBase(MyOtherInt, false) is MyInt
doAssert distinctBase(int) is int

Source Edit

proc genericHead(t: typedesc): typedesc {.magic: "TypeTrait", ...raises: [],
    tags: [], forbids: [].}

Accepts an instantiated generic type and returns its uninstantiated form. A compile-time error will be produced if the supplied type is not generic.

See also:

• stripGenericParams proc

Example:

type
  Foo[T] = object
  FooInst = Foo[int]
  Foo2 = genericHead(FooInst)

doAssert Foo2 is Foo and Foo is Foo2
doAssert genericHead(Foo[seq[string]]) is Foo
doAssert not compiles(genericHead(int))

type Generic = concept f
  type _ = genericHead(typeof(f))

proc bar(a: Generic): typeof(a) = a

doAssert bar(Foo[string].default) == Foo[string]()
doAssert not compiles bar(string.default)

when false: # these don't work yet
  doAssert genericHead(Foo[int])[float] is Foo[float]
  doAssert seq[int].genericHead is seq

Source Edit

proc hasClosure(fn: NimNode): bool {....raises: [], tags: [], forbids: [].}

Returns true if the func/proc/etc fn has closure. fn has to be a resolved symbol of kind nnkSym. This implies that the macro that calls this proc should accept typed arguments and not untyped arguments. Source Edit

proc hasDefaultValue(t: typedesc): bool {.magic: "TypeTrait", ...raises: [],
    tags: [], forbids: [].}

Returns true if t has a valid default value.

Example:

{.experimental: "strictNotNil".}
type
  NilableObject = ref object
    a: int
  Object = NilableObject not nil
  RequiresInit[T] = object
    a {.requiresInit.}: T

assert hasDefaultValue(NilableObject)
assert not hasDefaultValue(Object)
assert hasDefaultValue(string)
assert not hasDefaultValue(var string)
assert not hasDefaultValue(RequiresInit[int])

Source Edit

proc isNamedTuple(T: typedesc): bool {.magic: "TypeTrait", ...raises: [], tags: [],
                                       forbids: [].}

Returns true for named tuples, false for any other type.

Example:

doAssert not isNamedTuple(int)
doAssert not isNamedTuple((string, int))
doAssert isNamedTuple(tuple[name: string, age: int])

Source Edit

proc name(t: typedesc): string {.magic: "TypeTrait", ...raises: [], tags: [],
                                 forbids: [].}

Returns the name of t.

Alias for system.`$`(t) since Nim v0.20.

Example:

doAssert name(int) == "int"
doAssert name(seq[string]) == "seq[string]"

Source Edit

proc rangeBase(T: typedesc[range]): typedesc {.magic: "TypeTrait", ...raises: [],
    tags: [], forbids: [].}

Returns the base type for range types, or the type itself otherwise.

See also:

• rangeBase template

Example:

type MyRange = range[0..5]
type MyEnum = enum a, b, c
type MyEnumRange = range[b..c]
doAssert rangeBase(MyRange) is int
doAssert rangeBase(MyEnumRange) is MyEnum
doAssert rangeBase(range['a'..'z']) is char

Source Edit

proc stripGenericParams(t: typedesc): typedesc {.magic: "TypeTrait", ...raises: [],
    tags: [], forbids: [].}

This trait is similar to genericHead, but instead of producing an error for non-generic types, it will just return them unmodified.

Example:

type Foo[T] = object

doAssert stripGenericParams(Foo[string]) is Foo
doAssert stripGenericParams(int) is int

Source Edit

proc supportsCopyMem(t: typedesc): bool {.magic: "TypeTrait", ...raises: [],
    tags: [], forbids: [].}

Returns true if t is safe to use for copyMem.

Other languages name a type like these blob.

Source Edit

proc tupleLen(T: typedesc[tuple]): int {.magic: "TypeTrait", ...raises: [],
    tags: [], forbids: [].}

Returns the number of elements of the tuple type T.

See also:

• tupleLen template

Example:

doAssert tupleLen((int, int, float, string)) == 4
doAssert tupleLen(tuple[name: string, age: int]) == 2

Source Edit

Macros

macro enumLen(T: typedesc[enum]): int

Returns the number of items in the enum T.

Example:

type Foo = enum
  fooItem1
  fooItem2

doAssert Foo.enumLen == 2

Source Edit

Templates

template distinctBase[T](a: T; recursive: static bool = true): untyped

Overload of distinctBase for values.

Example:

type MyInt = distinct int
type MyOtherInt = distinct MyInt
doAssert 12.MyInt.distinctBase == 12
doAssert 12.MyOtherInt.distinctBase == 12
doAssert 12.MyOtherInt.distinctBase(false) is MyInt
doAssert 12.distinctBase == 12

Source Edit

template elementType(a: untyped): typedesc

Returns the element type of a, which can be any iterable (over which you can iterate).

Example:

iterator myiter(n: int): auto =
  for i in 0 ..< n:
    yield i

doAssert elementType(@[1,2]) is int
doAssert elementType("asdf") is char
doAssert elementType(myiter(3)) is int

Source Edit

template genericParams(T: typedesc): untyped

Returns the tuple of generic parameters for the generic type T.

Note: For the builtin array type, the index generic parameter will always become a range type after it's bound to a variable.

Example:

type Foo[T1, T2] = object

doAssert genericParams(Foo[float, string]) is (float, string)

type Bar[N: static float, T] = object

doAssert genericParams(Bar[1.0, string]) is (StaticParam[1.0], string)
doAssert genericParams(Bar[1.0, string]).get(0).value == 1.0
doAssert genericParams(seq[Bar[2.0, string]]).get(0) is Bar[2.0, string]
var s: seq[Bar[3.0, string]]
doAssert genericParams(typeof(s)) is (Bar[3.0, string],)

doAssert genericParams(array[10, int]) is (StaticParam[10], int)
var a: array[10, int]
doAssert genericParams(typeof(a)) is (range[0..9], int)

Source Edit

template get(T: typedesc[tuple]; i: static int): untyped

Returns the i-th element of T.

Example:

doAssert get((int, int, float, string), 2) is float

Source Edit

template pointerBase[T](_: typedesc[ptr T | ref T]): typedesc

Returns T for ref T | ptr T.

Example:

assert (ref int).pointerBase is int
type A = ptr seq[float]
assert A.pointerBase is seq[float]
assert (ref A).pointerBase is A # not seq[float]
assert (var s = "abc"; s[0].addr).typeof.pointerBase is char

Source Edit

template rangeBase[T: range](a: T): untyped

Overload of rangeBase for values.

Example:

type MyRange = range[0..5]
type MyEnum = enum a, b, c
type MyEnumRange = range[b..c]
let x = MyRange(3)
doAssert rangeBase(x) is int
doAssert $typeof(rangeBase(x)) == "int"
doAssert rangeBase(x) == 3
let y: set[MyEnumRange] = {c}
for e in y:
  doAssert rangeBase(e) is MyEnum
  doAssert $typeof(rangeBase(e)) == "MyEnum"
  doAssert rangeBase(e) == c
let z: seq[range['a'..'z']] = @['c']
doAssert rangeBase(z[0]) is char
doAssert $typeof(rangeBase(z[0])) == "char"
doAssert rangeBase(z[0]) == 'c'

Source Edit

template toSigned(T: typedesc[SomeInteger and not range]): untyped

Returns a signed type with same bit size as T.

Example:

assert int8.toSigned is int8
assert uint16.toSigned is int16
# range types are currently unsupported:
assert not compiles(toSigned(range[0..7]))

Source Edit

template toUnsigned(T: typedesc[SomeInteger and not range]): untyped

Returns an unsigned type with same bit size as T.

Example:

assert int8.toUnsigned is uint8
assert uint.toUnsigned is uint
assert int.toUnsigned is uint
# range types are currently unsupported:
assert not compiles(toUnsigned(range[0..7]))

Source Edit

template tupleLen(t: tuple): int

Returns the number of elements of the tuple t.

See also:

• tupleLen proc

Example:

doAssert tupleLen((1, 2)) == 2

Source Edit