Options and variants ​

Options ​

In SmartPy usage of the value None is reflected in the type. For example, an optional integer is of type sp.option[sp.int]. This type can be either None or sp.Some(n) for any value n of type sp.int.

x.is_none() → sp.bool

Checks whether the given value is None. For example None.is_none() == True and sp.Some(42).is_none() == False.

x.is_some() → sp.bool

Checks whether the given value is of the form sp.Some(...). For example None.is_some() == False and sp.Some(42).is_some() == True.

x.unwrap_some([error=exception: t]) → t

Extracts the argument of an option value if it is of the form sp.Some(...). Raises an exception (that can be specified as error) if x == None. If error is specified, the parameter must be named.

For example, sp.Some(42).unwrap_some() == 42, whereas None.unwrap_some(error="oops") raises the exception "oops".

Variants ​

Variants in SmartPy are enumerations of cases, where each case comes with an extra value. Variants are similar to features such as enums, sum types, and tagged/disjoint unions in other languages.

For example, sp.variant(Circle=sp.int, Rectangle=sp.pair[sp.int, sp.int]) is a variant type with two cases. Its values are sp.variant.Circle(r) (for any r of type sp.int) and sp.variant.Rectangle(h, w) (for any h and w of type sp.int).

x.is_variant.V() → sp.bool

Checks whether a value is of the given variant V, for example:

smartpy

c = sp.variant.Circle(2)
assert c.is_variant.Circle()

x.unwrap.V([error=exception: t]) → t

Obtains the argument of a given variant V. Raises an error if it is of a different variant. If error is specified, the parameter must be named. For example:

smartpy

c = sp.variant.Circle(2)
assert c.unwrap.Circle() == 2
r = c.unwrap.Rectangle()  # raises an exception
r = c.unwrap.Rectangle(error="Err")  # raises "Err"

Matching over options and variants ​

To match over variants, you can use with sp.match(my_variant) and then with sp.case.<case> or with sp.case.<case> as <value> or with None.

with sp.match(v: sp.variant[t])  → 

Matches over a variant.

This example creates a variant and uses match branch based on its contents:

smartpy

v = sp.variant.Circle(2)
with sp.match(v):
    with sp.case.Circle as radius:
        assert radius == 2
    with sp.case.Rectangle as dimensions:
        ...
        # Do something with `dimensions.h` and `dimensions.w`.

You can use with None to match the None case, as in this example:

smartpy

o = sp.Some(5)
with sp.match(o):
    with sp.case.Some as value:
        assert value == 5
    with None:
        ...