bug#45178: buffer-hash docstring should explain difference to secure-hash

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Stefan Kangas]

Severity: minor

It is not clear to me when I would want to use:

    (buffer-hash (current-buffer))

instead of

    (secure-hash 'sha1 (current-buffer))

One obvious difference is that secure-hash respects narrowing, while
buffer-hash doesn't.  But it's not clear to me why I can't just use
save-restrictions+widen instead.  The Elisp manual says: "It should be
somewhat more efficient on larger buffers than ‘secure-hash’ is, and
should not allocate more memory."

First, I think we should add something about this to the docstring of
`buffer-hash'.  Perhaps we should also mention it in the `secure-hash'
docstring.

Second, is the difference all that important?  If so, perhaps we should
look over our uses of `md5', `sha1' and `secure-hash' in our code-base
to ensure we use the more efficient version where applicable.  (For
example in savehist.el and desktop.el.)

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Severity: minor
>
> It is not clear to me when I would want to use:
>
>     (buffer-hash (current-buffer))
>
> instead of
>
>     (secure-hash 'sha1 (current-buffer))
>
> One obvious difference is that secure-hash respects narrowing, while
> buffer-hash doesn't.

I thought the buffer-hash doc string made the use case pretty clear:

----
This function is useful for comparing two buffers running in the same
Emacs, but is not guaranteed to return the same hash between different
Emacs versions.
----

The only use case for the function is to compare two buffers in the same
running Emacs image.  It shouldn't be used for anything else.

> First, I think we should add something about this to the docstring of
> `buffer-hash'.  Perhaps we should also mention it in the `secure-hash'
> docstring.

I think that would be pointing people in the wrong direction.
`secure-hash' is the right thing to use in 99% of the cases.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> The only use case for the function is to compare two buffers in the same
> running Emacs image.  It shouldn't be used for anything else.

I guess what I don't understand is why I would _ever_ want to use this
function.  I mean, why not just compare buffers using `secure-hash'?

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> I guess what I don't understand is why I would _ever_ want to use this
> function.  I mean, why not just compare buffers using `secure-hash'?

`buffer-hash' is fast, so you can use it to compare the buffer contents
before and after doing things like `indent-sexp' to see whether that
changed anything.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Stefan Kangas]

close 45178 28.1
thanks

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> I guess what I don't understand is why I would _ever_ want to use this
>> function.  I mean, why not just compare buffers using `secure-hash'?
>
> `buffer-hash' is fast, so you can use it to compare the buffer contents
> before and after doing things like `indent-sexp' to see whether that
> changed anything.

OK, I've benchmarked this and can confirm it is indeed much faster.  So
I updated its docstring on master by copying the explanation from the
manual.  I'm therefore closing this bug report.

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Basil L. Contovounesios]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
>> I guess what I don't understand is why I would _ever_ want to use this
>> function.  I mean, why not just compare buffers using `secure-hash'?
>
> `buffer-hash' is fast, so you can use it to compare the buffer contents
> before and after doing things like `indent-sexp' to see whether that
> changed anything.

[I get that this is just an example, but in this case wouldn't you use
 buffer-modified-tick or buffer-chars-modified-tick instead?]

-- 
Basil

bug#45178: buffer-hash docstring should explain difference to secure-hash

[Stefan Kangas]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> `buffer-hash' is fast, so you can use it to compare the buffer contents
>> before and after doing things like `indent-sexp' to see whether that
>> changed anything.
>
> [I get that this is just an example, but in this case wouldn't you use
>  buffer-modified-tick or buffer-chars-modified-tick instead?]

AFAIU, this is used to detect when a command changed a buffer but the
buffer still is the same before and after the changes.  In that case, we
don't want it to be marked as changed even if there were changes taking
place in the background.  For example, see `fill-paragraph'.