std::to_signed and std::to_unsigned

Contents

1. Revision history

1.1. Changes since R4

• added §4.2. Handling of enumeration types
• changed return type to avoid direct use of std::make_signed and std::make_unsigned

1.2. Changes since R3

• added §4.3. Naming
• added std::popcount(std::to_unsigned(123)) as motivation in §2. Introduction
• added §4.4. Saturating, checked, etc. variants (or lack thereof)

1.3. Changes since R2

• updated GitHub code search result count in §2.1. Existing developer practice
• added §2.2. Rust cast_signed and cast_unsigned
• rebased §6. Wording on [N5054]

1.4. Changes since R1

• ported proposal from Bikeshed to COWEL
• added §2.3. Dual purpose
• reordered §4. Design and §5. Possible implementation
• added discussion on constraints in §4. Design
• fixed typo in §6. Wording: x value

1.5. Changes since R0

• tightened constraints in §6. Wording to exclude cv-qualified types in general, not just cv bool
• added freestanding comment to feature-test macro

2. Introduction

In integer numerics and bit-manipulation code, it is common to implement functionality in terms of the corresponding signed/unsigned type:

This technique technically works, but suffers from some problems:

• The use of C-style/function-style casts may conflict with the project's style. When static_cast is used instead, this code becomes substantially more verbose.
• Since T has to be spelled out in code, abbreviated function templates cannot be used instead (or at least, decltype(x) would be required for the cast).
• Repeating the type T may be prone to mistakes. Nothing guarantees us that T is of type T when writing an expression std::make_signed_t<T>(x). In larger code samples, mismatching types and variables is a bug waiting to happen. To be safe, we would have to write std::make_signed_t<decltype(x)>(x). However, this still repeats the expression x.

The greater the distance between T and the use of std::make_{un}signed, the easier it is to make a mistake.

Another problem is that sometimes APIs are made usable only with unsigned integers, such as functions in the <bit> header (but this hurdle extends far beyond the standard library). Such APIs could often be used meaningfully with signed integers, which makes the restriction somewhat arbitrary. std::to_unsigned can make them usable, like in std::popcount(std::to_unsigned(123)).

To solve these issues, this proposal adds the function templates std::to_signed(x) and std::to_unsigned(x), which deduce T from x. This is concise and always uses the correct type.

2.1. Existing developer practice

A GitHub code search for

/[^a-zA-Z_](to_signed|to_unsigned)|static_cast<(typename)? ?((::)?std::)?(make_signed|make_unsigned)/
-is:fork language:c++

… shows that roughly 115K C++ files already use a non-standard to_unsigned and to_signed, or which static_cast to make_signed or make_unsigned.

By comparison,

/[^a-zA-Z_](to_underlying)|static_cast<(typename)? ?((::)?std::)?(underlying_type)/
-is:fork language:c++

… yields 165K C++ files that use to_underlying, or use static_cast with std::underlying_type.

The proposal [P1682R3] for std::to_underlying had similar rationale, and at the time, the author was only able to discover 1000 search results for to_underlying.

2.2. Rust cast_signed and cast_unsigned

As a point of reference, Rust also has cast_signed and cast_unsigned functions for integers. See also tracking issue for integer_sign_cast.

The problem statement in the libs-team issue applies equally to C++:

Casting using the as operator has some issues, in that it does not necessarily reflect the intent of the cast. Was the cast meant to be lossy or not? Was it meant to preserve the size? Constness? Signedness?

Similarly, a static_cast<std::int32_t>(x) from std::uint32_t does not reflect the purpose, while std::to_signed(x) expresses the intent of give me the same size and value, but reinterpreted as a signed type.

A GitHub code search for

/\bcast_(un)signed\b/ -is:fork/-is:fork language:rust

… shows roughly 5.1K Rust files.

2.3. Dual purpose

In addition to the purpose of changing signedness of integers, the proposed functions have another purpose: mapping other integral and enumeration types onto signed or unsigned integer types.

Just like make_signed and make_unsigned, to_signed and to_unsigned map the much larger set of integral types onto the smaller set of signed and unsigned integer types. This reduces template instantiations and may improve compilation speed and reduce code size.

3. Impact on the standard

This proposal is a pure library extension.

4. Design

This proposal follows precedent: similar to to_underlying, the proposed functions are located in <utility>. The naming scheme is based on to_underlying and the search results in §2.1. Existing developer practice.

4.1. Constraints

The design of to_signed and to_unsigned should be SFINAE-friendly because that is useful.

As for the constraints of the proposed functions, there are multiple options:

• ❌ Only permit signed or unsigned integer types. This would be needlessly restrictive because, for example, make_signed<char16_t> is also valid (and yields e.g. signed short), which makes it possible to implement the arithmetic_shift_right function in §2. Introduction for char16_t as well. In general, it would make generic programming harder if only some of the integral types were supported.
• ✔️ Permit what make_signed supports. That is, integral or enumeration types other than bool. This is proposed. There is no compelling reason to deviate from the restrictions imposed by make_signed and make_unsigned, as their restrictions de facto define for which types a sign conversion makes sense.
• ❌ Permit integer-like types. This is out-of scope, and would effectively replace to-unsigned-like. Integer-like types are an open set of types, possibly including user-defined types. This effectively turns the proposed function into a customization point. Seeing that integer-like is a concept which only exists in [ranges], the proposed functions should then be std::ranges::to_signed and std::ranges::to_unsigned. However, the goal of the proposal is to provide a simple numerical function, not add a ranges-specific customization point object.
• ❌ Permit arithmetic types. This would mirror std::is_signed_v, which is also true for floating-point types. This would create a weird asymmetry, where to_signed(float) is a no-op, and to_unsigned(float) is ill-formed. The result of the proposed functions is always a signed or unsigned integer type, and permitting float would muddy the waters here.

