From afaa32daf293163cb9612bdb20a04a5fcb26309d Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 12 Jun 2019 22:54:46 -0400 Subject: [PATCH] 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 --- doc/src/sgml/datatype.sgml | 76 ++++++++++++++++++++++++-------------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 281fdb6d60..401a2f07ae 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -2894,37 +2894,36 @@ SELECT EXTRACT(days from '80 hours'::interval); - Valid literal values for the true state are: - - TRUE - 't' - 'true' - 'y' - 'yes' - 'on' - '1' - - For the false state, the following values can be - used: - - FALSE - 'f' - 'false' - 'n' - 'no' - 'off' - '0' - - Leading or trailing whitespace is ignored, and case does not matter. - The key words - TRUE and FALSE are the preferred - (SQL-compliant) usage. + Boolean constants can be represented in SQL queries by the SQL + key words TRUE, FALSE, + and NULL. - shows that - boolean values are output using the letters - t and f. + The datatype input function for type boolean accepts these + string representations for the true state: + + true + yes + on + 1 + + and these representations for the false state: + + 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 datatype output function for type boolean always emits + either t or f, as shown in + . @@ -2946,6 +2945,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. +