%% %CopyrightBegin%
%%
%% SPDX-License-Identifier: Apache-2.0
%%
%% Copyright Ericsson AB 2021-2025. All Rights Reserved.
%%
%% %CopyrightEnd%

[;1m  replace(Subject, RE, Replacement, Options)[0m

  Replaces the matched part of the [;;4mSubject[0m string with [;;4m[0m
  [;;4mReplacement[0m.

  The permissible options are the same as for [;;4mrun/3[0m, except that
  option[;;4m capture[0m is not allowed. Instead a [;;4m{return, ReturnType}[0m
  is present. The default return type is [;;4miodata[0m, constructed in a
  way to minimize copying. The [;;4miodata[0m result can be used directly
  in many I/O operations. If a flat [;;4mlist/0[0m is desired, specify [;;4m[0m
  [;;4m{return, list}[0m. If a binary is desired, specify [;;4m{return, binary}[0m.

  As in function [;;4mrun/3[0m, an [;;4mmp/0[0m compiled with option [;;4municode[0m
  requires [;;4mSubject[0m to be a Unicode [;;4mcharlist()[0m. If compilation is
  done implicitly and the [;;4municode[0m compilation option is specified
  to this function, both the regular expression and [;;4mSubject[0m are to
  specified as valid Unicode [;;4mcharlist()[0ms.

  If the replacement is given as a string, it can contain the
  special character [;;4m&[0m, which inserts the whole matching expression
  in the result, and the special sequence [;;4m`N (where N is an integer >[0m
  [;;4m0), [0m\g[;;4mN, or [0m\g{[;;4mN[0m}, resulting in the subexpression number N,
  is inserted in the result. If no subexpression with that number is
  generated by the regular expression, nothing is inserted.

  To insert an & or a \ in the result, precede it with a \. Notice
  that Erlang already gives a special meaning to \ in literal
  strings, so a single \ must be written as [;;4m"\\"[0m and therefore a
  double \ as [;;4m"\\\\"[0m.

  Example:

    1> re:replace("abcd","c","[&]",[{return,list}]).
    "ab[c]d"

  while

    2> re:replace("abcd","c","[\\&]",[{return,list}]).
    "ab[&]d"

  If the replacement is given as a fun, it will be called with the
  whole matching expression as the first argument and a list of
  subexpression matches in the order in which they appear in the
  regular expression. The returned value will be inserted in the
  result.

  Example:

    3> re:replace("abcd", ".(.)",
        fun(Whole, [<<C>>]) ->
             <<$#, Whole/binary, $-, (C - $a + $A), $#>>
        end,
        [{return, list}]).
    "#ab-B#cd"

  [;;4mNote[0m

    Non-matching optional subexpressions will not be included in
    the list of subexpression matches if they are the last
    subexpressions in the regular expression. Example: The
    regular expression [;;4m"(a)(b)?(c)?"[0m ("a", optionally followed
    by "b", optionally followed by "c") will create the following
    subexpression lists:

     • [;;4m[<<"a">>, <<"b">>, <<"c">>][0m when applied to the string [;;4m[0m
       [;;4m"abc"[0m

     • [;;4m[<<"a">>, <<>>, <<"c">>][0m when applied to the string [;;4m[0m
       [;;4m"acx"[0m

     • [;;4m[<<"a">>, <<"b">>][0m when applied to the string [;;4m"abx"[0m

     • [;;4m[<<"a">>][0m when applied to the string [;;4m"axx"[0m

  As with [;;4mrun/3[0m, compilation errors raise the [;;4mbadarg[0m exception. [;;4m[0m
  [;;4mcompile/2[0m can be used to get more information about the error.