4.2. Handling of enumeration types

As mentioned above, anything accepted by std::make_signed is also accepted by std::to_signed, including enumeration types.

However, std::make_signed and std::make_unsigned shouldn't be used directly as the return type because they have long-standing design issues. std::make_unsigned surprisingly does not yield the underlying type of an enumeration type (or the unsigned counterpart thereof), but yields ([meta.trans.sign]):

the unsigned integer type with smallest rank ([conv.rank]) for which sizeof(T) == sizeof(type), with the same cv-qualifiers as T.

A simple workaround is to use use std::make_unsigned_t<std::underlying_type_t<E>> for enumeration types.

4.3. Naming

As explained above, the proposed function is inspired by std::to_underlying, so the names std::to_signed and std::to_unsigned continue that existing naming scheme. That is, the word to generally implies a conversion in the standard library, possibly including value-changing conversions (as compared to as like in std::as_const, which indicates lossless conversions).

The name std::to_signed is consistent with the rest of the library in another way: all std::to_* functions are wrappers for a static_cast (where std::to_underlying and std::to_integer convert to the underlying type).

4.3.1. Possible criticism of naming

A possible counter-argument to the proposed names is that they don't make it readily apparent that wrapping takes place (e.g. std::to_unsigned(-1) yields UINT_MAX), as compared to a name like std::wrap_to_unsigned or std::wrapping_to_unsigned. However, the same could be said about all sorts of existing features that perform wrapping without expressing that in the name:

• implicit conversions between int and unsigned are wrapping
• aliasing int objects via reinterpret_cast<unsigned*> is wrapping
• static_cast<unsigned>(-1) is wrapping
• std::bit_cast<unsigned>(-1) is wrapping
• anything equivalent to a static_cast (C-style cast, functional cast) is wrapping

std::to_unsigned(-1) does the same as unsigned(-1). Neither notation advertises that wrapping takes place, but the behavior is consistent and intuitive. There is also only one plausible default interpretation of convert to unsigned in C++, which is what all of these operations are doing, although not every user is familiar enough with the language to arrive at that conclusion, so admittedly, some users won't intuit that std::to_unsigned wraps. Still, as long as the behavior doesn't deviate from the norm by being e.g. saturating or throwing, it shouldn't need explicit clarification.

Another counter-argument is that std::to_underlying and std::to_integer are value-preserving since they simply convert to the underlying type, so a user may have a false expectation of losslessness toward std::to_signed and std::to_unsigned.

4.4. Saturating, checked, etc. variants (or lack thereof)

This proposal only adds the base operation, which is wrapping. It does not add any additional variants such as a checked, saturating, elastic, or other conversions. This has a number of reasons:

• Saturating and checked conversions don't make much design sense. Remember that the proposed functions deliberately don't require the user to specify the target width; it is deduced from the input. It makes very little sense to combine this with checked or saturating forms where an exception is thrown or the value is clamped when it falls outside a specific range. We would be combining a don't care about range operation with a care a lot about range form.
• Most of these forms don't exist in the C++ standard yet and should be explored holistically. For example:
  • If we wanted std::checked_to_signed (whatever the check does), we should explore std::checked_add and std::checked_mul to make a coherent library, similar to saturation arithmetic.
  • If we wanted a std::elastic_to_signed operation (which when given an unsigned operand, returns some wider signed type so the conversion is lossless), we should explore std::elastic_add and std::elastic_mul.

    It is unclear what a std::elastic_to_unsigned operation would do, given that unsigned types cannot represent negative values no matter how wide. This asymmetry and the overall lack of precedent in the standard library and core language makes elastic semantics particularly unsuitable for the base std::to_signed and std::to_unsigned operations.

  These checked, elastic, and other unprecedented variants are out of scope for this paper.
• The one form that may be worth exploring is std::saturating_to_signed, but as explained above, it makes little sense.
• Deployment experience from Rust shows that there is virtually no user interest in such variants. A GitHub code search for the nightly-only integer_cast_extras functions, i.e. for language:rust /(checked|saturating|strict)_cast_(un)?signed/ -is:fork yields only 30 results at the time of writing, of which almost all
  • are in comments,
  • are part of the crate/standard library implementation (which is not user demand),
  • act as pieces of a larger operation like a normal checked cast (making them arguably obsolete when such a combined operation exists), or
  • do two saturating conversions in a row (which is an anti-pattern and obsolete when std::saturating_cast exists).
  In short, the microscopic (being generous) user base is not making good use of these functions.

  One could argue that these functions are recent and unstable, so it is too early to judge, but genuinely useful numeric functions like std::bit_compress already acquired 1000K GitHub uses (from people independently implementing/copying pasting it), while libc++ and libstdc++ haven't released this feature yet.

That being said, nothing precludes adding more variants in the future, just like we could always add a std::checked_gcd or std::saturating_bit_ceil. It's just not needed in this paper.

5. Possible implementation

6. Wording

The proposed wording is relative to [N5054].

In subclause [version.syn], add the following feature-testing macro:

In subclause [utility.syn], change the synopsis as follows:

In subclause [utility], add a subclause immediately prior to [utility.underlying]:

7. Acknowledgements

Thanks to Dalton Messmer for reviewing R1 of this paper, leaving thoughtful comments that contributed to an improved R2 which discusses many design aspects in more detail.

Thanks to Oliver Rosten and to BSI for providing extensive feedback on R3 of this paper, which resulted in improvements to the design discussion.

8. References