std/options

Этот модуль реализует типы, которые инкапсулируют необязательное значение.

Значение типа Option[T] либо содержит значение x (представленное как some(x)) либо является пустым (none(T)).

Это может быть полезно, когда у вас есть значение, которое может быть присутствующим или отсутствующим. Отсутствие значения часто обозначается как nil, но это не всегда доступно, и не всегда является хорошим решением.

Основное использование

Начнём с примера: процедура, которая находит индекс символа в строке.

Пример:

import std/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

Обработка по образцу

fusion/matching поддерживает обработку по образцу для Option, с шаблонами Some(<pattern>) и None().

{.experimental: "caseStmtMacros".}

import fusion/matching

case some(42)
of Some(@a):
  assert a == 42
of None():
  assert false

assertMatch(some(some(none(int))), Some(Some(None())))

Импорты

typetraits

Типы

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

Необязательный тип, который может или не может содержать значение типа T. Когда T является указателем (ptr, pointer, ref, proc или iterator {.closure.}), none(T) представлен как nil. Source Edit

UnpackDefect = object of Defect

Source Edit

UnpackError {....deprecated: "See corresponding Defect".} = UnpackDefect

Устаревшее: См. соответствующий дефект

Source Edit

Процедуры

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

Получить строковое представление Option.

Пример:

assert $some(42) == "some(42)"
assert $none(int) == "none(int)"

Исходный код Редактировать

proc `==`[T](a, b: Option[T]): bool {.inline.}

Возвращает true, если оба Option являются none, или если они оба some и имеют равные значения.

Пример:

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

assert a == c
assert b == d
assert not (a == b)

Исходный код Редактировать

proc filter[T](self: Option[T]; callback: proc (input: T): bool): Option[T] {.
    inline, effectsOf: callback.}

Применяет callback к значению Option.

Если callback возвращает true, опция возвращается как some. Если возвращает false, она возвращается как none.

См. также:

• flatMap proc

Пример:

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

assert some(42).filter(isEven) == some(42)
assert none(int).filter(isEven) == none(int)
assert some(-11).filter(isEven) == none(int)

Исходный код Редактировать

proc flatMap[T, R](self: Option[T]; callback: proc (input: T): Option[R]): Option[
    R] {.inline, effectsOf: callback.}

Применяет функцию callback к значению Option и возвращает новое значение.

Если Option не имеет значения, возвращается none(R).

Аналогично map, с разницей в том, что callback возвращает Option, а не простое значение. Это позволяет объединять несколько процедур с сигнатурой A -> Option[B].

См. также:

• flatten proc
• filter proc

Пример:

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

assert some(42).flatMap(doublePositives) == some(84)
assert none(int).flatMap(doublePositives) == none(int)
assert some(-11).flatMap(doublePositives) == none(int)

Исходный код Редактировать

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

Удалить один уровень структуры вложенного Option.

См. также:

• flatMap proc

Пример:

assert flatten(some(some(42))) == some(42)
assert flatten(none(Option[int])) == none(int)

Исходный код Редактировать

proc get[T](self: Option[T]): lent T {.inline.}

Возвращает содержимое Option. Если оно не содержит значения, генерируется исключение UnpackDefect.

См. также:

• get proc со значением по умолчанию

Пример:

assert some(42).get == 42
doAssertRaises(UnpackDefect):
  echo none(string).get

Исходный код Редактировать

proc get[T](self: Option[T]; otherwise: T): T {.inline.}

Возвращает содержимое Option или otherwise, если Option не содержит значения.

Пример:

assert some(42).get(9999) == 42
assert none(int).get(9999) == 9999

Исходный код Редактировать

proc get[T](self: var Option[T]): var T {.inline.}

Возвращает содержимое var Option в изменяемой форме. Если оно не содержит значения, генерируется исключение UnpackDefect.

Пример:

var
  a = some(42)
  b = none(string)
inc(a.get)
assert a.get == 43
doAssertRaises(UnpackDefect):
  echo b.get

Исходный код Редактировать

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

Проверяет, пуста ли Option.

См. также:

• isSome proc
• none proc

Пример:

assert not some(42).isNone
assert none(string).isNone

Исходный код Редактировать

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

Проверяет, содержит ли Option значение.

См. также:

• isNone proc
• some proc

Пример:

assert some(42).isSome
assert not none(string).isSome

Исходный код Редактировать

proc map[T, R](self: Option[T]; callback: proc (input: T): R): Option[R] {.
    inline, effectsOf: callback.}

Применяет функцию callback к значению Option и возвращает Option с новым значением.

Если Option не имеет значения, возвращается none(R).

См. также:

• map proc
• flatMap proc для варианта с обратной функцией, возвращающей Option

Пример:

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

assert some(42).map(isEven) == some(true)
assert none(int).map(isEven) == none(bool)

Исходный код Редактировать

proc map[T](self: Option[T]; callback: proc (input: T)) {.inline,
    effectsOf: callback.}

Применяет функцию callback к значению Option, если оно есть.

См. также:

• map proc для варианта с обратной функцией, возвращающей значение

Пример:

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

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

Исходный код Редактировать

proc none(T: typedesc): Option[T] {.inline.}

Возвращает Option для данного типа, не содержащего значения.

См. также:

• option proc
• some proc
• isNone proc

Пример:

assert none(int).isNone

Исходный код Редактировать

proc none[T](): Option[T] {.inline.}

Псевдоним для none(T). Исходный код Редактировать

proc option[T](val: sink T): Option[T] {.inline.}

Может использоваться для преобразования типа указателя (ptr, pointer, ref или proc) в тип опции. Преобразует nil в none(T). Если T не является типом указателя, это эквивалентно some(val).

См. также:

• some proc
• none proc

Пример:

type
  Foo = ref object
    a: int
    b: string

assert option[Foo](nil).isNone
assert option(42).isSome

Исходный код Редактировать

proc some[T](val: sink T): Option[T] {.inline.}

Возвращает Option со значением val.

См. также:

• option proc
• none proc
• isSome proc

Пример:

let a = some("abc")

assert a.isSome
assert a.get == "abc"

Исходный код Редактировать

proc unsafeGet[T](self: Option[T]): lent T {.inline.}

Возвращает значение some. Поведение не определено для none.

Примечание: Используйте только в том случае, если вы абсолютно уверены, что значение присутствует (например, после проверки с помощью isSome). В целом, предпочтительно использовать get proc.

Исходный код Редактировать