# textMap

### textMap(source, mapNo)

Using map number "mapNo", find all occurrences of each "lookFor" pattern and replace it with the corresponding "replaceWith" pattern.

### textMap(source, mapNo, replaceNo)

Using map number "mapNo", find "replaceNo" occurrences of each "lookFor" pattern and replace it with the corresponding "replaceWith" pattern.

### textMap(source, mapNo, replaceNo, stopOnFirst)

Using map number "mapNo", find "replaceNo" occurrences of the first "lookFor" pattern and replace it with the corresponding "replaceWith" pattern. This version of the function stops after the first match is found - it does not proceed to test all the other patterns in the map.

## Arguments

Argument | Data Type | Description
source | string | String to search
mapNo | integer | Which text map to use - 1, 2 or 3
replaceNo | integer | Number specifying how many matches to replace, staring from 1
stopOnFirst | true/false | If present and TRUE, indicates that textMap should stop searching the text map after the first successful match

## Returns

The source string with one or more "lookFor" matches from the text map specified replaced with the "replaceWith" pattern.

## Description

textMap() is similar to replace(), in that it is used to scan the source string for matches and then replace the matches with new text. textMap(), however, uses the text map tables set up in 'Tools - Options - Text Maps' as the source of the "lookFor" and "replaceWith" patterns. The "mapNo" argument specifies which map to use.

textMap() scans through the map; for each line of the map, it:

1. reads the "lookFor" pattern

2. uses the "lookFor" pattern to scan for matches in the source

3. replaces each of the matches with the "replaceWith" pattern from the same line in the map.

For detailed information on how to use the "lookFor" and "replaceWith" patterns, see the documentation on the replace() function.

Using textMap() is equivalent to using a number of replace() function calls. However, textMap() has some advantages:

- when setting up the text map table, you are only typing the "lookFor" and "replaceWith" strings, so the typing is a bit easier

- if you wanted to use the same set of replacements on more than one field, you would have to type all the replace() functions for each field; with textMap(), you type a single textMap() function for each field

- if you have different import set-ups, you have to enter the set of replace() functions in each set-up, including re-entering each of the "lookFor" and "replaceWith" patterns. These can get quite complex, so there is real possibility of error with re-typing.

A typical use of textMap() is where your source data contains a variety of routine errors that need to be fixed. Examples might include:

1. ensuring that a company name is correct, despite a variety of misspellings

2. phone number area code changes

3. ensuring that states or counties all have the same abbreviation (CA instead of Calif., California, Cal., Ca, ...)

Normally textMap() will look at every row of the requested text map table, and apply all the changes found. For some types of input you may know that only one match is going to be found - an example might be phone number area code changes. If the field only contains one phone number, then once we have matched it, there is no point scanning the rest of the text map table. The "stopOnFirst" argument allows you to specify that textMap() stop after the first match.

NOTES:

1. Each match and replace is applied in sequence to the string. This means it is possible for a match/replace to change what was done in a preceeding match/replace.
2. "stopOnFirst" does not control how many replacements are made in the source after the first "lookFor" match is found. This is controlled by "replaceNo". "stopOnFirst" simply prevents textMap() from proceeding through the text map table to the next "lookFor" match.

## Examples

Assume that:

1. Field F1 has the string "The quick brown fox"

2. Map 1 has the mappings:
   quick -> slow
   fox -> tortoise

3. Field F2 has the following values in successive rows:
   0181 123 0171
   (0181) 234-2345
   (0171) 543 4321
   0171 987 6543

4. Map 2 has the following mappings:
   "^\(?0181\)?" -> "0208"
   "^\(?0171\)?" -> "0207"
   NOTE: decoding this regular expression:
   the '^' says"at the start of the string" (see Anchors);
   the "\(" and "\)" says "we want a '(' or ') character, not a group" (see Groups)
   the '?' means "zero or one occurrence of the preceding character" (see Count operators)

   So the first lookFor pattern will look for an occurrence of 0181 or (0181) at the start of the string

Example | Returns | Description
texMap(1, #f1) | "The slow brown tortoise" |
textMap(1, #f1, 1) | "The slow brown tortoise" | Both replacements are done because there is only one replacement per row of the text map.
textMap(1, #f1, 1, 1) | "The slow brown fox" | Now only one replacement is done, because we stop after the first row that has a match
textMap(2, #f2) | 0208 123 0171 0208 234-2345 0207 543 4321 0207 987 6543 | Note that all the brackets have been removed, and the 0171 at the end of the first phone number has not been replaced, because we anchored the matches to the start of the string

## See Also

replace(), find(), snip(), contains(), Introduction to Regular Expressions