☰

# std/typeinfo

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

This module implements an interface to Nim's runtime type information (RTTI). See the marshal module for an example of what this allows you to do.

Note: Even though `Any` and its operations hide the nasty low level details from its users, it remains inherently unsafe! Also, Nim's runtime type information will evolve and may eventually be deprecated. As an alternative approach to programmatically understanding and manipulating types, consider using the macros module to work with the types' AST representation at compile time. See for example the getTypeImpl proc. As an alternative approach to storing arbitrary types at runtime, consider using generics.

Example:

    import std/typeinfo
    var x: Any

    var i = 42
    x = i.toAny
    assert x.kind == akInt
    assert x.getInt == 42

    var s = @[1, 2, 3]
    x = s.toAny
    assert x.kind == akSequence
    assert x.len == 3

# Imports

assertions, strimpl

# Types

    Any = object
      when defined(js):
      else:

  A type that can represent any nim value.
  Danger: The wrapped value can be modified with its wrapper! This means that `Any` keeps a non-traced pointer to its wrapped value and must not live longer than its wrapped value.
  Source Edit

    AnyKind = enum
      akNone = 0,               ## invalid
      akBool = 1,               ## bool
      akChar = 2,               ## char
      akEnum = 14,              ## enum
      akArray = 16,             ## array
      akObject = 17,            ## object
      akTuple = 18,             ## tuple
      akSet = 19,               ## set
      akRange = 20,             ## range
      akPtr = 21,               ## ptr
      akRef = 22,               ## ref
      akSequence = 24,          ## sequence
      akProc = 25,              ## proc
      akPointer = 26,           ## pointer
      akString = 28,            ## string
      akCString = 29,           ## cstring
      akInt = 31,               ## int
      akInt8 = 32,              ## int8
      akInt16 = 33,             ## int16
      akInt32 = 34,             ## int32
      akInt64 = 35,             ## int64
      akFloat = 36,             ## float
      akFloat32 = 37,           ## float32
      akFloat64 = 38,           ## float64
      akFloat128 = 39,          ## float128
      akUInt = 40,              ## uint
      akUInt8 = 41,             ## uint8
      akUInt16 = 42,            ## uin16
      akUInt32 = 43,            ## uint32
      akUInt64 = 44              ## uint64

  The kind of `Any`. Source Edit

