Name

map — Extract a value from a list.

Syntax

map(key, keylist, valuelist)
map(key, keylist, valuelist, default)
              

The MAP function has the following argument:

key

The key to use to lookup the value to be returned.

keylist

The list of keys that are options to be looked up.

valuelist

The list of values, one matching each key, that are options that can be returned.

default

(Optional) A default value that will be provided if the key does not match an item in the keylist.

Description

This function extracts a value from a list by searching a list of keys to find a matching entry, and then returning a value from a corresponding position in the value list.

The keylist and valuelist arguments may be specified as either be a list data type or as a string that will be split at commas in to a list of string values.

The key lookup is done to find an exact matching value. For this reason the key value must have a data type that is identical to the values in the keylist. So if the keylist contains int values, then the key value must also be an int.

If the keylist is a string, then then the value of the key argument will automatically be converted to a string.

The number of values in the keylist must be the same as the number of values in the valuelist.

If the key does not match a value in the keylist then the function will return the default value if one has been provided. If a default value has not been provided then the an error wil occur.

Examples

Formula

Description

Result

map('a','a,b,c,d','1,2,3,4')

Split the keylist and valuelist arguments into lists of strings, return the value item in the position corresponding to the keyvalue 'a'.

'1'

map('a',list('a','b','c'),list(1,2,3))

Return the value item in the position corresponding to the keyvalue 'a'.

1

map('e','a,b,c,d','1,2,3,4')

An error will occur since the key is not found in the keylist

error!

map('e','a,b,c,d',list(1,2,3,4),-1)

Return the default value since the key is not found in the keylist

-1