Module options

Abstract

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.

Tutorial

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

try:
  assert("abc".find('c').get() == 2)  # Immediately extract the value
except UnpackError:  # If there is no value
  assert false  # This will not be reached, because the value is present

The get operation demonstrated above returns the underlying value, or raises UnpackError if there is no value. There is another option for obtaining the value: unsafeGet, but you must only use it when you are absolutely sure the value is present (e.g. after checking isSome). If you do not care about the tiny overhead that get causes, you should simply never use unsafeGet.

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)

try:
  echo result.get()
  assert(false)  # This will not be reached
except UnpackError:  # Because an exception is raised
  discard

Imports

typetraits, unittest, sequtils

Types

Option[T] = object
  val: T
  has: bool

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

UnpackError = ref object of ValueError

Procs

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

Returns a Option that has this value.

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

Returns a Option for this type that has no value.

proc isSome[T](self: Option[T]): bool

proc isNone[T](self: Option[T]): bool

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

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

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

Returns contents of the Option. If it is none, then an exception is thrown.

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

Returns the contents of this option or otherwise if the option is none.

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

Applies a callback to the value in this Option

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

Applies a callback to the value in this Option and returns an option containing the new value. If this option is None, None will be returned

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

Applies a callback to the value in this Option. If the callback returns true, the option is returned as a Some. If it returns false, it is returned as a None.

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

Returns true if both Option``s are ``none, or if they have equal values

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

Returns the contents of this option or otherwise if the option is none.