# Procs

    proc `[]`(x: Any): Any {....raises: [], tags: [], forbids: [].}

  Dereference operator for `Any`. `x` needs to represent a ptr or a ref. Source Edit

    proc `[]`(x: Any; fieldName: string): Any {....raises: [ValueError], tags: [],
        forbids: [].}

  Gets a field of `x`. `x` needs to represent an object or a tuple. Source Edit

    proc `[]`(x: Any; i: int): Any {....raises: [], tags: [], forbids: [].}

  Accessor for an any `x` that represents an array or a sequence. Source Edit

    proc `[]=`(x, y: Any) {....raises: [], tags: [], forbids: [].}

  Dereference operator for `Any`. `x` needs to represent a ptr or a ref. Source Edit

    proc `[]=`(x: Any; fieldName: string; value: Any) {....raises: [ValueError],
        tags: [], forbids: [].}

  Sets a field of `x`. `x` needs to represent an object or a tuple. Source Edit

    proc `[]=`(x: Any; i: int; y: Any) {....raises: [], tags: [], forbids: [].}

  Accessor for an any `x` that represents an array or a sequence. Source Edit

    proc assign(x, y: Any) {....raises: [], tags: [], forbids: [].}

  Copies the value of `y` to `x`. The assignment operator for `Any` does NOT do this; it performs a shallow copy instead! Source Edit

    proc base(x: Any): Any {....raises: [], tags: [], forbids: [].}

  Returns the base type of `x` (useful for inherited object types). Source Edit

    proc baseTypeKind(x: Any): AnyKind {.inline, ...raises: [], tags: [], forbids: [].}

  Gets the base type's kind. If `x` has no base type, `akNone` is returned. Source Edit

    proc baseTypeSize(x: Any): int {.inline, ...raises: [], tags: [], forbids: [].}

  Returns the size of `x`'s base type. If `x` has no base type, 0 is returned. Source Edit

    proc extendSeq(x: Any) {....raises: [], tags: [], forbids: [].}

  Performs `setLen(x, x.len+1)`. `x` needs to represent a `seq`. Source Edit

    proc getBiggestFloat(x: Any): BiggestFloat {....raises: [], tags: [], forbids: [].}

  Retrieves the float value out of `x`. `x` needs to represent some float. The value is extended to `BiggestFloat`. Source Edit

    proc getBiggestInt(x: Any): BiggestInt {....raises: [], tags: [], forbids: [].}

  Retrieves the integer value out of `x`. `x` needs to represent some integer, a bool, a char, an enum or a small enough bit set. The value might be sign-extended to `BiggestInt`. Source Edit

    proc getBiggestUint(x: Any): uint64 {....raises: [], tags: [], forbids: [].}

  Retrieves the unsigned integer value out of `x`. `x` needs to represent an unsigned integer. Source Edit

    proc getBool(x: Any): bool {....raises: [], tags: [], forbids: [].}

  Retrieves the `bool` value out of `x`. `x` needs to represent a `bool`. Source Edit

    proc getChar(x: Any): char {....raises: [], tags: [], forbids: [].}

  Retrieves the `char` value out of `x`. `x` needs to represent a `char`. Source Edit

    proc getCString(x: Any): cstring {....raises: [], tags: [], forbids: [].}

  Retrieves the `cstring` value out of `x`. `x` needs to represent a `cstring`. Source Edit

    proc getEnumField(x: Any): string {....raises: [], tags: [], forbids: [].}

  Gets the enum field name as a string. `x` needs to represent an enum. Source Edit

    proc getEnumField(x: Any; ordinalValue: int): string {....raises: [], tags: [],
        forbids: [].}

  Gets the enum field name as a string. `x` needs to represent an enum but is only used to access the type information. The field name of `ordinalValue` is returned. Source Edit

    proc getEnumOrdinal(x: Any; name: string): int {....raises: [], tags: [],
        forbids: [].}

  Gets the enum field ordinal from `name`. `x` needs to represent an enum but is only used to access the type information. In case of an error `low(int)` is returned. Source Edit

    proc getFloat(x: Any): float {....raises: [], tags: [], forbids: [].}

  Retrieves the `float` value out of `x`. `x` needs to represent a `float`. Source Edit

    proc getFloat32(x: Any): float32 {....raises: [], tags: [], forbids: [].}

  Retrieves the `float32` value out of `x`. `x` needs to represent a `float32`. Source Edit

    proc getFloat64(x: Any): float64 {....raises: [], tags: [], forbids: [].}

  Retrieves the `float64` value out of `x`. `x` needs to represent a `float64`. Source Edit

    proc getInt(x: Any): int {....raises: [], tags: [], forbids: [].}

  Retrieves the `int` value out of `x`. `x` needs to represent an `int`. Source Edit

    proc getInt8(x: Any): int8 {....raises: [], tags: [], forbids: [].}

  Retrieves the `int8` value out of `x`. `x` needs to represent an `int8`. Source Edit

    proc getInt16(x: Any): int16 {....raises: [], tags: [], forbids: [].}

  Retrieves the `int16` value out of `x`. `x` needs to represent an `int16`. Source Edit

    proc getInt32(x: Any): int32 {....raises: [], tags: [], forbids: [].}

  Retrieves the `int32` value out of `x`. `x` needs to represent an `int32`. Source Edit

    proc getInt64(x: Any): int64 {....raises: [], tags: [], forbids: [].}

  Retrieves the `int64` value out of `x`. `x` needs to represent an `int64`. Source Edit

    proc getPointer(x: Any): pointer {....raises: [], tags: [], forbids: [].}

  Retrieves the pointer value out of `x`. `x` needs to be of kind `akString`, `akCString`, `akProc`, `akRef`, `akPtr`, `akPointer` or `akSequence`. Source Edit

    proc getString(x: Any): string {....raises: [], tags: [], forbids: [].}

  Retrieves the `string` value out of `x`. `x` needs to represent a `string`. Source Edit

    proc getUInt(x: Any): uint {....raises: [], tags: [], forbids: [].}

  Retrieves the `uint` value out of `x`. `x` needs to represent a `uint`. Source Edit

    proc getUInt8(x: Any): uint8 {....raises: [], tags: [], forbids: [].}

  Retrieves the `uint8` value out of `x`. `x` needs to represent a `uint8`. Source Edit

    proc getUInt16(x: Any): uint16 {....raises: [], tags: [], forbids: [].}

  Retrieves the `uint16` value out of `x`. `x` needs to represent a `uint16`. Source Edit

    proc getUInt32(x: Any): uint32 {....raises: [], tags: [], forbids: [].}

  Retrieves the `uint32` value out of `x`. `x` needs to represent a `uint32`. Source Edit

    proc getUInt64(x: Any): uint64 {....raises: [], tags: [], forbids: [].}

  Retrieves the `uint64` value out of `x`. `x` needs to represent a `uint64`. Source Edit

    proc inclSetElement(x: Any; elem: int) {....raises: [], tags: [], forbids: [].}

  Includes an element `elem` in `x`. `x` needs to represent a Nim bitset. Source Edit

    proc invokeNew(x: Any) {....raises: [], tags: [], forbids: [].}

  Performs `new(x)`. `x` needs to represent a `ref`. Source Edit

    proc invokeNewSeq(x: Any; len: int) {....raises: [], tags: [], forbids: [].}

  Performs `newSeq(x, len)`. `x` needs to represent a `seq`. Source Edit

    proc isNil(x: Any): bool {....raises: [], tags: [], forbids: [].}

  `isNil` for an `x` that represents a cstring, proc or some pointer type. Source Edit

    proc kind(x: Any): AnyKind {.inline, ...raises: [], tags: [], forbids: [].}

  Gets the type kind. Source Edit

    proc len(x: Any): int {....raises: [], tags: [], forbids: [].}

  `len` for an any `x` that represents an array or a sequence. Source Edit

    proc setBiggestFloat(x: Any; y: BiggestFloat) {....raises: [], tags: [],
        forbids: [].}

  Sets the float value of `x`. `x` needs to represent some float. Source Edit

    proc setBiggestInt(x: Any; y: BiggestInt) {....raises: [], tags: [], forbids: [].}

  Sets the integer value of `x`. `x` needs to represent some integer, a bool, a char, an enum or a small enough bit set. Source Edit

    proc setBiggestUint(x: Any; y: uint64) {....raises: [], tags: [], forbids: [].}

  Sets the unsigned integer value of `x`. `x` needs to represent an unsigned integer. Source Edit

    proc setObjectRuntimeType(x: Any) {....raises: [], tags: [], forbids: [].}

  This needs to be called to set `x`'s runtime object type field. Source Edit

    proc setPointer(x: Any; y: pointer) {....raises: [], tags: [], forbids: [].}

  Sets the pointer value of `x`. `x` needs to be of kind `akString`, `akCString`, `akProc`, `akRef`, `akPtr`, `akPointer` or `akSequence`. Source Edit

    proc setString(x: Any; y: string) {....raises: [], tags: [], forbids: [].}

  Sets the `string` value of `x`. `x` needs to represent a `string`. Source Edit

    proc size(x: Any): int {.inline, ...raises: [], tags: [], forbids: [].}

  Returns the size of `x`'s type. Source Edit

    proc skipRange(x: Any): Any {....raises: [], tags: [], forbids: [].}

  Skips the range information of `x`. Source Edit

    proc toAny[T](x: var T): Any {.inline.}

  Constructs an `Any` object from `x`. This captures `x`'s address, so `x` can be modified with its `Any` wrapper! The caller needs to ensure that the wrapper does not live longer than `x`! Source Edit

# Iterators

    iterator elements(x: Any): int {....raises: [], tags: [], forbids: [].}

  Iterates over every element of `x`. `x` needs to represent a `set`. Source Edit

    iterator fields(x: Any): tuple[name: string, any: Any] {....raises: [], tags: [],
        forbids: [].}

  Iterates over every active field of `x`. `x` needs to represent an object or a tuple. Source Edit