RegEx.Replace
-------------

Replace pattern once.

| Component | Version | macOS | Windows | Linux | Server | iOS SDK |
|---|---|---|---|---|---|---|
| [RegEx](component_RegEx.md) | [7.5](newinversion75.md) | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |

MBS( "RegEx.Replace"; Text; Pattern; Rewrite { ; Options; All; NthOffset } ) 

**MBS**( **"RegEx.Replace";** /\* Replace pattern once. \*/  
**$Text**; /\* The text to use.e.g. "hello world" \*/   
**$Pattern**; /\* The pattern to use.e.g. "l+" \*/   
**$Rewrite**; /\* The output pattern.e.g. "\\1\\1" \*/   
**$Options**; /\* Optional; The PCRE options.  
Can be given as text or number.e.g. 0 \*/   
**$All**; /\* Optional; Whether to replace all occurances.  
Pass 1 to replace all or 0 to replace once.  
Default 0.e.g. 0 \*/   
**$NthOffset**) /\* Optional; Number of occurrences to skip over on the start before doing replace.  
e.g. pass 1 to skip first match and start replacing at second one.e.g. 0 \*/ 

### Parameters

| Parameter | Description | Example | Flags |
|---|---|---|---|
| Text | The text to use. | "hello world" |  |
| Pattern | The pattern to use. | "l+" |  |
| Rewrite | The output pattern. | "\\1\\1" |  |
| Options | The PCRE options.   Can be given as text or number. | 0 | Optional |
| All | Whether to replace all occurances.   Pass 1 to replace all or 0 to replace once.   Default 0. | 0 | Optional |
| NthOffset | Number of occurrences to skip over on the start before doing replace.   e.g. pass 1 to skip first match and start replacing at second one. | 0 | Optional      Added in version **13.5**. |

### Result

Returns new text or error.

### Description

Replace pattern once.  
You can replace the first match of pattern in text with rewrite pattern. Within rewrite pattern, backslash-escaped digits (\\1 to \\9) can be used to insert text matching corresponding parenthesized group from the pattern. \\0 in rewrite refers to the entire matching text.  
  
| Option | Number | Description |
|---|---|---|
| Caseless | 1 | Do caseless matching |
| CaseSensitive | 0 | Do case sensitive matching |
| Multiline | 2 | ^ and $ match newlines within data |
| SingleLine | 0 | ^ and $ do not match newlines within data |
| DotAll | 4 | . matches anything including NL |
| Extended | 8 | Ignore white space and # comments |
| Anchored | 16 | Force pattern anchoring |
| DollarEndOnly | 32 | $ not to match newline at end |
| NotBOL | 128 | Subject string is not the beginning of a line |
| NotEOL | 256 | Subject string is not the end of a line |
| Ungreedy | 512 | Invert greediness of quantifiers |
| Greedy | 0 | Be greedy. |
| NotEmpty | 1024 | An empty string is not a valid match |
| Empty | 0 | An empty string is a valid match |
| AutoCapture | 0 | Enable numbered capturing parentheses |
| NoAutoCapture | 4096 | Disable numbered capturing parentheses (named ones available) |
| AutoCallout | 16384 | Compile automatic callouts |
| NoAutoCallout | 0 | Don’t compile automatic callouts |
| Partial | 32768 | Allow partial results. |
| FirstLine | 262144 | Force matching to be before newline |
| DupNames | 524288 | Allow duplicate names for subpatterns |
| NewlineCR | 1048576 | Set CR as the newline sequence |
| NewlineLF | 2097152 | Set LF as the newline sequence |
| NewlineCRLF | 3145728 | Set CRLF as the newline sequence |
| NewlineAny | 4194304 | Recognize any Unicode newline sequence |
| NewlineAnyCRLF | 5242880 | Recognize CR, LF, and CRLF as newline sequences |
| BSRAnyCRLF | 8388608 | \\R matches only CR, LF, or CRLF |
| BSRUnicode | 16777216 | \\R matches all Unicode line endings |
| JavaScriptCompatible | 33554432 | JavaScript compatibility |
| NoStartOptimize | 67108864 | Disable match-time start optimizations |
| PartialHard | 134217728 | Return partial result if found before . |
| NotEmptyAtStart | 268435456 | An empty string at the start of the subject is not a valid match |
| UCP | 536870912 | Use Unicode properties for \\d, \\w, etc. |

### Examples

Replace:

 MBS ( "RegEx.Replace"; "yabba dabba doo"; "b+"; "d" )  
<small>  
Example result: "yadba dabba doo"</small>Replace with multiline:

 MBS ( "RegEx.Replace"; "Hello¶World¶Testing"; "^World$"; "Welt"; "Multiline, NewlineAnyCRLF" )  
<small>  
Example result:   
Hello  
Welt  
Testing</small>Try replaceing nth occurance:

 MBS ( "RegEx.Replace"; "John John John John"; "john"; "Thom"; "caseless"; 0; 0 ) &amp; ¶ &amp;   
MBS ( "RegEx.Replace"; "John John John John"; "john"; "Thom"; "caseless"; 0; 1 ) &amp; ¶ &amp;   
MBS ( "RegEx.Replace"; "John John John John"; "john"; "Thom"; "caseless"; 0; 2 ) &amp; ¶ &amp;   
MBS ( "RegEx.Replace"; "John John John John"; "john"; "Thom"; "caseless"; 0; 3 )  
<small>  
Example result:   
Thom John John John  
John Thom John John  
John John Thom John  
John John John Thom</small>### See also

- [RegEx.Extract](RegExExtract.md)
- [RegEx.Release](RegExRelease.md)
- [RegEx.ReplaceAll](RegExReplaceAll.md)

### Release notes

- **Version 7.5**
    - Added [RegEx.Replace](http://www.mbsplugins.eu/RegExReplace.shtml), [RegEx.ReplaceAll](http://www.mbsplugins.eu/RegExReplaceAll.shtml) and [RegEx.Quote](http://www.mbsplugins.eu/RegExQuote.shtml) functions.

### Blog Entries

- [MBS Plugin Advent calendar: 19 - RegEx](https://www.mbsplugins.de/archive/2023-12-19/MBS_Plugin_Advent_calendar_19_/monkeybreadsoftware_blog_filemaker)
- [Regular Expressions in FileMaker](https://www.mbsplugins.de/archive/2023-03-19/Regular_Expressions_in_FileMak/monkeybreadsoftware_blog_filemaker)
- [MBS Plugin Quiz](https://www.mbsplugins.de/archive/2021-04-30/MBS_Plugin_Quiz/monkeybreadsoftware_blog_filemaker)
- [Comparing Base Elements Plugin to MBS FileMaker Plugin](https://www.mbsplugins.de/archive/2017-10-24/Comparing_Base_Elements_Plugin/monkeybreadsoftware_blog_filemaker)
- [MBS FileMaker Plugin, version 7.5pr3](https://www.mbsplugins.de/archive/2017-10-23/MBS_FileMaker_Plugin_version_7/monkeybreadsoftware_blog_filemaker)

This function checks for a license.

Created 17th October 2017 , last changed 31st October 2023

  
[RegEx.ReleaseAll](RegExReleaseAll.md) - [RegEx.ReplaceAll](RegExReplaceAll.md)

[HTML Version](RegExReplace.shtml)