[Emacs-diffs] /srv/bzr/emacs/trunk r111179: * internals.texi (C Integer Types): New section.

[Paul Eggert]

------------------------------------------------------------
revno: 111179
committer: Paul Eggert <address@hidden>
branch nick: trunk
timestamp: Mon 2012-12-10 16:13:44 -0800
message:
  * internals.texi (C Integer Types): New section.
  
  This follows up and records an email in
  <http://lists.gnu.org/archive/html/emacs-devel/2012-07/msg00496.html>.
modified:
  doc/lispref/ChangeLog
  doc/lispref/internals.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-12-10 02:00:42 +0000
+++ b/doc/lispref/ChangeLog     2012-12-11 00:13:44 +0000
@@ -1,3 +1,9 @@
+2012-12-11  Paul Eggert  <address@hidden>
+
+       * internals.texi (C Integer Types): New section.
+       This follows up and records an email in
+       <http://lists.gnu.org/archive/html/emacs-devel/2012-07/msg00496.html>.
+
 2012-12-10  Stefan Monnier  <address@hidden>
 
        * control.texi (Pattern maching case statement): New node.

=== modified file 'doc/lispref/internals.texi'
--- a/doc/lispref/internals.texi        2012-12-07 02:37:20 +0000
+++ b/doc/lispref/internals.texi        2012-12-11 00:13:44 +0000
@@ -16,6 +16,7 @@
 * Memory Usage::        Info about total size of Lisp objects made so far.
 * Writing Emacs Primitives::   Writing C code for Emacs.
 * Object Internals::    Data formats of buffers, windows, processes.
+* C Integer Types::     How C integer types are used inside Emacs.
 @end menu
 
 @node Building Emacs
@@ -1531,4 +1532,91 @@
 
 @end table
 
address@hidden C Integer Types
address@hidden C Integer Types
address@hidden integer types (C programming language)
+
+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.
+
address@hidden @bullet
address@hidden
+Avoid arbitrary limits.  For example, avoid @code{int len = strlen
+(s);} unless the length of @code{s} is required for other reasons to
+fit in @code{int} range.
+
address@hidden
+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, modulo a power of two.
+
address@hidden
+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.,
address@hidden instead of @code{ptrdiff_t}, or @code{uintptr_t} instead
+of @code{intptr_t}).
+
address@hidden
+Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF.
+
address@hidden
+Prefer @code{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 @code{ptrdiff_t} limits objects to
address@hidden bytes, but larger objects would cause trouble
+anyway since they would break pointer subtraction, so this does not
+impose an arbitrary limit.
+
address@hidden
+Prefer @code{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 @code{intptr_t} would
+be better; fixing this is lower priority, as the code works as-is on
+Emacs's current porting targets.
+
address@hidden
+Prefer the Emacs-defined type @code{EMACS_INT} for representing values
+converted to or from Emacs Lisp fixnums, as fixnum arithmetic is based
+on @code{EMACS_INT}.
+
address@hidden
+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.,
address@hidden, @code{time_t}).  Do not assume that a system type is
+signed, unless this assumption is known to be safe.  For example,
+although @code{off_t} is always signed, @code{time_t} need not be.
+
address@hidden
+Prefer the Emacs-defined type @code{printmax_t} for representing
+values that might be any signed integer value that can be printed,
+using a @code{printf}-family function.
+
address@hidden
+Prefer @code{intmax_t} for representing values that might be any
+signed integer value.
+
address@hidden
+In bitfields, prefer @code{unsigned int} or @code{signed int} to
address@hidden, as @code{int} is less portable: it might be signed, and
+might not be.  Single-bit bit fields are invariably @code{unsigned
+int} so that their values are 0 and 1.
+
address@hidden
+In C, Emacs commonly uses @code{bool}, 1, and 0 for boolean values.
+Using @code{bool} for booleans can make programs easier to read and a
+bit faster than using @code{int}.  Although it is also OK to use
address@hidden, this older style is gradually being phased out.  When
+using @code{bool}, respect the limitations of the replacement
+implementation of @code{bool}, as documented in the source file
address@hidden/stdbool.in.h}, so that Emacs remains portable to pre-C99
+platforms.
address@hidden itemize
+
 @c FIXME Mention src/globals.h somewhere in this file?