Documentation on choice types is lacking

[SimonCockx]

There is some confusion on the nature of choice types. We should clarify it in the Rune docs.

The intention for choice types is to be an implementation of tagged unions (also called discriminated unions, or sum types).

Note that this is different from a classical set union, since for each element in the set we remember the original set where it came from. In terms of set operations:

-- "Set" union between types A and B
A U B
-- (where U represents the union operator in set theory)

-- "Tagged" union between types A and B
({TAG_A} x A) U ({TAG_B} x B)
-- (where x represents the cartesian product in set theory)

Note that the tag allows you to discriminate between instances of different type, which is why most modern programming languages usually support tagged unions rather than actual unions, with one prime exception being Rust.

Note also that, because of this tag, whether the union is inclusive or exclusive is irrelevant - the sets on each side never overlap.

Similar implementations:

• TypeScript, where they are just called union types: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types

type StringOrNumber = string | number

function f(input: StringOrNumber) {
  if (typeof input === 'string') {
    // we know `input` is of type `string`. Note that the `typeof` operator acts as the tag here.
  } else {
    // we know `input` is of type `number`.
  }
}

• Haskell, which supports a generalized form of tagged unions called algebraic data types: https://www.schoolofhaskell.com/school/starting-with-haskell/introduction-to-haskell/2-algebraic-data-types

data StringOrNumber = String String | Number Decimal

f :: StringOrNumber -> IO ()
f (String stringValue) = -- we know the input is of type `String`. Note that the tag is explicitly defined here.
f (Number numberValue) = -- we know the input is of type `Decimal`

In that same fashion, we support choice types in Rune:

choice StringOrNumber:
  string
  number

func F:
  inputs:
    input StringOrNumber (1..1)
  output:
    result string (1..1)

  set result:
    input switch
      string then // we know `input` is of type `string`. Note that the tag of the union coincides with the name of the type.
      number then // we know `input` is of type `number`