A Proposal to add wide

Green lines are notes for the editor or for the SG6/LEWG/LWG that must not be treated as part of the wording.

I. Introduction and Motivation

Current standard provides signed and unsigned int8_t, int16_t, int32_t, int64_t. It is usually enough for every day tasks, but sometimes appears a need in big numbers: for cryptography, IPv6, very big counters etc. Non-standard type __int128 which is provided by gcc and clang illuminates this need. But there is no cross-platform solution and no way to satisfy future needs in even more big numbers.

II. Changelog

III. Design and paper limitations

wide_integer is designed to be as close as possible to built-in integral types:

wide_integer is not a metafunction. Such metafunctions are discussed in P0102R0.

wide_integer does not add noexcept to operations that have UB for built-in types. Operations that have UB traditionally are not marked with noexcept by LWG. Attempt to change that behavior may be done in separate paper.

In this proposal we concentrate on the wide_integer class that uses machine words under the cover. Such implementations allow you to get best performance and leave behind some design questions, like "Is (sizeof(wide_integer<X>) == X / CHAR_BITS) or not?".

However, we do not wish to shut the door close for extending the abilities of the wide_integer class. Some users may wish to see unit40_t, or unit48_t.

We insist on interface that allows specifying integers not representable by machine words count. Such extensions of functionality may be discussed in separate papers.

wide_integer mimics the behavior of int. Because of that wide_int<128> * wide_int<128> results in wide_int<128>, not wide_int<256>. There are separate proposals for integers that are elastic (P0828R0) or safe (P0228R0).

Non template aliases for integers of particular width (for example int128_t) are handled in separate paper P0102R0. There was an implicit request from LEWG to remove those aliases from this paper, as they were rising a lot of questions on some platforms.

Interoperability with other arithmetic types was moved to a separate paper P0880R0.

We double checked that constexpr on default constructor does not require zero initialization in non constexpr contexts and still allows zero initialization if explicitly asked:

int main() {
     //constexpr wide_integer<128, unsigned> wi;   // Not initialized in constexpr context - compile time error
     wide_integer<128, unsigned> wi_no_init;       // Not initialized - OK
     constexpr wide_integer<128, unsigned> wi{};   // Zero initialized - OK
}

Current revision of the paper mimics behavior of int even in cases that are considered dangerous. It is possible to make wide_integer type more safe by making explicit:

Conversion from any signed to any unsigned type.
Narrowing conversions.
Conversion to and from floating point types.
Conversion to bool.

Such change will break the compatibility of wide_integer and int. Consider the case, when you have some template function foo(Arithmetic a) that works with arithmetic types. Function is huge and it was developed a long time ago. If interface of wide_integer is same as the interface of int then foo() could work with it. But if we make some of the conversions explicit, then foo() function must be adjusted.

Also note that adding explicit would affect only wide_integers, while there could be a better solution for all the integral types. For example all the integrals could be fixed by some safe_integer<Integral> class, that is very explicit and does additional checks on demand. In that case adding restrictions into wide_integer would just break the interface compatibility with int without big benefit.

IV. Proposed wording

[Note:

Here and below we rely on Arithmetic and Integral that are defined in P0880 in [numeric.requirements] as:

Functions that accept template parameters starting with Arithmetic shall not participate in overload resolution unless std::numeric_limits<Arithmetic>::is_specialized is true.

Functions that accept template parameters starting with Integral shall not participate in overload resolution unless std::numeric_limits<Integral>::is_integer is true.

- end note]

18.3.4 Class template numeric_limits[numeric.limits]

[Note to editor: Add the following sentence after the sentence "Specializations shall be provided for each arithmetic type, both floating-point and integer, including bool." (first sentence in fourth paragraph in [numeric.limits]) - end note]

Specializations shall be also provided for wide_integer type. [Note: If there is a built-in integral type Integral that has the same signedness and width as wide_integer<Bits, S>, then numeric_limits<wide_integer<Bits, S>> specialized in the same way as numeric_limits<Integral>- end note]

26.??.1 Header <wide_integer> synopsis[numeric.wide_integer.syn]

[Note: P0102R0 proposal with exact_2int, fast_2int, least_2int, exact_2uint, fast_2uint, least_2uint requires additional specializations for wide_integer. - end note]

