---
type: "fhirpath-function"
title: "FHIRPath Function: replaceMatches"
function: "replaceMatches"
category: "String Manipulation"
section: "5.6.12"
source: "fhirpath/functions.json"
---
# FHIRPath Function: replaceMatches
Matches the input using the regular expression in `regex` and replaces each match with the `substitution` string. The substitution may refer to identified match groups in the regular expression, as illustrated by the example below that uses named capture groups for `month`, `day`, and `year` to perform a conversion from one date format to another.

If the input collection, `regex`, or `substitution` are empty, the result is empty (`{ }`).

If the input collection contains multiple items, the evaluation of the expression will end and signal an error to the calling environment.

The optional `flags` parameter can be set to:
{:.stu}
* `i` to perform a case-insensitive search (otherwise is case-sensitive)
* `m` - Matches the start and end of each line using ^ and $ (multi-line)<br/>(not only begin/end of string)
{:.stu}

This example of `replaceMatches()` will convert a string with a date formatted as MM/dd/yy to dd-MM-yy:
``` fhirpath
'11/30/1972'.replaceMatches('\\b(?<month>\\d{1,2})/(?<day>\\d{1,2})/(?<year>\\d{2,4})\\b',
       '${day}-${month}-${year}')
```

This example locates all the instances of `aa` and surrounds them with double quotes:
``` fhirpath
'aaabaa'.replaceMatches('aa', '"aa"') // returns "aa"ab"aa"
```

> **Note:** Platforms will typically use native regular expression implementations. These are typically fairly similar, but there will always be small differences. As such, FHIRPath does not prescribe a particular dialect, but recommends the use of the [\[PCRE\]](#PCRE) flavor as the dialect most likely to be broadly supported and understood.
## Summary
- **Category**: String Manipulation
- **Section**: `5.6.12`
- **Return Type**: `String`
- **Empty Input Result**: `empty`
- **Errors on Multiple Input**: `true`
## Description
Matches the input using the regular expression in `regex` and replaces each match with the `substitution` string. Within a substitution string, \n refers to the nth match group in the regex. \0 refers to the entire match.
## Arguments
- `regex`: `String` - Regular expression to match against
- `substitution`: `String` - Substitution string, with \n referring to match groups
- `flags` (optional): `String` - Optional flags for the regex (i for case-insensitive, m for multi-line)
## Type Mapping
- `String-String`
## Example
```fhirpath
'10/15/2014'.replaceMatches('[0-9]+', 'X') // 'X/X/X'
'Mary had a little lamb'.replaceMatches('(\\w+) (\\w+)', '\\2, \\1') // 'had, Mary a lamb, little'
```