# options

- Manual
- Standard library
- Index

Search:
Group by:

This module implements types which encapsulate an optional value.

A value of type `Option[T]` either contains a value `x` (represented as `some(x)`) or is empty (`none(T)`).

This can be useful when you have a value that can be present or not. The absence of a value is often represented by `nil`, but it is not always available, nor is it always a good solution.

# Basic usage

Let's start with an example: a procedure that finds the index of a character in a string.

    import options

    proc find(haystack: string, needle: char): Option[int] =
      for i, c in haystack:
        if c == needle:
          return some(i)
      return none(int)  # This line is actually optional,
                        # because the default is empty

    let found = "abc".find('c')
    assert found.isSome and found.get() == 2

The `get` operation demonstrated above returns the underlying value, or raises `UnpackError` if there is no value. Note that `UnpackError` inherits from `system.Defect`, and should therefore never be caught. Instead, rely on checking if the option contains a value with isSome and isNone procs.

How to deal with an absence of a value:

    let result = "team".find('i')

    # Nothing was found, so the result is `none`.
    assert(result == none(int))
    # It has no value:
    assert(result.isNone)

# Imports

typetraits, unittest, sequtils

# Types

    Option[T] = object
      when T is SomePointer:
        val
      else:
          val
          has

  An optional type that stores its value and state separately in a boolean. Source Edit

    UnpackError = object of Defect

  Source Edit

# Procs

    proc option[T](val: T): Option[T]

  Can be used to convert a pointer type (`ptr` or `ref`) to an option type. It converts `nil` to `None`.

  See also:

  - some
  - none

  Examples:

      type
        Foo = ref object
          a: int
          b: string

      var c: Foo
      assert c.isNil
      var d = option(c)
      assert d.isNone

  Source Edit

    proc some[T](val: T): Option[T]

  Returns an `Option` that has the value `val`.

  See also:

  - option
  - none
  - isSome

  Examples:

      var
        a = some("abc")
        b = some(42)
      assert $type(a) == "Option[system.string]"
      assert b.isSome
      assert a.get == "abc"
      assert $b == "Some(42)"

  Source Edit

    proc none(T: typedesc): Option[T]

  Returns an `Option` for this type that has no value.

  See also:

  - option
  - some
  - isNone

  Examples:

      var a = none(int)
      assert a.isNone
      assert $type(a) == "Option[system.int]"

  Source Edit

    proc none[T](): Option[T]

  Alias for none(T) proc. Source Edit

    proc isSome[T](self: Option[T]): bool {...}{.inline.}

  Checks if an `Option` contains a value.

  Examples:

      var
        a = some(42)
        b = none(string)
      assert a.isSome
      assert not b.isSome

  Source Edit

    proc isNone[T](self: Option[T]): bool {...}{.inline.}

  Checks if an `Option` is empty.

  Examples:

      var
        a = some(42)
        b = none(string)
      assert not a.isNone
      assert b.isNone

  Source Edit

    proc get[T](self: Option[T]): T

  Returns contents of an `Option`. If it is `None`, then an exception is thrown.

  See also:

  - get proc with the default return value

  Examples:

      let
        a = some(42)
        b = none(string)
      assert a.get == 42
      doAssertRaises(UnpackError):
        echo b.get

  Source Edit

    proc get[T](self: Option[T]; otherwise: T): T

  Returns the contents of the `Option` or an `otherwise` value if the `Option` is `None`.

  Examples:

      var
        a = some(42)
        b = none(int)
      assert a.get(9999) == 42
      assert b.get(9999) == 9999

  Source Edit

    proc get[T](self: var Option[T]): var T

  Returns contents of the `var Option`. If it is `None`, then an exception is thrown.

  Examples:

      let
        a = some(42)
        b = none(string)
      assert a.get == 42
      doAssertRaises(UnpackError):
        echo b.get

  Source Edit

    proc map[T](self: Option[T]; callback: proc (input: T))

  Applies a `callback` function to the value of the `Option`, if it has one.

  See also:

  - map proc for a version with a callback which returns a value
  - filter proc

  Examples:

      var d = 0
      proc saveDouble(x: int) =
        d = 2 * x

      let
        a = some(42)
        b = none(int)
      b.map(saveDouble)
      assert d == 0
      a.map(saveDouble)
      assert d == 84

  Source Edit

    proc map[T, R](self: Option[T]; callback: proc (input: T): R): Option[R]

  Applies a `callback` function to the value of the `Option` and returns an `Option` containing the new value.

  If the `Option` is `None`, `None` of the return type of the `callback` will be returned.

  See also:

  - flatMap proc for a version with a callback which returns an `Option`
  - filter proc

  Examples:

      var
        a = some(42)
        b = none(int)
      proc isEven(x: int): bool =
        x mod 2 == 0

      assert $(a.map(isEven)) == "Some(true)"
      assert $(b.map(isEven)) == "None[bool]"

  Source Edit

    proc flatten[A](self: Option[Option[A]]): Option[A]

  Remove one level of structure in a nested `Option`.

  Examples:

      let a = some(some(42))
      assert $flatten(a) == "Some(42)"

  Source Edit

    proc flatMap[A, B](self: Option[A]; callback: proc (input: A): Option[B]): Option[B]

  Applies a `callback` function to the value of the `Option` and returns an `Option` containing the new value.

  If the `Option` is `None`, `None` of the return type of the `callback` will be returned.

  Similar to `map`, with the difference that the `callback` returns an `Option`, not a raw value. This allows multiple procs with a signature of `A -> Option[B]` to be chained together.

  See also:

  - flatten proc
  - filter proc

  Examples:

      proc doublePositives(x: int): Option[int] =
        if x > 0:
          return some(2 * x)
        else:
          return none(int)

      let
        a = some(42)
        b = none(int)
        c = some(-11)
      assert a.flatMap(doublePositives) == some(84)
      assert b.flatMap(doublePositives) == none(int)
      assert c.flatMap(doublePositives) == none(int)

  Source Edit

    proc filter[T](self: Option[T]; callback: proc (input: T): bool): Option[T]

  Applies a `callback` to the value of the `Option`.

  If the `callback` returns `true`, the option is returned as `Some`. If it returns `false`, it is returned as `None`.

  See also:

  - map proc
  - flatMap proc

  Examples:

      proc isEven(x: int): bool =
        x mod 2 == 0

      let
        a = some(42)
        b = none(int)
        c = some(-11)
      assert a.filter(isEven) == some(42)
      assert b.filter(isEven) == none(int)
      assert c.filter(isEven) == none(int)

  Source Edit

    proc `==`(a, b: Option): bool

  Returns `true` if both `Option`s are `None`, or if they are both `Some` and have equal values.

  Examples:

      let
        a = some(42)
        b = none(int)
        c = some(42)
        d = none(int)
      assert a == c
      assert b == d
      assert not (a == b)

  Source Edit

    proc `$`[T](self: Option[T]): string

  Get the string representation of the `Option`.

  If the `Option` has a value, the result will be `Some(x)` where `x` is the string representation of the contained value. If the `Option` does not have a value, the result will be `None[T]` where `T` is the name of the type contained in the `Option`.

  Source Edit

    proc unsafeGet[T](self: Option[T]): T

  Returns the value of a `some`. Behavior is undefined for `none`.

  Note: Use it only when you are absolutely sure the value is present (e.g. after checking isSome). Generally, using get proc is preferred.

  Source Edit