From 70ebdd061f9ae158b1674453e4a6e03db1b74815 Mon Sep 17 00:00:00 2001 From: Jeff Davis Date: Wed, 12 Aug 2026 07:32:19 -0700 Subject: [PATCH vPG18 3/4] 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 | 76 +++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 13 deletions(-) diff --git a/src/backend/utils/adt/pg_locale.c b/src/backend/utils/adt/pg_locale.c index 8e79ccbd9f6..c21619f85cd 100644 --- a/src/backend/utils/adt/pg_locale.c +++ b/src/backend/utils/adt/pg_locale.c @@ -1324,6 +1324,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 srclen is + * -1, src must be NUL-terminated. 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, ssize_t srclen, pg_locale_t locale) @@ -1347,6 +1361,20 @@ pg_strlower(char *dst, size_t dstsize, const char *src, ssize_t srclen, return 0; /* keep compiler quiet */ } +/* + * 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 srclen is + * -1, src must be NUL-terminated. 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, ssize_t srclen, pg_locale_t locale) @@ -1370,6 +1398,20 @@ pg_strtitle(char *dst, size_t dstsize, const char *src, ssize_t srclen, return 0; /* keep compiler quiet */ } +/* + * 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 srclen is + * -1, src must be NUL-terminated. 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, ssize_t srclen, pg_locale_t locale) @@ -1393,6 +1435,19 @@ pg_strupper(char *dst, size_t dstsize, const char *src, ssize_t srclen, return 0; /* keep compiler quiet */ } +/* + * 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 srclen is + * -1, src must be NUL-terminated. 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, ssize_t srclen, pg_locale_t locale) @@ -1432,12 +1487,10 @@ 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. If an input - * string is NUL-terminated, its length may be specified as -1. + * Strings must be encoded in the database encoding with no embedded NULs. If + * an input string is NUL-terminated, its length may be specified as -1. * * The caller is responsible for breaking ties if the collation is * deterministic; this maintains consistency with pg_strnxfrm(), which cannot @@ -1453,9 +1506,6 @@ pg_strncoll(const char *arg1, ssize_t len1, const char *arg2, ssize_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) @@ -1486,9 +1536,9 @@ 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 the input - * string is NUL-terminated, its length may be specified as -1. If 'destsize' - * is zero, 'dest' may be NULL. + * String must be encoded in the database encoding with no embedded NULs. If + * srclen is -1, src must be NUL-terminated. 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 @@ -1534,8 +1584,8 @@ 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. If the input - * string is NUL-terminated, its length may be specified as -1. + * String must be encoded in the database encoding with no embedded NULs. If + * the input string is NUL-terminated, its length may be specified as -1. * * 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