
  -spec replace(Subject, RE, Replacement, Options) ->
                   iodata() | unicode:charlist()
                   when
                       Subject :: iodata() | unicode:charlist(),
                       RE :: mp() | iodata() | unicode:charlist(),
                       Replacement :: iodata() | unicode:charlist(),
                       Options :: [Option],
                       Option ::
                           anchored | global | notbol | noteol |
                           notempty | notempty_atstart |
                           {offset, non_neg_integer()} |
                           {newline, NLSpec} |
                           bsr_anycrlf |
                           {match_limit, non_neg_integer()} |
                           {match_limit_recursion, non_neg_integer()} |
                           bsr_unicode |
                           {return, ReturnType} |
                           CompileOpt,
                       ReturnType :: iodata | list | binary,
                       CompileOpt :: compile_option(),
                       NLSpec :: cr | crlf | lf | anycrlf | any.

  Replaces the matched part of the Subject string with the
  contents of Replacement.

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

  As in function run/3, an mp() compiled with option unicode
  requires Subject to be a Unicode charlist(). If compilation is
  done implicitly and the unicode compilation option is specified
  to this function, both the regular expression and Subject are to
  specified as valid Unicode charlist()s.

  The replacement string can contain the special character &,
  which inserts the whole matching expression in the result, and the
  special sequence \N (where N is an integer > 0), \gN, or \g{
  N}, 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 "\\" and therefore a
  double \ as "\\\\".

  Example:

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

  gives

    "ab[c]d"

  while

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

  gives

    "ab[&]d"

  As with run/3, compilation errors raise the badarg exception. 
  compile/2 can be used to get more information about the error.
