From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 7 Apr 2024 13:41:34 -0500
Subject: new repository

---
 devdocs/elisp/c-integer-types.html | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 devdocs/elisp/c-integer-types.html

(limited to 'devdocs/elisp/c-integer-types.html')

diff --git a/devdocs/elisp/c-integer-types.html b/devdocs/elisp/c-integer-types.html
new file mode 100644
index 00000000..5e24088e
--- /dev/null
+++ b/devdocs/elisp/c-integer-types.html
@@ -0,0 +1,19 @@
+ <h3 class="section"> C Integer Types</h3>  <p>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. </p> <ul> <li> Avoid arbitrary limits. For example, avoid <code>int len = strlen
+(s);</code> unless the length of <code>s</code> is required for other reasons to fit in <code>int</code> range. </li>
+<li> 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. </li>
+<li> 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., <code>size_t</code> instead of <code>ptrdiff_t</code>, or <code>uintptr_t</code> instead of <code>intptr_t</code>). </li>
+<li> Prefer <code>int</code> for Emacs character codes, in the range 0 .. 0x3FFFFF. More generally, prefer <code>int</code> for integers known to be in <code>int</code> range, e.g., screen column counts. </li>
+<li> Prefer <code>ptrdiff_t</code> 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</code> limits objects to <code>PTRDIFF_MAX</code> bytes, but larger objects would cause trouble anyway since they would break pointer subtraction, so this does not impose an arbitrary limit. </li>
+<li> Avoid <code>ssize_t</code> except when communicating to low-level APIs that have <code>ssize_t</code>-related limitations. Although it’s equivalent to <code>ptrdiff_t</code> on typical platforms, <code>ssize_t</code> is occasionally narrower, so using it for size-related calculations could overflow. Also, <code>ptrdiff_t</code> is more ubiquitous and better-standardized, has standard <code>printf</code> formats, and is the basis for Emacs’s internal size-overflow checking. When using <code>ssize_t</code>, please note that POSIX requires support only for values in the range -1 .. <code>SSIZE_MAX</code>. </li>
+<li> Normally, prefer <code>intptr_t</code> 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. However, prefer <code>uintptr_t</code> to represent pointer arithmetic that could cross page boundaries. For example, on a machine with a 32-bit address space an array could cross the 0x7fffffff/0x80000000 boundary, which would cause an integer overflow when adding 1 to <code>(intptr_t) 0x7fffffff</code>. </li>
+<li> Prefer the Emacs-defined type <code>EMACS_INT</code> for representing values converted to or from Emacs Lisp fixnums, as fixnum arithmetic is based on <code>EMACS_INT</code>. </li>
+<li> 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., <code>off_t</code>, <code>time_t</code>). Do not assume that a system type is signed, unless this assumption is known to be safe. For example, although <code>off_t</code> is always signed, <code>time_t</code> need not be. </li>
+<li> Prefer <code>intmax_t</code> for representing values that might be any signed integer value. A <code>printf</code>-family function can print such a value via a format like <code>"%"PRIdMAX</code>. </li>
+<li> Prefer <code>bool</code>, <code>false</code> and <code>true</code> for booleans. Using <code>bool</code> can make programs easier to read and a bit faster than using <code>int</code>. Although it is also OK to use <code>int</code>, <code>0</code> and <code>1</code>, this older style is gradually being phased out. When using <code>bool</code>, respect the limitations of the replacement implementation of <code>bool</code>, as documented in the source file <samp>lib/stdbool.in.h</samp>. In particular, boolean bitfields should be of type <code>bool_bf</code>, not <code>bool</code>, so that they work correctly even when compiling Objective C with standard GCC. </li>
+<li> In bitfields, prefer <code>unsigned int</code> or <code>signed int</code> to <code>int</code>, as <code>int</code> is less portable: it might be signed, and might not be. Single-bit bit fields should be <code>unsigned int</code> or <code>bool_bf</code> so that their values are 0 or 1. </li>
+</ul><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/C-Integer-Types.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/C-Integer-Types.html</a>
+  </p>
+</div>
-- 
cgit v1.2.3