# MAP

### Description

`MAP` is used to perform the same action on each individual value in a list.

That way, it lets you transform a list of values into another list, which comes in especially handy when working with user-provided values like `nationalities` or `sources_of_income`.

For readability, we recommend using the [method version ](https://docs.atfinity.io/rule-language/operators/list-operators/map)whenever you can. 

### Example: Get total income

```
p is Person
SUM(
  MAP(
    p.sources_of_income, 
    get_attr(CONCAT("income_" , CURRENT))
  )
)
```

Here we use the functional version:

1. we assume a user selects the relevant sources of income out of `salary`, `capital_gain`, and `gifts`
2. the user then fills out the information with predictable keys, like `income_salary`, `income_capital_gain`, and `income_gifts`.
3. with `get_attr`, these values are accessed and added up. If a value has no entry from the user, its default will be 0.

The calculations step-by-step:

* the first argument of `MAP` is `self.sources_of_income`.
* let's say the user has filled out 10,000 under `income_salary`, 5000 under `income_capital_gain`, and nothing under `income_gifts`.
* the values of the first argument, which `MAP` will run over in succession, are salary, capital gain, and gifts.
* in the first iteration, the first argument of `MAP`, `self.sources_of_income`, gets the value `salary`.
* Next, `CURRENT` in the second argument takes that value `salary` from the first argument. `CONCAT` attaches it to the string "income\_".
* This means the first run of the `MAP` function looks like this: `MAP(self.salary, get_attr(income_salary)`
* Using the values the user has provided, the `MAP` function will store 10,000 as the first value of its output. `MAP` then starts its work over on the second value in the list capital gain.
* Once `MAP` has run over all values in the list, it’s intermediate output will be `[10000, 5000, 0]`
* Since `MAP` is wrapped in a `SUM` function, the final output yields 15000.