Class Subspace :: sus :: choice_type :: Choice

class Choice final

{ ... };

A tagged union, or sum type.

A Choice is always set to one of its Tags values, and each tag has zero or more types attached to it as data values.

Choice can be thought of as a combination of an enum and a std::variant, and typically the Tags are specified to be values in an enum.

A Choice always has an active member, as the tag must be specified at construction, and the asociated values for the tag are always set as they must be set when the tag is specified. This means a Choice is always in a fully specified state, or it is moved-from. Once it is moved from it may not be used except to be re-initialized.

Use the sus_choice_types() macro to specify the types in a Choice type.

To access the values in Choice, the current tag must be specified as a template parameter, and it will be checked for correctness. When it does not match, the Choice method will panic.

as<Tag>() gives const access to all the values attached to the tag.
as_mut<Tag>() gives mutable access to all the values attached to the tag. It is only callable on mutable Choice.
into_inner<Tag>() moves all values attached to the tag out of the Choice and marks the Choice as moved-from. It is only callable on an rvalue Choice.
get<Tag>() returns a const reference to the values attached to the tag if its currently active, and returns None if the tag is not active.
get_mut<Tag>() returns a mutable reference to the values attached to the tag if its currently active, and returns None if the tag is not active.

Examples

This Choice holds either a u64 with the First tag or a u32 with the Second tag.

enum class Order { First, Second };
using EitherOr = Choice<sus_choice_types(
    (Order::First, u64),
    (Order::Second, u32)
)>;

A Choice tag may be associated with no values by making its type void or may be associated with more than one type in which case all access will be done with a Tuple.

enum class Order { First, Second };
using EitherOr = Choice<sus_choice_types(
    (Order::First, void),
    (Order::Second, std::string, i32)
)>;
auto e1 = EitherOr::with<Order::First>();
auto e2 = EitherOr::with<Order::Second>("text", 123);

The Choice type can be used in a switch, with each case being one of its possible tag values. Within each tag case block, the values can be pulled out of the Choice with as in a type-safe and memory-safe way.

enum class Order { First, Second };
using EitherOr = Choice<sus_choice_types(
    (Order::First, u64),
    (Order::Second, std::string, i32)
)>;
auto e = EitherOr::with<Order::Second>("hello worl", 0xd);
switch (e) {
  case Order::First: {
    const auto& i = e.as<Order::First>();
    // We don't get here.
    fmt::println("First has u64 {}", i);
    break;
  }
  case Order::Second: {
    const auto& [s, i] = e.as<Order::Second>();
    // Prints "Second has hello world".
    fmt::println("Second has {}{:x}", s, i);
    break;
  }
}

Choice will re-export the tag value type as a nested Tag subtype. This allows access to the Choice's values though MyChoiceType::Tag::Name.

enum class Order { First, Second };
using EitherOr = Choice<sus_choice_types(
    (Order::First, u64),
    (Order::Second, u32)
)>;
auto x = EitherOr::with<EitherOr::Tag::First>(987u);