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
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 = ref object of ValueError
- Source Edit
Procs
proc some[T](val: T): Option[T]
- Returns a Option that has this value. Source Edit
proc option[T](val: T): Option[T]
- Can be used to convert a pointer type to an option type. It converts nil to the none-option. Source Edit
proc none(T: typedesc): Option[T]
- Returns an Option for this type that has no value. Source Edit
proc none[T](): Option[T]
- Alias for none(T). Source Edit
proc isSome[T](self: Option[T]): bool {...}{.inline.}
- unequals operator. This is a shorthand for not (x == y). Source Edit
proc isNone[T](self: Option[T]): bool {...}{.inline.}
- Source Edit
proc unsafeGet[T](self: Option[T]): T
- Returns the value of a some. Behavior is undefined for none. Source Edit
proc get[T](self: Option[T]): T
- Returns contents of the Option. If it is none, then an exception is thrown. Source Edit
proc get[T](self: Option[T]; otherwise: T): T
- Returns the contents of this option or otherwise if the option is none. Source Edit
proc get[T](self: var Option[T]): var T
- Returns contents of the Option. If it is none, then an exception is thrown. Source Edit
proc map[T](self: Option[T]; callback: proc (input: T))
- Applies a callback to the value in this Option Source Edit
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 Source Edit
proc flatten[A](self: Option[Option[A]]): Option[A]
- Remove one level of structure in a nested Option. Source Edit
proc flatMap[A, B](self: Option[A]; callback: proc (input: A): Option[B]): Option[B]
- 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. 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] (including A = B) to be chained together. Source Edit
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. Source Edit
proc `==`(a, b: Option): bool
- Returns true if both Option``s are ``none, or if they have equal values Source Edit
proc `$`[T](self: Option[T]): string
- Get the string representation of this 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