Re: Another ptrdiff_t

[Paul Eggert]

On 07/22/2012 08:43 AM, Eli Zaretskii wrote:
> Can we perhaps have some conventions regarding which integer types to
> use in what situations?

Sure, here's a first cut.  Perhaps this sort of thing should be put
into a comment in lisp.h?  Or into a new file under admin/notes?

====

Here are some guidelines for use of integer types in the Emacs C
source code.  These guidelines sometimes give competing advice; common
sense is advised.

 . Avoid arbitrary limits.  For example, avoid 'int len = strlen (s);'
   unless S's length is required for other reasons to fit in 'int' range.

 . Do not assume that signed integer arithmetic wraps around on overflow.
   This is no longer true of Emacs porting targets: signed integer
   overflow has undefined behavior in practice, and can dump core or
   even cause earlier or later code to behave "illogically".  Unsigned
   overflow does wrap around reliably.

 . Prefer signed types to unsigned, as code gets confusing when signed
   and unsigned types are combined.  Many other guidelines assume that
   types are signed; in the rarer cases where unsigned types are
   needed, similar advice may apply to the unsigned counterparts
   (e.g., size_t instead of ptrdiff_t, or uintptr_t instead of
   intptr_t).

 . Prefer 'int' for Emacs character codes, in the range 0 .. 0x3FFFFF.

 . Prefer ptrdiff_t for sizes, i.e., for integers bounded by the
   maximum size of any individual C object or by the maximum number of
   elements in any C array.  This is part of Emacs's general
   preference for signed types.  Using ptrdiff_t limits objects to
   PTRDIFF_MAX bytes, but larger objects would cause trouble anyway
   since they would break pointer subtraction, so this does not impose
   an arbitrary limit.

 . Prefer intptr_t for internal representations of pointers, or for
   integers bounded only by the number of objects that can exist at
   any given time or by the total number of bytes that can be
   allocated.  Currently Emacs sometimes uses other types when
   intptr_t would be better; fixing this is lower priority, as the
   code works as-is on Emacs's current porting targets.

 . Prefer EMACS_INT for representing values converted to or from Emacs
   Lisp fixnums, as fixnum arithmetic is based on EMACS_INT.

 . When representing a system value (such as a file size or a count of
   seconds since the Epoch), prefer the corresponding system type
   (e.g., off_t, time_t).  Do not assume that a system type is signed,
   unless this assumption is known to be safe (e.g., although off_t
   must be signed, time_t need not be).

 . Prefer printmax_t for representing values that might be any signed
   integer value that can be printed, using a printf-family function.

 . Prefer intmax_t for representing values that might be any signed
   integer value.

 . In bitfields, prefer 'unsigned int' to 'int' when space is tight,
   as 'int' is less portable (it might be signed, and might not be).

 . Currently Emacs typically uses 'int', 1, and 0 for boolean values.
   It's OK to use 'bool', 'true', and 'false' instead, as this usage
   is now portable -- a Gnulib <stdbool.h> replacement is used on
   older platforms.  Using 'bool' can make programs easier to read,
   and a bit faster.  At some point we may change Emacs to prefer
   'bool' to 'int' where either will do.