std::to_signed and std::to_unsigned

Contents

1. Revision history

1.1. 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.2. 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.3. 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 are, the easier it is to make a mistake.

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 which use to_underlying, or which static_cast to 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 on the libs-team issue equally applies 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 e.g. 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 that 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 from deviating 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.

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.

8. References