From 81ad1161ed864e1572e5319eecec037670e940b4 Mon Sep 17 00:00:00 2001 From: Jeff Davis Date: Wed, 12 Aug 2026 07:32:19 -0700 Subject: [PATCH vPG19 2/3] Add missing comments in pg_locale.c. Suggested-by: Andres Freund Discussion: https://postgr.es/m/v3nniwcrxejmcfvz56xbd22hphprqleuornd6hqkmw2bl7kgmz@cnytz2ee5ltk Backpatch-through: 18 --- src/backend/utils/adt/pg_locale.c | 70 ++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 10 deletions(-) diff --git a/src/backend/utils/adt/pg_locale.c b/src/backend/utils/adt/pg_locale.c index 9eb99487e57..da32590396f 100644 --- a/src/backend/utils/adt/pg_locale.c +++ b/src/backend/utils/adt/pg_locale.c @@ -1317,6 +1317,20 @@ strupper_c(char *dst, size_t dstsize, const char *src, size_t srclen) return srclen; } +/* + * pg_strlower() + * + * Convert src to lowercase, and return the result length (not including + * terminating NUL). + * + * 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. + * + * If the result length is less than dstsize, the NUL-terminated result is + * stored in dst. Otherwise, the contents of dst are undefined, and the + * caller should use the return value to resize the buffer and retry. + */ size_t pg_strlower(char *dst, size_t dstsize, const char *src, size_t srclen, pg_locale_t locale) @@ -1327,6 +1341,20 @@ pg_strlower(char *dst, size_t dstsize, const char *src, size_t srclen, return locale->ctype->strlower(dst, dstsize, src, srclen, locale); } +/* + * pg_strtitle() + * + * Convert src to titlecase, and return the result length (not including + * terminating NUL). + * + * 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. + * + * If the result length is less than dstsize, the NUL-terminated result is + * stored in dst. Otherwise, the contents of dst are undefined, and the + * caller should use the return value to resize the buffer and retry. + */ size_t pg_strtitle(char *dst, size_t dstsize, const char *src, size_t srclen, pg_locale_t locale) @@ -1337,6 +1365,20 @@ pg_strtitle(char *dst, size_t dstsize, const char *src, size_t srclen, return locale->ctype->strtitle(dst, dstsize, src, srclen, locale); } +/* + * pg_strupper() + * + * Convert src to uppercase, and return the result length (not including + * terminating NUL). + * + * 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. + * + * If the result length is less than dstsize, the NUL-terminated result is + * stored in dst. Otherwise, the contents of dst are undefined, and the + * caller should use the return value to resize the buffer and retry. + */ size_t pg_strupper(char *dst, size_t dstsize, const char *src, size_t srclen, pg_locale_t locale) @@ -1347,6 +1389,19 @@ pg_strupper(char *dst, size_t dstsize, const char *src, size_t srclen, return locale->ctype->strupper(dst, dstsize, src, srclen, locale); } +/* + * pg_strfold() + * + * Casefold src, and return the result length (not including terminating NUL). + * + * 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. + * + * If the result length is less than dstsize, the NUL-terminated result is + * stored in dst. Otherwise, the contents of dst are undefined, and the + * caller should use the return value to resize the buffer and retry. + */ size_t pg_strfold(char *dst, size_t dstsize, const char *src, size_t srclen, pg_locale_t locale) @@ -1392,11 +1447,9 @@ pg_strcoll(const char *arg1, const char *arg2, pg_locale_t locale) /* * pg_strncoll * - * Call ucol_strcollUTF8(), ucol_strcoll(), strcoll_l() or wcscoll_l() as - * appropriate for the given locale, platform, and database encoding. If the - * locale is not specified, use the database collation. + * Compare strings according to the given locale. * - * The input strings must be encoded in the database encoding. + * Strings must be encoded in the database encoding with no embedded NULs. * * The caller is responsible for breaking ties if the collation is * deterministic; this maintains consistency with pg_strnxfrm(), which cannot @@ -1412,9 +1465,6 @@ pg_strncoll(const char *arg1, size_t len1, const char *arg2, size_t len2, /* * Return true if the collation provider supports pg_strxfrm() and * pg_strnxfrm(); otherwise false. - * - * - * No similar problem is known for the ICU provider. */ bool pg_strxfrm_enabled(pg_locale_t locale) @@ -1445,8 +1495,8 @@ pg_strxfrm(char *dest, const char *src, size_t destsize, pg_locale_t locale) * ordinary strcmp() on transformed strings is equivalent to pg_strcoll() on * untransformed strings. * - * The input string must be encoded in the database encoding. If 'destsize' is - * zero, 'dest' may be NULL. + * String must be encoded in the database encoding with no embedded NULs. If + * 'destsize' is zero, 'dest' may be NULL. * * Not all providers support pg_strnxfrm() safely. The caller should check * pg_strxfrm_enabled() first, otherwise this function may return wrong @@ -1492,7 +1542,7 @@ pg_strxfrm_prefix(char *dest, const char *src, size_t destsize, * memcmp() on the byte sequence is equivalent to pg_strncoll() on * untransformed strings. The result is not nul-terminated. * - * The input string must be encoded in the database encoding. + * String must be encoded in the database encoding with no embedded NULs. * * Not all providers support pg_strnxfrm_prefix() safely. The caller should * check pg_strxfrm_prefix_enabled() first, otherwise this function may return -- 2.43.0