better docs: options (#10720)

lib/pure/options.nim

@@ -7,21 +7,18 @@
 #    distribution, for details about the copyright.
 #
 
-## Abstract
-## ========
-##
 ## This module implements types which encapsulate an optional value.
 ##
-## A value of type ``Option[T]`` either contains a value `x` (represented as
+## A value of type `Option[T]` either contains a value `x` (represented as
-## ``some(x)``) or is empty (``none(T)``).
+## `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
+## absence of a value is often represented by `nil`, but it is not always
 ## available, nor is it always a good solution.
 ##
 ##
-## Tutorial
+## Basic usage
-## ========
+## ===========
 ##
 ## Let's start with an example: a procedure that finds the index of a character
 ## in a string.
@@ -41,16 +38,12 @@
 ##
 ##    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 catched. Instead, rely on
-## checking if the option contains a value with ``isSome`` and ``isNone``.
 ##
-## There is another option for obtaining the value: ``unsafeGet``, but you must
+## The `get` operation demonstrated above returns the underlying value, or
-## only use it when you are absolutely sure the value is present (e.g. after
+## raises `UnpackError` if there is no value. Note that `UnpackError`
-## checking ``isSome``). If you do not care about the tiny overhead that ``get``
+## inherits from `system.Defect`, and should therefore never be caught.
-## causes, you should simply never use ``unsafeGet``.
+## Instead, rely on checking if the option contains a value with
+## `isSome <#isSome,Option[T]>`_ and `isNone <#isNone,Option[T]>`_ procs.
 ##
 ## How to deal with an absence of a value:
 ##
@@ -79,8 +72,44 @@ type
 
   UnpackError* = object of Defect
 
+
+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 <#some,T>`_
+  ## * `none <#none,typedesc>`_
+  runnableExamples:
+    type
+      Foo = ref object
+        a: int
+        b: string
+    var c: Foo
+    assert c.isNil
+    var d = option(c)
+    assert d.isNone
+
+  result.val = val
+  when T isnot SomePointer:
+    result.has = true
+
 proc some*[T](val: T): Option[T] =
-  ## Returns a ``Option`` that has this value.
+  ## Returns an `Option` that has the value `val`.
+  ##
+  ## See also:
+  ## * `option <#option,T>`_
+  ## * `none <#none,typedesc>`_
+  ## * `isSome <#isSome,Option[T]>`_
+  runnableExamples:
+    var
+      a = some("abc")
+      b = some(42)
+    assert $type(a) == "Option[system.string]"
+    assert b.isSome
+    assert a.get == "abc"
+    assert $b == "Some(42)"
+
   when T is SomePointer:
     assert val != nil
     result.val = val
@@ -88,107 +117,240 @@ proc some*[T](val: T): Option[T] =
     result.has = true
     result.val = val
 
-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.
-  result.val = val
-  when T isnot SomePointer:
-    result.has = true
-
 proc none*(T: typedesc): Option[T] =
-  ## Returns an ``Option`` for this type that has no value.
+  ## Returns an `Option` for this type that has no value.
+  ##
+  ## See also:
+  ## * `option <#option,T>`_
+  ## * `some <#some,T>`_
+  ## * `isNone <#isNone,Option[T]>`_
+  runnableExamples:
+    var a = none(int)
+    assert a.isNone
+    assert $type(a) == "Option[system.int]"
+
   # the default is the none type
   discard
 
 proc none*[T]: Option[T] =
-  ## Alias for ``none(T)``.
+  ## Alias for `none(T) proc <#none,typedesc>`_.
   none(T)
 
 proc isSome*[T](self: Option[T]): bool {.inline.} =
+  ## Checks if an `Option` contains a value.
+  runnableExamples:
+    var
+      a = some(42)
+      b = none(string)
+    assert a.isSome
+    assert not b.isSome
+
   when T is SomePointer:
     self.val != nil
   else:
     self.has
 
 proc isNone*[T](self: Option[T]): bool {.inline.} =
+  ## Checks if an `Option` is empty.
+  runnableExamples:
+    var
+      a = some(42)
+      b = none(string)
+    assert not a.isNone
+    assert b.isNone
   when T is SomePointer:
     self.val == nil
   else:
     not self.has
 
-proc unsafeGet*[T](self: Option[T]): T =
-  ## Returns the value of a ``some``. Behavior is undefined for ``none``.
-  assert self.isSome
-  self.val
-
 proc get*[T](self: Option[T]): T =
-  ## Returns contents of the Option. If it is none, then an exception is
+  ## Returns contents of an `Option`. If it is `None`, then an exception is
   ## thrown.
+  ##
+  ## See also:
+  ## * `get proc <#get,Option[T],T>`_ with the default return value
+  runnableExamples:
+    let
+      a = some(42)
+      b = none(string)
+    assert a.get == 42
+    doAssertRaises(UnpackError):
+      echo b.get
+
   if self.isNone:
     raise newException(UnpackError, "Can't obtain a value from a `none`")
   self.val
 
 proc get*[T](self: Option[T], otherwise: T): T =
-  ## Returns the contents of this option or `otherwise` if the option is none.
+  ## Returns the contents of the `Option` or an `otherwise` value if
+  ## the `Option` is `None`.
+  runnableExamples:
+    var
+      a = some(42)
+      b = none(int)
+    assert a.get(9999) == 42
+    assert b.get(9999) == 9999
+
   if self.isSome:
     self.val
   else:
     otherwise
 
 proc get*[T](self: var Option[T]): var T =
-  ## Returns contents of the Option. If it is none, then an exception is
+  ## Returns contents of the `var Option`. If it is `None`, then an exception
-  ## thrown.
+  ## is thrown.
+  runnableExamples:
+    let
+      a = some(42)
+      b = none(string)
+    assert a.get == 42
+    doAssertRaises(UnpackError):
+      echo b.get
+
   if self.isNone:
     raise newException(UnpackError, "Can't obtain a value from a `none`")
   return self.val
 
 proc map*[T](self: Option[T], callback: proc (input: T)) =
-  ## Applies a callback to the value in this Option
+  ## Applies a `callback` function to the value of the `Option`, if it has one.
+  ##
+  ## See also:
+  ## * `map proc <#map,Option[T],proc(T)_2>`_ for a version with a callback
+  ##   which returns a value
+  ## * `filter proc <#filter,Option[T],proc(T)>`_
+  runnableExamples:
+    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
+
   if self.isSome:
     callback(self.val)
 
 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
+  ## Applies a `callback` function to the value of the `Option` and returns an
-  ## containing the new value. If this option is None, None will be returned
+  ## `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 <#flatMap,Option[A],proc(A)>`_ for a version with a
+  ##   callback which returns an `Option`
+  ## * `filter proc <#filter,Option[T],proc(T)>`_
+  runnableExamples:
+    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]"
+
   if self.isSome:
     some[R]( callback(self.val) )
   else:
     none(R)
 
 proc flatten*[A](self: Option[Option[A]]): Option[A] =
