Appearance

CHOOSE function ​

Overview ​

CHOOSE is a function of the Logical category that returns a value from a list of values based on a specified index number. It is useful when you want to select one option from multiple possible values without writing complex nested conditional logic.

Common use cases include:

  • Mapping numeric codes to text labels
  • Selecting different calculation results based on a position or index

Usage ​

Syntax ​

CHOOSE(index_num, value1, [value2], …) => result

Argument descriptions ​

  • index_num (number, required). The position of the value to return. The first value has index 1, the second value has index 2, and so on. If index_num is a fraction, it is truncated to the lowest integer before being used.

  • value1 (any, required). The value to return when index_num is 1.

  • valueN (any, optional). Additional values to choose from. You can supply multiple values, each corresponding to a sequential index.

Additional guidance ​

  • Values can be of any type, including numbers, text or booleans.
  • CHOOSE evaluates only the selected value, which can make it more efficient than deeply nested IF expressions.
  • If your logic depends on conditions rather than fixed positions, consider using logical functions such as IF or IFS instead.
  • CHOOSE evaluates its arguments lazily, meaning only the value corresponding to the selected index_num is evaluated.

Returned value ​

CHOOSE returns a value of the same type as the selected argument. The returned value corresponds to the position specified by the index_num argument.

Error conditions ​

  • In common with many other IronCalc functions, CHOOSE propagates errors that are found in any of its arguments.
  • If too few or too many arguments are supplied, CHOOSE returns the #ERROR! error.
  • If the value of index_num is not (or cannot be converted to) a number, CHOOSE returns the #VALUE! error.
  • If index_num is less than 1 or greater than the number of supplied values, CHOOSE returns the #VALUE! error.
  • For more information about the different types of errors that you may encounter when using IronCalc functions, visit our Error Types page.

Details ​

  • Conceptually, CHOOSE works like positional indexing into a list:

    • If index_num = 1, the result is value1
    • If index_num = 2, the result is value2
    • …
    • If index_num = n, the result is valueN

  • Unlike lookup functions that search for matching keys, CHOOSE relies entirely on the numeric position provided by index_num.

  • CHOOSE uses lazy evaluation: only the selected value is evaluated, and all other values are ignored. This allows CHOOSE to safely reference expressions that might otherwise produce errors (such as division by zero) as long as they are not selected.

Examples ​