target

integration into IS ISO/IEC 9899:202y

document history

C document ID: C4172

polls

• Would WG14 like to adopt something along the lines of N3543 for integer types into C2y?
  • 22-0-6: clear direction
• Do we want to adopt something along the lines of N3762 using stdint.h into C2y?
  • 10-3-6: strong direction in favor

1 Introduction

Generic features to compute minimum and maximum value of two given integer values is notoriously challenging in C. The difficulties with such features are as follows

• Implicit conversion of signed and unsigned types have it that the necessary comparison already may go the wrong way
• Determination of a correct type for the minimum between a signed and an unsigned value is not completely trivial.
• Naïve use of macros lead to multiple evaluations of macro parameters, including their side effects.

Previous revisions of this paper also discussed versions of these macros that would result in integer constant expressions if the arguments are so. This aspect did not find as wide approval as the feature in general, so we drop this idea for now. In can be added later without problems.

2 Approach

We propose to add type-generic macros that solve all these problems for all integer value and type combinations. Namely:

• Compare values numerically, without consideration of type
• Choose a type that is able to represent the result for all possible combinations of argument values.

In particular, if one type is signed and the other is unsigned, we have to ensure that the result type can hold the result and that no sign conversion occurs when converting to the result type.

• The macro stdc_min chooses the signed type for the result. This choice is motivated as follows:

  • If the signed value is negative, it is automatically the minimum value of the two.
  • If the signed value s is 0 or positive, the other value u may only hold the minimum if u ≤ s and thus then u ≤ SMAX where SMAX is the maximum value of the signed type.

  Thus the signed type is always able to hold the result of the minimum operation.

• The macro stdc_max chooses the common real type for the result. This choice is motivated as follows:

  • If the signed value is negative, it is never the maximum value of the two.
  • If the signed value s is 0 or positive, no sign conversion is necessary.

  Thus no sign conversion is necessary to store the result in the common real type.

The proposed features have to be implemented side effect free (7.14) and thus, seen as function interfaces, they should be pure in the CS sense of the term. So, as we have already have done for the bit manipulation macros, for these new interfaces we add the [[unsequenced]] attribute.

After discussion in WG14, we propose to add the features to the <stdint.h> header in a subclause of their own.

The choice for the macro names is guided by the fact that the min and max identifiers are abundantly used in user code, not only for functions or macros that perform these operations, but also as variable names that store the respective minimum or maximum value in a given situation. The prefix stdc_, which is already reserved for identifiers with external linkage, seemed the most natural one: sufficiently short and unambiguous.

3 Implementations

Implementations of minimum and maximum macros or functions there are plenty. Even the current C standard provides a handful of slightly different interfaces for maximum macros and functions, but only for floating types. Then, in the field an abundant number of implementations of varying properties and quality are added to that picture.

The goal of this paper is to propose a unification to all these interfaces and their behavior, such that programmers find reliable implementations of these features in their C library.

The reference implementation that is available on the WG14 git (and that we are able to provide on request) is not meant to suggest any particular way in which these features should be implemented, but only to prove that an implementation is possible as of today with relatively small effort. Besides a lot of C23-only features, this reference implementation uses only the __COUNTER__ pseudo macro (which is accepted for inclusion into C2Y).

Our expectation is that compilers will provide buildins for these features and that the macros proposed here will then only serve as stubs to ensure standard conformance.

4 Suggested Wording

In 7.23, bump the value of __STDC_VERSION_STDINT_H__.

Then add a new clause

#include <stdint.h>
minType stdc_min(A a, B b) [[unsequenced]];
maxType stdc_max(A a, B b) [[unsequenced]];

#include <stdint.h>
unsigned long n = ULONG_MAX;

auto max1 = stdc_max(n, 0);          // (unsigned long)n
auto min1 = stdc_min(n, 0);          // (signed int)0

auto max2 = stdc_max(n, 0u);         // (unsigned long)n
auto min2 = stdc_min(n, 0u);         // (unsigned long)0

auto max3 = stdc_max(n, (char)0);    // (unsigned long)n
auto min3 = stdc_min(n, (char)0);    // (unsigned long)0 or (signed int)0

auto max4 = stdc_max(3wb, 7wbu);     // (unsigned _BitInt(3))7
auto min4 = stdc_min(3wb, 7wbu);     // (signed _BitInt(3))3

auto max5 = stdc_max(-1wb, 255wbu);  // (unsigned _BitInt(8))255
auto min5 = stdc_min(-1wb, 255wbu);  // (signed _BitInt(2))-1

auto max6 = stdc_max(-1wbu, 255wbu); // (unsigned _BitInt(8))255
auto min6 = stdc_min(-1wbu, 255wbu); // (unsigned _BitInt(8))1

Acknowledgment

I’d like to thank Aaron Ballman, Christoph Grüninger, Joseph Myers, Philipp Klaus Krause, and Robert Seacord for their suggestions.