-  ## Remove one level of structure in a nested Option.
+  ## Remove one level of structure in a nested `Option`.
+  runnableExamples:
+    let a = some(some(42))
+    assert $flatten(a) == "Some(42)"
+
   if self.isSome:
     self.val
   else:
     none(A)
 
 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
+  ## Applies a `callback` function to the value of the `Option` and returns an
-  ## option containing the new value. If this option is None, None will be
+  ## `Option` containing the new value.
-  ## returned. Similar to ``map``, with the difference that the callback
+  ##
-  ## returns an Option, not a raw value. This allows multiple procs with a
+  ## If the `Option` is `None`, `None` of the return type of the `callback`
-  ## signature of ``A -> Option[B]`` (including A = B) to be chained together.
+  ## 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 <#flatten,Option[Option[A]]>`_
+  ## * `filter proc <#filter,Option[T],proc(T)>`_
+  runnableExamples:
+    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)
+
   map(self, callback).flatten()
 
 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
+  ## Applies a `callback` to the value of the `Option`.
-  ## `true`, the option is returned as a Some. If it returns false, it is
+  ##
-  ## returned as a None.
+  ## If the `callback` returns `true`, the option is returned as `Some`.
+  ## If it returns `false`, it is returned as `None`.
+  ##
+  ## See also:
+  ## * `map proc <#map,Option[T],proc(T)_2>`_
+  ## * `flatMap proc <#flatMap,Option[A],proc(A)>`_
+  runnableExamples:
+    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)
+
   if self.isSome and not callback(self.val):
     none(T)
   else:
     self
 
 proc `==`*(a, b: Option): bool =
-  ## Returns ``true`` if both ``Option``s are ``none``,
+  ## Returns `true` if both `Option`s are `None`,
-  ## or if they have equal values
+  ## or if they are both `Some` and have equal values.
+  runnableExamples:
+    let
+      a = some(42)
+      b = none(int)
+      c = some(42)
+      d = none(int)
+
+    assert a == c
+    assert b == d
+    assert not (a == b)
+
   (a.isSome and b.isSome and a.val == b.val) or (not a.isSome and not b.isSome)
 
 proc `$`*[T](self: Option[T]): string =
-  ## Get the string representation of this option. If the option has a value,
+  ## Get the string representation of the `Option`.
-  ## 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
+  ## If the `Option` has a value, the result will be `Some(x)` where `x`
-  ## the type contained in the option.
+  ## 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`.
   if self.isSome:
     result = "Some("
     result.addQuoted self.val
@@ -196,6 +358,16 @@ proc `$`*[T](self: Option[T]): string =
   else:
     result = "None[" & name(T) & "]"
 
+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 <#isSome,Option[T]>`_).
+  ## Generally, using `get proc <#get,Option[T]>`_ is preferred.
+  assert self.isSome
+  self.val
+
+
 when isMainModule:
   import unittest, sequtils