From: Tom Lane Date: Thu, 13 Jun 2019 02:54:46 +0000 (-0400) Subject: Doc: improve description of allowed spellings for Boolean input. X-Git-Tag: REL_12_BETA2~29 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9729c9360886bee7feddc6a1124b0742de4b9f3d;p=postgresql Doc: improve description of allowed spellings for Boolean input. datatype.sgml failed to explain that boolin() accepts any unique prefix of the basic input strings. Indeed it was actively misleading because it called out a few minimal prefixes without mentioning that there were more valid inputs. I also felt that it wasn't doing anybody any favors by conflating SQL key words, valid Boolean input, and string literals containing valid Boolean input. Rewrite in hopes of reducing the confusion. Per bug #15836 from Yuming Wang, as diagnosed by David Johnston. Back-patch to supported branches. Discussion: https://postgr.es/m/15836-656fab055735f511@postgresql.org --- diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index fc300f605f..35ecd48ed5 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -2905,37 +2905,36 @@ SELECT EXTRACT(days from '80 hours'::interval); - Valid literal values for the true state are: + Boolean constants can be represented in SQL queries by the SQL + key words TRUE, FALSE, + and NULL. + + + + The datatype input function for type boolean accepts these + string representations for the true state: - TRUE - 't' - 'true' - 'y' - 'yes' - 'on' - '1' + true + yes + on + 1 - For the false state, the following values can be - used: + and these representations for the false state: - FALSE - 'f' - 'false' - 'n' - 'no' - 'off' - '0' + false + no + off + 0 + Unique prefixes of these strings are also accepted, for + example t or n. Leading or trailing whitespace is ignored, and case does not matter. - The key words - TRUE and FALSE are the preferred - (SQL-compliant) usage. - shows that - boolean values are output using the letters - t and f. + The datatype output function for type boolean always emits + either t or f, as shown in + . @@ -2957,6 +2956,27 @@ SELECT * FROM test1 WHERE a; t | sic est + + + The key words TRUE and FALSE are + the preferred (SQL-compliant) method for writing + Boolean constants in SQL queries. But you can also use the string + representations by following the generic string-literal constant syntax + described in , for + example 'yes'::boolean. + + + + Note that the parser automatically understands + that TRUE and FALSE are of + type boolean, but this is not so + for NULL because that can have any type. + So in some contexts you might have to cast NULL + to boolean explicitly, for + example NULL::boolean. Conversely, the cast can be + omitted from a string-literal Boolean value in contexts where the parser + can deduce that the literal must be of type boolean. +