[#BloombergLP-bdlpcre-RegEx-replace-0b]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlpcre.adoc[bdlpcre]::xref:BloombergLP/bdlpcre/RegEx.adoc[RegEx]::replace
:relfileprefix: ../../../
:mrdocs:

Replace matches of `pattern()` in `subject` with `replacement`&period;

== Synopsis

Declared in `&lt;bdlpcre&lowbar;regex&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
int
replace(
    xref:bsl/string.adoc[bsl::string]* result,
    int* errorOffset,
    std::string&lowbar;view const& subject,
    std::string&lowbar;view const& replacement,
    size&lowbar;t options = 0) const;
----

== Description

Optionally specify a bit mask of `options` flags that configure the behavior of the replacement&period; `options` should contain a bit&hyphen;wise OR of the `k&lowbar;REPLACE&lowbar;&ast;` constants defined by this class&period; If `options` has `k&lowbar;REPLACE&lowbar;GLOBAL` then every matching substring is replaced&semi; otherwise only the first match is replaced&period; UTF&hyphen;8 validity checking is performed on `subject` and `replacement` if `pattern()` was prepared with `k&lowbar;FLAG&lowbar;UTF8`&period; Return the number of substitutions on success, and load `result` with the replacement text&period; On error, return a negative value&period; If that error is a syntax error in `replacement`, load `errorOffset` (if non&hyphen;null) with the offset in `replacement` where the error was detected&semi; for other errors load `errorOffset` with a negative value&period; The behavior is undefined unless `true &equals;&equals; isPrepared()`&period; Note that if `result` is too small this method may resize it&semi; prefer a buffer large enough for the result including a terminating null&period;

== Return Value

number of substitutions, or a negative value on error

== Parameters

[cols="1,4"]
|===
| Name| Description
| *result*
| location for the replacement text
| *errorOffset*
| optional location for a syntax&hyphen;error offset
| *subject*
| input subject string
| *replacement*
| replacement text
| *options*
| bit&hyphen;wise OR of `k&lowbar;REPLACE&lowbar;&ast;` flags
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#
