From 0937f6d172921202e1b432e206e4c30775d564d8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 28 Sep 2022 12:31:36 -0400 Subject: [PATCH] Doc: document bpchar, clarify relationship of text and varchar. For some reason the "bpchar" type name was defined nowhere in our SGML docs, although several places refer to it in passing. Give it a proper mention under Character Types. While here, also provide an explanation of how the text and varchar types relate. The previous wording seemed to be doing its best to sweep text under the rug, which doesn't seem very appropriate given its prominence in other parts of the docs. Minor rearrangements and word-smithing for clarity, too. Laurenz Albe and Tom Lane, per gripe from Yanliang Lei Discussion: https://postgr.es/m/120b3084.56b6.1833b5ffe4b.Coremail.msdnchina@163.com --- doc/src/sgml/datatype.sgml | 59 +++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 0258b192e0..b030b36002 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1154,6 +1154,10 @@ SELECT '52093.89'::money::numeric::float8; varchar + + bpchar + + Character Types @@ -1169,7 +1173,7 @@ SELECT '52093.89'::money::numeric::float8; variable-length with limit - character(n), char(n) + character(n), char(n), bpchar(n) fixed-length, blank padded @@ -1196,7 +1200,14 @@ SELECT '52093.89'::money::numeric::float8; error, unless the excess characters are all spaces, in which case the string will be truncated to the maximum length. (This somewhat bizarre exception is required by the SQL - standard.) If the string to be stored is shorter than the declared + standard.) + However, if one explicitly casts a value to character + varying(n) or + character(n), then an over-length + value will be truncated to n characters without + raising an error. (This too is required by the + SQL standard.) + If the string to be stored is shorter than the declared length, values of type character will be space-padded; values of type character varying will simply store the shorter @@ -1204,33 +1215,35 @@ SELECT '52093.89'::money::numeric::float8; - If one explicitly casts a value to character - varying(n) or - character(n), then an over-length - value will be truncated to n characters without - raising an error. (This too is required by the - SQL standard.) + In addition, PostgreSQL provides the + text type, which stores strings of any length. + Although the text type is not in the + SQL standard, several other SQL database + management systems have it as well. + text is PostgreSQL's native + string data type, in that most built-in functions operating on strings + are declared to take or return text not character + varying. For many purposes, character varying + acts as though it were a domain + over text. - The notations varchar(n) and - char(n) are aliases for character - varying(n) and - character(n), respectively. - If specified, the length must be greater than zero and cannot exceed - 10485760. + The type name varchar is an alias for character + varying, while char and bpchar are + aliases for character. + The varchar and char aliases are defined in + the SQL standard, but bpchar is + a PostgreSQL extension. + + + + If specified, the length n must be greater + than zero and cannot exceed 10485760. character without length specifier is equivalent to character(1). If character varying is used without length specifier, the type accepts strings of any size. The - latter is a PostgreSQL extension. - - - - In addition, PostgreSQL provides the - text type, which stores strings of any length. - Although the type text is not in the - SQL standard, several other SQL database - management systems have it as well. + latter behavior is a PostgreSQL extension.