From 04a20a4a1b02ac12eecde28e441e0a20e5063382 Mon Sep 17 00:00:00 2001 From: Jeff Davis Date: Mon, 24 Aug 2026 11:51:02 -0700 Subject: [PATCH] pg_locale.c: add explanatory comments. Explain the purpose of case mapping functions, rather than just the API. Suggested-by: Andres Freund Discussion: https://postgr.es/m/v36ssaygf7grb3qzfsjhtdzi7kqd45ds56nyuf7gi5qjml4qbb@ezmfqzmhlrs2 Backpatch-through: 18 --- src/backend/utils/adt/pg_locale.c | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/backend/utils/adt/pg_locale.c b/src/backend/utils/adt/pg_locale.c index 4f0d0ca5057..7f73cd75956 100644 --- a/src/backend/utils/adt/pg_locale.c +++ b/src/backend/utils/adt/pg_locale.c @@ -1323,6 +1323,9 @@ strupper_c(char *dst, size_t dstsize, const char *src, size_t srclen) * Convert src to lowercase, and return the result length (not including * terminating NUL). * + * Lowercasing is intended for human-readable display. If the goal is to + * convert to a canonical caseless form, see pg_strfold(). + * * src must be in the database encoding with no embedded NULs. If dstsize is * zero, dst may be NULL, which is useful for calculating the required buffer * size before allocating. @@ -1347,6 +1350,11 @@ pg_strlower(char *dst, size_t dstsize, const char *src, size_t srclen, * Convert src to titlecase, and return the result length (not including * terminating NUL). * + * Titlecasing is intended for human-readable display. A titlecase string has + * the initial letter of each word uppercased (or changed to a special + * titlecase form, if available), and all other characters lowercased. Used + * to implement the SQL INITCAP() function. + * * src must be in the database encoding with no embedded NULs. If dstsize is * zero, dst may be NULL, which is useful for calculating the required buffer * size before allocating. @@ -1371,6 +1379,9 @@ pg_strtitle(char *dst, size_t dstsize, const char *src, size_t srclen, * Convert src to uppercase, and return the result length (not including * terminating NUL). * + * Uppercasing is intended for human-readable display. If the goal is to + * convert to a canonical caseless form, see pg_strfold(). + * * src must be in the database encoding with no embedded NULs. If dstsize is * zero, dst may be NULL, which is useful for calculating the required buffer * size before allocating. @@ -1392,7 +1403,17 @@ pg_strupper(char *dst, size_t dstsize, const char *src, size_t srclen, /* * pg_strfold() * - * Casefold src, and return the result length (not including terminating NUL). + * Casefold src, and return the result length (not including terminating + * NUL). + * + * Casefolding produces a canonical string such that, iff the casefolded + * strings are equal, the original strings are a case-insensitive match (the + * strength of this guarantee depends on normalization, provider and locale). + * In practice the result is similar to lowercasing, but the purpose is + * different: lowercasing is for human-readable display; whereas casefolding + * is meant to canonicalize complex mappings reliably without regard for + * display. Unicode guarantees that casefolding is stable across versions if + * the original string consists only of assigned code points. * * src must be in the database encoding with no embedded NULs. If dstsize is * zero, dst may be NULL, which is useful for calculating the required buffer