Thread: nchar is undocumented

nchar is undocumented

From
Erik Wienhold
Date:
While studying the parser, I noticed that we support nchar and the n''
literal.  But both concepts are undocumented.  That may be intentional
because nchar is just an alias for char and because all our string types
are multibyte and therefore essentially national character strings.

I was looking through the archive for previous discussions and found:

* Thread [1] (about making nchar a distinct type) which noted that docs
  are missing but nobody proposed a fix.

* Thread [2] where Peter Eisentraut suggested leaving nchar undocumented
  until it's figured out if our implementation matches the standard.

What bugs me about the missing docs is that 7081ac46ace added nchar to
the intro for table 9.47[3], assuming that the reader already knows
about nchar.  That's the only instance of nchar in the docs (besides the
keyword list).

So, I think we should either remove that one nchar instance (because it
doesn't add any real value) or document it properly.  The attached patch
does the latter.

[1] https://www.postgresql.org/message-id/B1A7485194DE4FDAB8FA781AFB570079%40maumau
[2] https://www.postgresql.org/message-id/1275895438.1849.1.camel%40fsopti579.F-Secure.com
[3] https://www.postgresql.org/docs/16/functions-json.html#FUNCTIONS-JSON-CREATION-TABLE

-- 
Erik

Attachment

Re: nchar is undocumented

From
David Rowley
Date:
On Sun, 5 May 2024 at 12:41, Erik Wienhold <ewie@ewie.name> wrote:
> So, I think we should either remove that one nchar instance (because it
> doesn't add any real value) or document it properly.  The attached patch
> does the latter.

It seems easier to do the former, that way we don't need to reconsider
Peter's concerns about not having enough confidence that it matches
the standard.

I've included Alvaro and Peter to see what they think.

David



Re: nchar is undocumented

From
Alvaro Herrera
Date:
On 2024-May-05, David Rowley wrote:

> On Sun, 5 May 2024 at 12:41, Erik Wienhold <ewie@ewie.name> wrote:
> > So, I think we should either remove that one nchar instance (because it
> > doesn't add any real value) or document it properly.  The attached patch
> > does the latter.
> 
> It seems easier to do the former, that way we don't need to reconsider
> Peter's concerns about not having enough confidence that it matches
> the standard.
> 
> I've included Alvaro and Peter to see what they think.

Yeah, I too am inclined to remove it.  This text was initially written
by Mantrova, Bartunov and Glukhov and posted in [1] without further
explanation, from where it was copied by Glukhov into [2]; the one I
committed is a direct derivate from that.  There was no discussion about
nchar specifically that I can see, and at least I simply failed to
realize that nchar was not something that we talk about.

I'll remove it from the list, and backpatch to 16.

[1] https://postgr.es/m/732208d3-56c3-25a4-8f08-3be1d54ad51b@postgrespro.ru
[2] https://postgr.es/m/8c1ba295-fa42-d4f2-a155-76cf3327d07c@postgrespro.ru
%

If you, Erik, want to spend some time thinking through the standard
definition of NCHAR and whether we conform, perhaps we can document it
more fully.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"Java is clearly an example of money oriented programming"  (A. Stepanov)



Re: nchar is undocumented

From
Alvaro Herrera
Date:
By the way, this neighboring sentence is a bit awkward

" It must be ... or a type for which there is a cast from json to that type."

Would it be better to say
  " It must be ... or a type to which a cast from json exists."
?

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/
"La espina, desde que nace, ya pincha" (Proverbio africano)



Re: nchar is undocumented

From
Peter Eisentraut
Date:
On 06.05.24 10:53, Alvaro Herrera wrote:
> On 2024-May-05, David Rowley wrote:
> 
>> On Sun, 5 May 2024 at 12:41, Erik Wienhold <ewie@ewie.name> wrote:
>>> So, I think we should either remove that one nchar instance (because it
>>> doesn't add any real value) or document it properly.  The attached patch
>>> does the latter.
>>
>> It seems easier to do the former, that way we don't need to reconsider
>> Peter's concerns about not having enough confidence that it matches
>> the standard.
>>
>> I've included Alvaro and Peter to see what they think.
> 
> Yeah, I too am inclined to remove it.  This text was initially written
> by Mantrova, Bartunov and Glukhov and posted in [1] without further
> explanation, from where it was copied by Glukhov into [2]; the one I
> committed is a direct derivate from that.  There was no discussion about
> nchar specifically that I can see, and at least I simply failed to
> realize that nchar was not something that we talk about.
> 
> I'll remove it from the list, and backpatch to 16.

Yeah, makes sense to at least undocument it consistently.

> If you, Erik, want to spend some time thinking through the standard
> definition of NCHAR and whether we conform, perhaps we can document it
> more fully.

I think the idea of NCHAR and its variants is that you could sort of 
have two character sets pre-selected: One is the character set set by 
the client (maybe historically ASCII) and the other is one you designate 
as the "national" one.  Since in PostgreSQL, a given session always has 
one character set active, this is trivially true, so I think we can 
leave it like that.



Re: nchar is undocumented

From
Erik Wienhold
Date:
On 2024-05-06 10:59 +0200, Alvaro Herrera wrote:
> By the way, this neighboring sentence is a bit awkward
> 
> " It must be ... or a type for which there is a cast from json to that type."
> 
> Would it be better to say
>   " It must be ... or a type to which a cast from json exists."
> ?

Yeah, that sounds better, but I'd say:
    "[...] or a type _for_ which a cast from json exists."

Or maybe just
    "[...] or any type that can be cast to json."
?

-- 
Erik



Re: nchar is undocumented

From
Alvaro Herrera
Date:
On 2024-May-06, Erik Wienhold wrote:

> On 2024-05-06 10:59 +0200, Alvaro Herrera wrote:
> > By the way, this neighboring sentence is a bit awkward
> > 
> > " It must be ... or a type for which there is a cast from json to that type."

> Or maybe just
>     "[...] or any type that can be cast to json."
> ?

WFM, thanks, pushed.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/