Document how to deal with bignums, negative numbers and floating-point numbers.

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index e40624c3325236f437e385851c1ee24198ef9400..a92199d98f6bb1aaeebf69551ff2ab6690b8bb47 100644 (file)
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,3 +1,9 @@
+2006-08-16  Bruno Haible  <bruno@clisp.org>
+
+       * gettext.texi (Plural forms): Document how to deal with bignums,
+       negative numbers and floating-point numbers.
+       Suggested by Paul Eggert <eggert@cs.ucla.edu>.
+
 2006-08-16  Bruno Haible  <bruno@clisp.org>
 
        * gettext.texi (Plural Forms): Put Hungarian under nplurals=2, and

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index f95e10be15e779ca772dc8f3c021f885e6e34fc9..8051587c960e87c118d4703c1005c24cc7ddab9f 100644 (file)
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5479,6 +5479,51 @@ Slovenian
 @end table
 @end table
 
+You might now ask, @code{ngettext} handles only numbers @var{n} of type
+@samp{unsigned long}.  What about larger integer types?  What about negative
+numbers?  What about floating-point numbers?
+
+About larger integer types, such as @samp{uintmax_t} or 
+@samp{unsigned long long}: they can be handled by reducing the value to a
+range that fits in an @samp{unsigned long}.  Simply casting the value to
+@samp{unsigned long} would not do the right thing, since it would treat
+@code{ULONG_MAX + 1} like zero, @code{ULONG_MAX + 2} like singular, and
+the like.  Here you can exploit the fact that all mentioned plural form
+formulas eventually become periodic, with a period that is a divisor of 100
+(or 1000 or 1000000).  So, when you reduce a large value to another one in
+the range [1000000, 1999999] that ends in the same 6 decimal digits, you
+can assume that it will lead to the same plural form selection.  This code
+does this:
+
+@smallexample
+#include <inttypes.h>
+uintmax_t nbytes = ...;
+printf (ngettext ("The file has %"PRIuMAX" byte.",
+                  "The file has %"PRIuMAX" bytes.",
+                  (nbytes > ULONG_MAX
+                   ? (nbytes % 1000000) + 1000000
+                   : nbytes)),
+        nbytes);
+@end smallexample
+
+Negative and floating-point values usually represent physical entities for
+which singular and plural don't clearly apply.  In such cases, there is no
+need to use @code{ngettext}; a simple @code{gettext} call with a form suitable
+for all values will do.  For example:
+
+@smallexample
+printf (gettext ("Time elapsed: %.3f seconds"),
+        num_milliseconds * 0.001);
+@end smallexample
+
+@noindent
+Even if @var{num_milliseconds} happens to be a multiple of 1000, the output
+@smallexample
+Time elapsed: 1.000 seconds
+@end smallexample
+@noindent
+is acceptable in English, and similarly for other languages.
+
 @node Optimized gettext,  , Plural forms, gettext
 @subsection Optimization of the *gettext functions
 @cindex optimization of @code{gettext} functions