# map-column-values

## Description

<mark style="color:purple;">`map-column-values`</mark> *adaptor adds a new column to a datatable by mapping values of an existing column.*

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The columns and rows.

**`original column`**\
Type: `text`\
Required: Yes\
The name of an existing column containing values to be mapped.

**`values`**\
Type: `dictionary`\
Required: Yes\
The map of existing and new values, where the keys are the existing values in the original column, and the values are the corresponding values to be written to the new column.

**`new column`**\
Type: `text`\
Required: No\
The name of the new column to which the mapped values will be written. If unspecified, mapped values will be written to the original column.

**`case sensitive`**\
Type: `boolean`\
Required: No\
Whether lowercase and uppercase letters should be treated as equivalent. If unspecified, defaults to `False` (lowercase and uppercase letters are treated as equivalent).

**`unmapped values`**\
Type: `text`\
Required: No\
Specifies what values to write in the new column when the original column values are not included as map keys. If unspecified, defaults to `Replace original value with blank`.

## Outputs

**`data`**\
Type: `datatable`\
A datatable containing mapped values in `new column`.

## Examples

### Example 1: Default behaviour.

Inputs:

`data`:

| id | code | name           |
| -- | ---- | -------------- |
| 1  | GB   | United Kingdom |
| 2  | TR   | Turkey         |
| 3  | US   | United States  |
| 4  | IN   | India          |

`original column`: code

`values:`

<table><thead><tr><th>Key</th><th>Value</th><th data-hidden></th></tr></thead><tbody><tr><td>GB</td><td>gb</td><td></td></tr><tr><td>TR</td><td>tr</td><td></td></tr><tr><td>US</td><td>us</td><td></td></tr><tr><td>IN</td><td>in</td><td></td></tr></tbody></table>

`new column:`*null (empty)*\
\
`case sensitive:`*null (empty)*\
\
`unmapped values:` *null (empty)*

#### Outputs:

`data`:

<table><thead><tr><th width="259">id</th><th>code</th><th>name</th></tr></thead><tbody><tr><td>1</td><td>gb</td><td>United Kingdom</td></tr><tr><td>2</td><td>tr</td><td>Turkey</td></tr><tr><td>3</td><td>us</td><td>United States</td></tr><tr><td>4</td><td>in</td><td>India</td></tr></tbody></table>

-> Mapped values in the `code` column, replacing existing values.

### Example 2: Specify new column and unmapped values.

Inputs:

`data`:

| id | code | name           |
| -- | ---- | -------------- |
| 1  | GB   | United Kingdom |
| 2  | TR   | Turkey         |
| 3  | US   | United States  |
| 4  | IN   | India          |

`original column`: code

`values:`

<table><thead><tr><th>Key</th><th>Value</th><th data-hidden></th></tr></thead><tbody><tr><td>GB</td><td>gb</td><td></td></tr><tr><td>TR</td><td>tr</td><td></td></tr><tr><td>US</td><td>us</td><td></td></tr></tbody></table>

`new column:` country code\
\
`case sensitive:`*null (empty)*\
\
`unmapped values:` none

#### Outputs:

`data`:

<table><thead><tr><th width="179">id</th><th>code</th><th>name</th><th>country code</th></tr></thead><tbody><tr><td>1</td><td>GB</td><td>United Kingdom</td><td>gb</td></tr><tr><td>2</td><td>TR</td><td>Turkey</td><td>tr</td></tr><tr><td>3</td><td>US</td><td>United States</td><td>us</td></tr><tr><td>4</td><td>IN</td><td>India</td><td>none</td></tr></tbody></table>

-> Mapped values in the `code` column, creating a new column named `country code`. Unmapped value was set to `none.`