idx: add commentary

* lib/idx.h: Add comments about ssize_t and strlen, in
response to comments from Simon Josefsson in:
https://lists.gnu.org/r/bug-gnulib/2021-08/msg00196.html

2 files changed, 27 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index b86a6c33a7..1b1372cb76 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2021-08-30  Paul Eggert  <eggert@cs.ucla.edu>
+
+	idx: add commentary
+	* lib/idx.h: Add comments about ssize_t and strlen, in
+	response to comments from Simon Josefsson in:
+	https://lists.gnu.org/r/bug-gnulib/2021-08/msg00196.html
+
 2021-08-29  Paul Eggert  <eggert@cs.ucla.edu>
 
 	attribute: keep up with gnulib-common.m4
diff --git a/lib/idx.h b/lib/idx.h
index 483587eabb..54ad5d81fe 100644
--- a/lib/idx.h
+++ b/lib/idx.h
@@ -56,6 +56,26 @@
      * Because 'size_t' is an unsigned type, and a signed type is better.
        See above.
 
+   Why not use 'ssize_t'?
+
+     * 'ptrdiff_t' is more portable; it is standardized by ISO C
+       whereas 'ssize_t' is standardized only by POSIX.
+
+     * 'ssize_t' is not required to be as wide as 'size_t', and some
+       now-obsolete POSIX platforms had 'size_t' wider than 'ssize_t'.
+
+     * Conversely, some now-obsolete platforms had 'ptrdiff_t' wider
+       than 'size_t', which can be a win and conforms to POSIX.
+
+   Won't this cause a problem with objects larger than PTRDIFF_MAX?
+
+     * Typical modern or large platforms do not allocate such objects,
+       so this is not much of a problem in practice; for example, you
+       can safely write 'idx_t len = strlen (s);'.  To port to older
+       small platforms where allocations larger than PTRDIFF_MAX could
+       in theory be a problem, you can use Gnulib's ialloc module, or
+       functions like ximalloc in Gnulib's xalloc module.
+
    Why not use 'ptrdiff_t' directly?
 
      * Maintainability: When reading and modifying code, it helps to know that