Function

choose( key, choice1, choiceN )

Evaluates the choice argument at the given index and returns the result.

See also:

• a!match(): Allows specifying a series of condition pairs using equal and then, or whenTrue and then. Can often achieve more complex logic than choose().
• wherecontains(): Returns an index given a list of values and a value to find within the list; often used in combination with choose() to determine the index.
• index(): Similar to choose(), index() returns an item at a certain index within a list. Usually used for static lists instead of expressions.

Parameters

Returns

Any Type

Usage considerations

Casting and returning boolean values

• The key parameter is always cast to an integer to identify the choice.
• If the value cannot be cast to an integer, the function returns an error.

Working with nulls

• If the selected choice evaluates to null, no error occurs and null will be returned.
• The key must be a number between 1 and the number of choices. It cannot be null.

Using lists

• The items to evaluate must be provided as separate arguments. If a list is provided as an argument, the entire list is returned as the result.
• The key parameter cannot be a list of values.

Evaluation order

• Unlike most functions, choose() does not evaluate all its arguments. First the key is evaluated, then the corresponding choice argument.
• Only one choice argument is evaluated. Use choose to avoid calling potentially costly expressions whose results would be discarded.

Other tips

When choosing values from a static list, the index() function is often easier to use. For example, both of the following examples will return the same output:

1
2
3
4
5
6
choose(
  2,
  "Low",
  "Medium",
  "High"
)

1
2
3
4
5
index(
  {"Low", "Medium", "High"},
  2,
  "Unknown"
)

However, the example using index() is far more common because the list of values can come from a single variable or constant rather than each value being provided in a separate argument. In addition, if an index value of 4 is provided in the examples above, choose() returns an evaluation error, while index() returns the default value Unknown.

Examples

Use expressions as the choice arguments

1
choose(2,2+2,4/2,3^2)

Returns 2.

Using choose to provide a random rating

It can be useful to use the wherecontains() function in conjunction with choose(). Since wherecontains() returns a list, use the first result for the key parameter.

1
2
3
4
5
6
7
8
9
a!localVariables(
  local!rating: "Excellent",
  choose(
    wherecontains(local!rating, {"Poor","Satisfactory","Excellent"})[1],
    mod(rand() * 10, 5),
    mod(rand() * 10, 5) + 4,
    10 - mod(rand() * 10, 2)
  )
)

Choose a component to display in an interface

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
a!localVariables(
  local!selectionField: 2,
  local!value: 2,
  choose(
    local!selectionField,
    a!radioButtonField(
      label: "Radio Button",
      choiceLabels: {"One", "Two", "Three"},
      choiceValues: {1, 2, 3},
      value: local!value,
      saveInto: local!value
    ),
    a!checkboxField(
      label: "Checkbox",
      choiceLabels: {"One", "Two", "Three"},
      choiceValues: {1, 2, 3},
      value: local!value,
      saveInto: local!value
    ),
    a!dropdownField(
      label: "Dropdown",
      choiceLabels: {"One", "Two", "Three"},
      choiceValues: {1, 2, 3},
      value: local!value,
      saveInto: local!value
    )
  )
)

In this example, the checkbox field is displayed since it is the second choice argument. In addition, the radio button and dropdown fields are not evaluated.

Feature compatibility