9.4. String Functions and Operators page does not document that encode adds line breaks
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. By the way, this is a very poor design decision. The function has no knowledge of how the string is going to be used. If it is going to be displayed on an 80-character terminal, then the newline makes sense. If it is going to be written to a PEM-encoded file, then the newline is to be expected. But I'm inserting the result into a VARCHAR(88) column and comparing with base-64 encoded strings from Node.js. There is no reason for the results to be terminal or file friendly. Instead, they should be machine friendly. The decision to add newlines should have been made on display or on creation of the PEM file, where that information becomes available. The workaround of trimming whitespace characters from the encoded string is ugly and unacceptable.
Re: 9.4. String Functions and Operators page does not document that encode adds line breaks
On Sat, Feb 8, 2020 at 12:10 PM PG Doc comments form 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.
Re: Lack of detailed documentation
On Fri, Feb 7, 2020 at 4:53 PM PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/functions-geometry.html > Description: > > On: https://www.postgresql.org/docs/current/functions-geometry.html > > The functions aren't defined, nor have pointers. For instance: > * Scaling/rotationbox '((0,0),(1,1))' * point '(2.0,0)' > > I see how it can be scaling (or shearing), but how does it do rotation? > Or maybe when the points x^2+y^2 == 1, it's interpreted at rotation? > Google: "box point multiplication postgres" came up with the follow book section: https://books.google.com/books?id=gkQVL9pyFVYC&pg=PA95&lpg=PA95&dq=box+point+multiplication+postgres&source=bl&ots=E8z9PZHum-&sig=ACfU3U1QyE1TkI6ceUX24sQzl_zrsEH5lQ&hl=en&sa=X&ved=2ahUKEwiVhO2_48LnAhWXFzQIHVwYCXQQ6AEwAXoECAoQAQ#v=onepage&q=box%20point%20multiplication%20postgres&f=false Haven't independently confirm the math but it sounds reasonable... Each operator needs a full explanation... > Patch submissions are welcomed. David J.