The header <wide_integer> defines class template wide_integer and a set of operators for representing and manipulating integers of specified width.

26.??.2 Template class wide_integer overview[numeric.wide_integer.overview]

The class template wide_integer<size_t Bits, typename S> is a trivial standard layout class that behaves as an integer type of a compile time specified bitness.

Template parameter Bits specifies exact bits count to store the integer value. Bits % (sizeof(int) * CHAR_BITS) is eqaul to 0. sizeof(wide_integer<Bits, unsigned>) and sizeof(wide_integer<Bits, signed>) are required to be equal to Bits * CHAR_BITS.

When size of wide_integer is equal to a size of builtin integral type then the alignment and layout of that wide_integer is equal to the alignment and layout of the builtin type.

Template parameter S specifies signedness of the stored integer value and is either signed or unsigned.

Implementations are permitted to add explicit conversion operators and explicit or implicit constructors for Arithmetic and for Integral types.

[Example:

    template <class Arithmetic>
        [[deprecated("Implicit conversions to builtin arithmetic types are not safe!")]]
    constexpr operator Arithmetic() const noexcept;

    explicit constexpr operator bool() const noexcept;
    explicit constexpr operator int() const noexcept;
    ...

— end example ]

26.??.2.?? wide_integer constructors [numeric.wide_integer.cons]

26.??.2.?? wide_integer assignments [numeric.wide_integer.assign]

26.??.2.?? wide_integer compound assignments [numeric.wide_integer.cassign]

26.??.2.?? wide_integer observers [numeric.wide_integer.observers]

Returns: If Arithmetic type is an integral type then it is constructed from *this using the integral conversion rules [conv.integral]. Otherwise Arithmetic is constructed from *this using the floating-integral conversion rules [conv.fpint].

constexpr explicit operator bool() const noexcept;

Returns: true if *this is not equal to 0.

Returns: If is_integral_v<Arithmetic> then Arithmetic is constructed from *this using the integral conversion rules [conv.integral]. If is_floating_point_v<Arithmetic>, then Arithmetic is constructed from *this using the floating-integral conversion rules [conv.fpint]. Otherwise the operator shall not participate in overload resolution.

26.??.?? Specializations of common_type [numeric.wide_integer.traits.specializations]

[Note: common_type follows the usual arithmetic conversions design. - end note]

[Note: common_type attempts to follow the usual arithmetic conversions design here for interoperability between different numeric types. Following two specializations must be moved to a more generic place and enriched with usual arithmetic conversion rules for all the other numeric classes that specialize std::numeric_limits- end note]

26.??.?? Unary operators [numeric.wide_integer.unary_ops]

26.??.?? Binary operators [numeric.wide_integer.binary_ops]

In the function descriptions that follow, CT represents common_type_t<A, B>, where A and B are the types of the two arguments to the function.

26.??.?? Numeric conversions [numeric.wide_integer.conversions]

template <size_t Bits, typename S>
to_chars_result to_chars(char* first,
                       char* last,
                       const wide_integer<Bits, S>& value,
                       int base = 10);

Behavior of wide_integer overload is subject to the usual rules of primitive numeric output conversion functions [utility.to.chars].

template <size_t Bits, typename S>
from_chars_result from_chars(const char* first,
                           const char* last,
                           wide_integer<Bits, S>& value,
                           int base = 10);

Behavior of wide_integer overload is subject to the usual rules of primitive numeric input conversion functions [utility.from.chars].

26.??.?? iostream specializations [numeric.wide_integer.io]

26.??.?? Hash support [numeric.wide_integer.hash]

The specialization is enabled (20.14.14). If there is a built-in integral type Integral that has the same typename and width as wide_integer<Bits, S>, and wi is an object of type wide_integer<Bits, S>, then hash<wide_integer<MachineWords, S>>()(wi) == hash<Integral>()(Integral(wi)).

V. Feature-testing macro

For the purposes of SG10 we recommend the feature-testing macro name __cpp_lib_wide_integer.

VI. Acknowledgements

Many thanks to Alex Strelnikov and John McFarlane for sharing useful ideas and thoughts.

A Proposal to add wide_int Template Class