Numeric Functions

Returns: A basic_big_int equal in magnitude to j and not less than 0.

Postconditions: For the lvalue overload, j is unchanged. For the rvalue overload, j is in a valid but unspecified state.

Throws: For the lvalue overload, any exception thrown while allocating the copied result (for example, std::bad_alloc); a magnitude held in the in-place buffer allocates nothing. The rvalue overload is noexcept.

Remarks: The function is usable in a constant expression. The result uses the allocator of j.

Constraints: R is a signed or unsigned integer type.

Returns: If the integer value of x is representable as a value of type R, that value; otherwise the largest or smallest value representable by R, whichever is closer to the value of x. In particular, a value greater than the maximum of R saturates to that maximum, a value less than the minimum saturates to the minimum, and every negative value yields 0 when R is unsigned.

Throws: Nothing; the function is noexcept.

Remarks: The function is usable in a constant expression. The bounds of R are derived from its width, so extended integer types and bit-precise integers (_BitInt) are supported even where they lack a std::numeric_limits specialization.

Constraints: R is a signed or unsigned integer type.

Returns: true if the value of x is in the range of values that can be represented in R, otherwise false.

Throws: Nothing; the function is noexcept.

Remarks: The function is usable in a constant expression. The bounds of R are derived from its width.

Constraints: One operand is a specialization of basic_big_int, and the other is either the same specialization or a signed or unsigned integer type. Whether the other operand is admissible follows from the return type, which is ill-formed otherwise, so bool, character types, floating-point types, and a second, unrelated basic_big_int specialization all drop gcd out of overload resolution rather than producing a hard error. Two built-in integers are the business of std::gcd, not of these overloads.

Returns: The greatest common divisor of |m| and |n|. The result is never negative. If both arguments are zero the result is zero; otherwise gcd(x, 0) is |x|.

Throws: Any exception thrown while allocating the result or the values the reduction works on (for example, std::bad_alloc). Arguments whose magnitudes both fit a single limb, and an argument pair where one magnitude fits a single limb, are computed without allocating at all — however wide the other operand is, since a borrowed operand is not copied unless the reduction needs a mutable value.

Remarks: The function is usable in a constant expression. The result uses the allocator of the basic_big_int argument. Unlike std::gcd, no argument can fail to be representable in the result type: basic_big_int is unbounded, so the precondition that std::gcd places on |m| and |n| is vacuous here. The operands are taken by forwarding reference and classified the way the binary operators classify theirs, so passing a basic_big_int as an rvalue hands its storage to the computation while an lvalue is left untouched. There are four overloads rather than one because every basic_big_int drags namespace std into argument-dependent lookup through its allocator: std::gcd is always a candidate, and spelling the big_int operand as a specialization — something `std::gcd’s plain type parameter cannot deduce — is what makes these the more specialized overloads, and an unqualified call unambiguous.

Constraints: The same as gcd's: one operand is a specialization of basic_big_int, and the other is either the same specialization or a signed or unsigned integer type. Anything else drops lcm out of overload resolution rather than producing a hard error, and two built-in integers are the business of std::lcm.

Returns: The least common multiple of |m| and |n|, which is the smallest non-negative value that both operands divide. The result is never negative. If either argument is zero the result is zero, since zero is then the only common multiple.

Throws: Any exception thrown while allocating the result or the value the computation works on (for example, std::bad_alloc). Arguments whose magnitudes both fit a single limb are computed without allocating at all when their least common multiple fits a limb as well, and a zero argument allocates nothing either way.

Remarks: The function is usable in a constant expression. The result uses the allocator of the basic_big_int argument, as gcd’s does. Unlike `std::lcm, neither the arguments nor the result can fail to be representable in the result type: basic_big_int is unbounded, so the preconditions std::lcm places on |m|, |n|, and the least common multiple itself are all vacuous here — which is the practical reason to reach for this overload set, since the least common multiple of two built-in integers overflows long before the operands do. The operands are taken by forwarding reference, so passing a basic_big_int as an rvalue hands its storage to the computation while an lvalue is left untouched. There are four overloads for the same reason gcd has four: std::lcm is a candidate of every unqualified call through argument-dependent lookup on the allocator, and only a parameter that its plain type parameter cannot deduce makes these the more specialized ones.

Constraints: The same as gcd's: one operand is a specialization of basic_big_int, and the other is either the same specialization or a signed or unsigned integer type. Anything else drops midpoint out of overload resolution rather than producing a hard error, and two built-in integers are the business of std::midpoint.

Returns: Half the sum of m and n. If the sum is odd, the result is rounded toward m. Equivalently, the result is m + (n - m) / 2 with the division truncated toward zero.

Throws: Any exception thrown while allocating the result or the value the arithmetic works on (for example, std::bad_alloc). Arguments whose magnitudes both fit a single limb are computed without allocating at all, whatever their signs, since the midpoint of two such values fits a limb as well.

Remarks: The function is usable in a constant expression. The result uses the allocator of the basic_big_int argument, as gcd’s and `lcm’s do. Unlike `std::midpoint, this function is not noexcept, because a wide result has to be allocated. The guarantee that no overflow occurs is unconditional for the same reason it is vacuous in gcd and lcm: basic_big_int is unbounded, so neither the sum of the operands nor the difference between them can fail to be representable — which is the practical reason to reach for this overload set, since std::midpoint has to work around exactly that hazard for built-in types. Only the second operand is taken over when it is passed as an rvalue; the first is read again after the halving, so it is left untouched either way. There are four overloads for the same reason gcd and lcm have four: std::midpoint is a candidate of every unqualified call through argument-dependent lookup on the allocator. Its own constraints admit only arithmetic types, so it drops out on its own for a basic_big_int argument, but spelling the big_int operand as a specialization is still what lets these overloads take the mixed operand pairs that `std::midpoint’s single type parameter cannot deduce.