[#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`.

== Synopsis

Declared in `<bdlpcre_regex.h>`

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

== Description

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


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