database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2026-10-23 13:29:09 +03:00
Code Activity

pg_locale.c: add explanatory comments.

Browse Source 
Explain the purpose of case mapping functions, rather than just the
API.

Suggested-by: Andres Freund <andres@anarazel.de>
Discussion: https://postgr.es/m/v36ssaygf7grb3qzfsjhtdzi7kqd45ds56nyuf7gi5qjml4qbb@ezmfqzmhlrs2
Backpatch-through: 18
This commit is contained in:
Jeff Davis
2026-08-24 11:51:35 -07:00
parent 3b984ab52a
commit c96cd80d60
1 changed files with 22 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
src/backend/utils/adt/pg_locale.c
View File

@@ -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