From 02a2137c1ae521c09050e3d1614dd5d79c4107db Mon Sep 17 00:00:00 2001 From: Jeff Davis Date: Tue, 18 Aug 2026 13:19:59 -0700 Subject: [PATCH] pg_locale.c: comment improvements. Add missing comments and fix outdated/incorrect comments in pg_locale.c and related files. Suggested-by: Andres Freund Discussion: https://postgr.es/m/v3nniwcrxejmcfvz56xbd22hphprqleuornd6hqkmw2bl7kgmz@cnytz2ee5ltk Backpatch-through: 18 --- src/backend/utils/adt/pg_locale.c | 88 ++++++++++++++++++----- src/backend/utils/adt/pg_locale_builtin.c | 4 +- src/backend/utils/adt/pg_locale_icu.c | 15 ++-- src/include/utils/pg_locale.h | 6 +- 4 files changed, 81 insertions(+), 32 deletions(-) diff --git a/src/backend/utils/adt/pg_locale.c b/src/backend/utils/adt/pg_locale.c index 9c721efb52f..af01c9cf950 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 @@ -1451,11 +1504,8 @@ 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. + * Return true if the locale supports pg_strxfrm() and pg_strnxfrm(); + * otherwise false. */ 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 @@ -1506,7 +1556,7 @@ pg_strnxfrm(char *dest, size_t destsize, const char *src, ssize_t srclen, } /* - * Return true if the collation provider supports pg_strxfrm_prefix() and + * Return true if the locale supports pg_strxfrm_prefix() and * pg_strnxfrm_prefix(); otherwise false. */ bool @@ -1534,12 +1584,12 @@ 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. If + * destsize is zero, dest may be NULL. * - * Not all providers support pg_strnxfrm_prefix() safely. The caller should - * check pg_strxfrm_prefix_enabled() first, otherwise this function may return - * wrong results or an error. + * Not all providers support pg_strnxfrm_prefix() safely. The caller must + * check pg_strxfrm_prefix_enabled() first. * * If destsize is not large enough to hold the resulting byte sequence, stores * only the first destsize bytes in 'dest'. Returns the number of bytes diff --git a/src/backend/utils/adt/pg_locale_builtin.c b/src/backend/utils/adt/pg_locale_builtin.c index faf71d129d7..6079bdf8d83 100644 --- a/src/backend/utils/adt/pg_locale_builtin.c +++ b/src/backend/utils/adt/pg_locale_builtin.c @@ -182,8 +182,8 @@ char * get_collation_actual_version_builtin(const char *collcollate) { /* - * The only two supported locales (C and C.UTF-8) are both based on memcmp - * and are not expected to change, but track the version anyway. + * The supported locales (C, C.UTF-8, and PG_UNICODE_FAST) are all based + * on memcmp and are not expected to change, but track the version anyway. * * Note that the character semantics may change for some locales, but the * collation version only tracks changes to sort order. diff --git a/src/backend/utils/adt/pg_locale_icu.c b/src/backend/utils/adt/pg_locale_icu.c index 72c5fffa204..61075693e81 100644 --- a/src/backend/utils/adt/pg_locale_icu.c +++ b/src/backend/utils/adt/pg_locale_icu.c @@ -462,10 +462,9 @@ strfold_icu(char *dest, size_t destsize, const char *src, ssize_t srclen, } /* - * strncoll_icu_utf8 + * strncoll_icu_utf8() * - * Call ucol_strcollUTF8() or ucol_strcoll() as appropriate for the given - * database encoding. An argument length of -1 means the string is + * Wrapper for ucol_strcollUTF8(). An argument length of -1 means the string is * NUL-terminated. */ #ifdef HAVE_UCOL_STRCOLLUTF8 @@ -613,13 +612,11 @@ icu_to_uchar(UChar **buff_uchar, const char *buff, size_t nbytes) /* * Convert a string of UChars into the database encoding. * - * The source string at buff_uchar is of length len_uchar - * (it needn't be nul-terminated) + * The source string at buff_uchar is of length len_uchar (it needn't be + * nul-terminated) * - * *result receives a pointer to the palloc'd result string, and the - * function's result is the number of bytes generated (not counting nul). - * - * The result string is nul-terminated. + * If the result length is less than destsize, the NUL-terminated result is + * stored in dest. Otherwise the contents of dest are undefined. */ static size_t icu_from_uchar(char *dest, size_t destsize, const UChar *buff_uchar, int32_t len_uchar) diff --git a/src/include/utils/pg_locale.h b/src/include/utils/pg_locale.h index 3a758256591..6852969fead 100644 --- a/src/include/utils/pg_locale.h +++ b/src/include/utils/pg_locale.h @@ -69,7 +69,9 @@ extern void cache_locale_time(void); struct pg_locale_struct; typedef struct pg_locale_struct *pg_locale_t; -/* methods that define collation behavior */ +/* + * Collation behavior: string ordering. + */ struct collate_methods { /* required */ @@ -89,7 +91,7 @@ struct collate_methods /* * If the strnxfrm method is not trusted to return the correct results, - * set strxfrm_is_safe to false. It set to false, the method will not be + * set strxfrm_is_safe to false. If set to false, the method will not be * used in most cases, but the planner still expects it to be there for * estimation purposes (where incorrect results are acceptable). */