Options and variants

Options

TIP

Options are a particular case of variants described below with two cases: None and Some.

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:

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:

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 the pattern-matching syntax (match <expr>) over SmartPy variants. The following example creates a variant and uses match branch based on its contents:

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

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

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

Note, in SmartPy, you can only pattern-match over options and variants.