| 1 |
/* A type for indices and sizes. |
| 2 |
Copyright (C) 2020-2024 Free Software Foundation, Inc. |
| 3 |
This file is part of the GNU C Library. |
| 4 |
|
| 5 |
The GNU C Library is free software; you can redistribute it and/or |
| 6 |
modify it under the terms of the GNU Lesser General Public |
| 7 |
License as published by the Free Software Foundation; either |
| 8 |
version 2.1 of the License, or (at your option) any later version. |
| 9 |
|
| 10 |
The GNU C Library is distributed in the hope that it will be useful, |
| 11 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 13 |
Lesser General Public License for more details. |
| 14 |
|
| 15 |
You should have received a copy of the GNU Lesser General Public |
| 16 |
License along with the GNU C Library; if not, see |
| 17 |
<https://www.gnu.org/licenses/>. */ |
| 18 |
|
| 19 |
#ifndef _IDX_H |
| 20 |
#define _IDX_H |
| 21 |
|
| 22 |
/* Get ptrdiff_t. */ |
| 23 |
#include <stddef.h> |
| 24 |
|
| 25 |
/* Get PTRDIFF_MAX. */ |
| 26 |
#include <stdint.h> |
| 27 |
|
| 28 |
/* The type 'idx_t' holds an (array) index or an (object) size. |
| 29 |
Its implementation promotes to a signed integer type, |
| 30 |
which can hold the values |
| 31 |
0..2^63-1 (on 64-bit platforms) or |
| 32 |
0..2^31-1 (on 32-bit platforms). |
| 33 |
|
| 34 |
Why a signed integer type? |
| 35 |
|
| 36 |
* Security: Signed types can be checked for overflow via |
| 37 |
'-fsanitize=undefined', but unsigned types cannot. |
| 38 |
|
| 39 |
* Comparisons without surprises: ISO C99 § 6.3.1.8 specifies a few |
| 40 |
surprising results for comparisons, such as |
| 41 |
|
| 42 |
(int) -3 < (unsigned long) 7 => false |
| 43 |
(int) -3 < (unsigned int) 7 => false |
| 44 |
and on 32-bit machines: |
| 45 |
(long) -3 < (unsigned int) 7 => false |
| 46 |
|
| 47 |
This is surprising because the natural comparison order is by |
| 48 |
value in the realm of infinite-precision signed integers (ℤ). |
| 49 |
|
| 50 |
The best way to get rid of such surprises is to use signed types |
| 51 |
for numerical integer values, and use unsigned types only for |
| 52 |
bit masks and enums. |
| 53 |
|
| 54 |
Why not use 'size_t' directly? |
| 55 |
|
| 56 |
* Because 'size_t' is an unsigned type, and a signed type is better. |
| 57 |
See above. |
| 58 |
|
| 59 |
Why not use 'ssize_t'? |
| 60 |
|
| 61 |
* 'ptrdiff_t' is more portable; it is standardized by ISO C |
| 62 |
whereas 'ssize_t' is standardized only by POSIX. |
| 63 |
|
| 64 |
* 'ssize_t' is not required to be as wide as 'size_t', and some |
| 65 |
now-obsolete POSIX platforms had 'size_t' wider than 'ssize_t'. |
| 66 |
|
| 67 |
* Conversely, some now-obsolete platforms had 'ptrdiff_t' wider |
| 68 |
than 'size_t', which can be a win and conforms to POSIX. |
| 69 |
|
| 70 |
Won't this cause a problem with objects larger than PTRDIFF_MAX? |
| 71 |
|
| 72 |
* Typical modern or large platforms do not allocate such objects, |
| 73 |
so this is not much of a problem in practice; for example, you |
| 74 |
can safely write 'idx_t len = strlen (s);'. To port to older |
| 75 |
small platforms where allocations larger than PTRDIFF_MAX could |
| 76 |
in theory be a problem, you can use Gnulib's ialloc module, or |
| 77 |
functions like ximalloc in Gnulib's xalloc module. |
| 78 |
|
| 79 |
Why not use 'ptrdiff_t' directly? |
| 80 |
|
| 81 |
* Maintainability: When reading and modifying code, it helps to know that |
| 82 |
a certain variable cannot have negative values. For example, when you |
| 83 |
have a loop |
| 84 |
|
| 85 |
int n = ...; |
| 86 |
for (int i = 0; i < n; i++) ... |
| 87 |
|
| 88 |
or |
| 89 |
|
| 90 |
ptrdiff_t n = ...; |
| 91 |
for (ptrdiff_t i = 0; i < n; i++) ... |
| 92 |
|
| 93 |
you have to ask yourself "what if n < 0?". Whereas in |
| 94 |
|
| 95 |
idx_t n = ...; |
| 96 |
for (idx_t i = 0; i < n; i++) ... |
| 97 |
|
| 98 |
you know that this case cannot happen. |
| 99 |
|
| 100 |
Similarly, when a programmer writes |
| 101 |
|
| 102 |
idx_t = ptr2 - ptr1; |
| 103 |
|
| 104 |
there is an implied assertion that ptr1 and ptr2 point into the same |
| 105 |
object and that ptr1 <= ptr2. |
| 106 |
|
| 107 |
* Being future-proof: In the future, range types (integers which are |
| 108 |
constrained to a certain range of values) may be added to C compilers |
| 109 |
or to the C standard. Several programming languages (Ada, Haskell, |
| 110 |
Common Lisp, Pascal) already have range types. Such range types may |
| 111 |
help producing good code and good warnings. The type 'idx_t' could |
| 112 |
then be typedef'ed to a range type that is signed after promotion. */ |
| 113 |
|
| 114 |
#ifdef __cplusplus |
| 115 |
extern "C" { |
| 116 |
#endif |
| 117 |
|
| 118 |
|
| 119 |
/* In the future, idx_t could be typedef'ed to a signed range type. |
| 120 |
The clang "extended integer types", supported in Clang 11 or newer |
| 121 |
<https://clang.llvm.org/docs/LanguageExtensions.html#extended-integer-types>, |
| 122 |
are a special case of range types. However, these types don't support binary |
| 123 |
operators with plain integer types (e.g. expressions such as x > 1). |
| 124 |
Therefore, they don't behave like signed types (and not like unsigned types |
| 125 |
either). So, we cannot use them here. */ |
| 126 |
|
| 127 |
/* Use the signed type 'ptrdiff_t'. */ |
| 128 |
/* Note: ISO C does not mandate that 'size_t' and 'ptrdiff_t' have the same |
| 129 |
size, but it is so on all platforms we have seen since 1990. */ |
| 130 |
typedef ptrdiff_t idx_t; |
| 131 |
|
| 132 |
/* IDX_MAX is the maximum value of an idx_t. */ |
| 133 |
#define IDX_MAX PTRDIFF_MAX |
| 134 |
|
| 135 |
/* So far no need has been found for an IDX_WIDTH macro. |
| 136 |
Perhaps there should be another macro IDX_VALUE_BITS that does not |
| 137 |
count the sign bit and is therefore one less than PTRDIFF_WIDTH. */ |
| 138 |
|
| 139 |
|
| 140 |
#ifdef __cplusplus |
| 141 |
} |
| 142 |
#endif |
| 143 |
|
| 144 |
#endif /* _IDX_H */ |