Re: 9.4. String Functions and Operators page does not document thatencode adds line breaks

Поиск
Список
Период
Сортировка
От David G. Johnston
Тема Re: 9.4. String Functions and Operators page does not document thatencode adds line breaks
Дата
Msg-id CAKFQuwZg+_ewLpnjKDXRqJJWaGJ1Hf8k1Mxx9k4EBRXOjw2p4g@mail.gmail.com
обсуждение исходный текст
Ответ на 9.4. String Functions and Operators page does not document that encode adds line breaks  (PG Doc comments form <noreply@postgresql.org>)
Список pgsql-docs
Дерево обсуждения
On Sat, Feb 8, 2020 at 12:10 PM PG Doc comments form <noreply@postgresql.org> wrote:
The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/functions-string.html
Description:

It took me a long time to discover why a base 64 encoded SHA-512 hash was 89
characters long instead of the expected 88. The documentation does not
mention that the encode function inserts newlines after 76 characters.
Please make a note of this behavior.

Patch submissions are welcomed.  Though there is an argument for this being an implementation detail one shouldn't rely upon and therefore should not be described in user-facing documentation.
 
By the way, this is a very poor design decision.

It seems to be something we inherited some 20 years ago and are not likely to change even though I suspect you will find general agreement with your position.  Though since its isn't documented maybe changing it would be ok.

The workaround of trimming whitespace characters from the encoded string is ugly
and unacceptable.

It may be a bit ugly but when dealing with base64, specifically when decoding, whitespace of this nature is expressly allowed.  Its historical presence here, based upon MIME requirements prevalent at the time the code was written, doesn't alter its meaning and so it somewhat rightfully considered an implementation detail that is not necessary to document.

David J.

В списке pgsql-docs по дате отправления:

Предыдущее
От: PG Doc comments form
Дата:
Сообщение: 9.4. String Functions and Operators page does not document that encode adds line breaks
Следующее
От: "David G. Johnston"
Дата:
Сообщение: Re: Lack of detailed documentation