>> That would be the best way to do it, if the normal case is that you want
>> the costly algorithm.  But my understanding so far is that, in the
>> overwhelming majority of cases, you do not want this.
> I don't think this assumption is true.  The slow and costly algorithm
> keeps the markers and other properties, whereas bypassing it will not
> do so.  So the trade-off is not clear and depends on the context.

My guts agree with Stefan, but I think none of us have hard data to
confirm our intuition.

This said, I did a quick:

    grep -C1 delete-region **/*.el  |
        sed 's/-\([0-9]\+\)-/:\1:/' |
        grep insert

and this gives a crapload of matches.  A completely unscientific random
sampling suggests that the majority of them could make use of
`replace-region`, but that only a smaller proportion of them are likely
to benefit from the fancy diff of `replace-region-contents`.

See the (untested) patch below resulting from my random sampling (can
you spot which ones use the fancy diff algo and which ones don't).

To me the strongest argument in favor of having 2 separate functions is
that the semantics is sufficiently different that callers need to know
which is which (mostly because of the difference in algorithmic
complexity but also because of where point is (guaranteed or not) after
the call).

[ I noticed also that some of them could benefit from an `and-extract`
  option (i.e. return the old text), e.g. in `transpose-subr-1`.
  It would be easy/cheap to add such an option to `replace-region`, but not
  to `replace-region-contents`.  ]

>> Personally, I would feel reluctant to use this function.  For example, I
>> don't know how to specify a meaningful value for MAX-COSTS.  It is
>> documented as specifying "the quality of the difference computation",
>> which does not help much.  I think our users will feel this even more.
>> 
>> No other buffer editing primitives have anything resembling the MAX-SECS
>> and MAX-COSTS arguments.  I find the design choice to expose those
>> arguments a bit unusual in a specialized function, and inappropriate in
>> a function intended for general use.
>
> The original version of replace-buffer-contents didn't have any such
> arguments.  You called the function and had to wait for however long it
> took to do its job.  We added these arguments to give Lisp programs
> more control, depending on the context and the importance of keeping
> the text which doesn't need to be changed.  Now we are discussing how
> to give Lisp programs even more control.

[ Note: This sub-discussion is only very remotely related to
  `replace-region`.  ]
FWIW, I find the MAX-COSTS very problematic, because nobody knows what
it does.  The only thing we know about it is that it's an integer and it
defaults to 10k.  Based on the name we can assume that a larger value
pushes the limit further, so a smaller value may shorten the time to
complete (while reducing the quality of the output), but we have no idea
about the proportion.  To make it usable, the programmer would need to
know things like:

- How does it relate to the size of the replaced text?
  E.g. If the replacement is "zoomed" by a factor 4 (i.e. e.g. just
  replace each char in both the old and the new text with 4 repetitions
  of that char), does the same MAX-COSTS lead to finding the same diff
  in both cases (modulo the zoom factor)?
- If I reduce MAX-COSTS by half, is the max runtime reduced by half?
  Much less than half?  Much more than half?  Something else altogether?

>> That said, I understand that they are occasionally useful, or they
>> wouldn't exist.  I would make them internal to the function, with
>> sensible defaults that users could override with some variable when they
>> need to.  That change could be done in a backwards-compatible way with
>> advertised-calling-convention', and I would suggest we do that.
> I'm not sure I see how this would be better than what we have now.

I'd tend to agree: Dynbound implicit args aren't great, so I think the
current setup is not bad choice in this regard.  The MAX-SECS arg tends
to depend on the specific call, AFAICT, so I'm not sure there'd be much
benefit to a global, overridable, default.  As for MAX-COSTS, I don't
think we can guess what setup is best without being able to answer the
questions above.


        Stefan