Message-ID: <92151c4debb48bbbaed4db81c79d73c36f619858.camel@cybertec.at>
Subject: Re: BPCHAR description in 8.3. Character Types is misleading and
 incomplete
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Tom Lane <tgl@sss.pgh.pa.us>, Jeff Davis <pgsql@j-davis.com>
Cc: skatkovsky@gmail.com, pgsql-docs@lists.postgresql.org
Date: Fri, 17 Oct 2025 14:49:12 +0200
In-Reply-To: <1307875.1760556576@sss.pgh.pa.us>
References: <176044409338.770.16064383081308443747@wrigleys.postgresql.org>
	 <e9ad2cb03195402a96e8cb9130470bfca3bf49c7.camel@j-davis.com>
	 <1307875.1760556576@sss.pgh.pa.us>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.56.2 (3.56.2-2.fc42) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/92151c4debb48bbbaed4db81c79d73c36f619858.camel%40cybertec.at>
Precedence: bulk

On Wed, 2025-10-15 at 15:29 -0400, Tom Lane wrote:
> Jeff Davis <pgsql@j-davis.com> writes:
> > Please take a look at the attached patch. If you'd like your name
> > included in the commit, please send it as you'd like it to appear.
>=20
> I don't understand why any of these variants are better than the
> original wording "blank-padded".=C2=A0 That has the non-negligible
> advantage of corresponding to the type name, and furthermore
> appears in many other places in our docs and source code.
>=20
> There may be some other wording improvements we could make here,
> but I think b69db5173 was fundamentally misguided in this respect.

My suggestion is to just remove the "blank-trimmed" from the documentation.

"bpchar" and "varchar", when used without type modifier, are actually
identical:

SELECT octet_length(BPCHAR 'x   '),
       octet_length(VARCHAR 'x   '),
       octet_length(TEXT 'x   ');

 octet_length =E2=94=82 octet_length =E2=94=82 octet_length=20
=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=
=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=AA=E2=95=90=E2=95=
=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=
=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=AA=E2=95=90=E2=95=90=E2=95=90=E2=
=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=
=90=E2=95=90=E2=95=90
            4 =E2=94=82            4 =E2=94=82            4

The blank-trimming only occurs when a "bpchar" is converted to "text",
for example when used with the concatenation operator.

I suggest the following simplification:

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index b81d89e2608..05edab3bd33 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1177,11 +1177,7 @@ SELECT '52093.89'::money::numeric::float8;
         <entry>fixed-length, blank-padded</entry>
        </row>
        <row>
-        <entry><type>bpchar</type></entry>
-        <entry>variable unlimited length, blank-trimmed</entry>
-       </row>
-       <row>
-        <entry><type>text</type></entry>
+        <entry><type>text</type>, <type>varchar</type>, <type>bpchar</type=
></entry>
         <entry>variable unlimited length</entry>
        </row>
      </tbody>

Yours,
Laurenz Albe