std::remainder, std::remainderf, std::remainderl

Определено в заголовке `<cmath>`
	(1)
float remainder ( float x, float y ); double remainder ( double x, double y ); long double remainder ( long double x, long double y );		(до C++23)
constexpr /* floating-point-type / remainder ( / floating-point-type / x, / floating-point-type */ y );		(с C++23)
float remainderf( float x, float y );	(2)	(с C++11) (constexpr с C++23)
long double remainderl( long double x, long double y );	(3)	(с C++11) (constexpr с C++23)
Дополнительные перегрузки (с C++11)
Определено в заголовке `<cmath>`
template< class Integer > double remainder ( Integer x, Integer y );	(A)	(constexpr с C++23)

1-3) Вычисляет остаток от деления с плавающей запятой по IEEE x / y. Библиотека предоставляет перегрузки std::remainder для всех типов с плавающей запятой без квалификаторов cv в качестве типа параметров.(с C++23)

A) Дополнительные перегрузки предоставляются для всех целочисленных типов, которые рассматриваются как double.

(с C++11)

IEEE остаток от деления x / y, вычисленный этой функцией, равен точному значению x - quo * y, где значение quo — целое значение, ближайшее к точному значению x / y. При |quo - x / y| = ½, значение quo выбирается чётным.

В отличие от std::fmod, возвращаемое значение не гарантируется, что будет иметь тот же знак, что и x.

Если возвращаемое значение равно нулю, оно будет иметь тот же знак, что и x.

Параметры

x, y

значения с плавающей запятой или целочисленные значения

Возвращаемое значение

При успехе возвращает IEEE остаток от деления x / y как определено выше.

В случае возникновения ошибки области, возвращается значение, определённое реализацией (NaN, если поддерживается).

Если возникает ошибка диапазона из-за подтекания, возвращается правильное значение.

Если y равно нулю, но ошибка области не возникает, возвращается ноль.

Обработка ошибок

Ошибки сообщаются в соответствии со спецификацией math_errhandling.

Ошибка области может возникнуть, если y равно нулю.

Если реализация поддерживает IEEE арифметику с плавающей запятой (IEC 60559),

Текущий режим округления не оказывает влияния.
FE_INEXACT никогда не генерируется, результат всегда точен.
Если x — ±∞, и y не NaN, возвращается NaN, и FE_INVALID генерируется.
Если y — ±0, и x не NaN, возвращается NaN, и FE_INVALID генерируется.
Если любой из аргументов — NaN, возвращается NaN.

Примечания

POSIX требует, чтобы ошибка области возникала, если x бесконечно или y равно нулю.

std::fmod, но не std::remainder полезно для безмолвной обёртки типов с плавающей запятой в беззнаковые целочисленные типы: (0.0 <= (y = std::fmod(std::rint(x), 65536.0)) ? y : 65536.0 + y) находится в диапазоне [-0.0, 65535.0], что соответствует unsigned short, но std::remainder(std::rint(x), 65536.0) находится в диапазоне [-32767.0, +32768.0], что выходит за пределы диапазона signed short.

Дополнительные перегрузки не обязаны предоставляться точно как (A). Они должны быть достаточны, чтобы гарантировать, что для первого аргумента num1 и второго аргумента num2:

Если num1 или num2 имеет тип long double, то std::remainder(num1, num2) имеет тот же эффект, что и std::remainder(static_cast<long double>(num1), static_cast<long double>(num2)).
В противном случае, если num1 и/или num2 имеет тип double или целочисленный тип, то std::remainder(num1, num2) имеет тот же эффект, что и std::remainder(static_cast<double>(num1), static_cast<double>(num2)).
В противном случае, если num1 или num2 имеет тип float, то std::remainder(num1, num2) имеет тот же эффект, что и std::remainder(static_cast<float>(num1), static_cast<float>(num2)).

(до C++23)

Если num1 и num2 имеют типы арифметических типов, то std::remainder(num1, num2) имеет тот же эффект, что и std::remainder(static_cast</* common-floating-point-type */>(num1), static_cast</* common-floating-point-type */>(num2)), где /* common-floating-point-type */ — тип с плавающей запятой с наибольшим рангом преобразования с плавающей запятой и наибольшим подрангом преобразования с плавающей запятой между типами num1 и num2, аргументы целочисленного типа рассматриваются как имеющие тот же ранг преобразования с плавающей запятой, что и double.

Если такой тип с плавающей запятой с наибольшим рангом и подрангом не существует, тогда разрешение перегрузок не приводит к использованию кандидата из предоставленных перегрузок.

(с C++23)

Пример

#include <cfenv>
#include <cmath>
#include <iostream>
// #pragma STDC FENV_ACCESS ON
 
int main()
{
    std::cout << "remainder(+5.1, +3.0) = " << std::remainder(5.1, 3) << '\n'
              << "remainder(-5.1, +3.0) = " << std::remainder(-5.1, 3) << '\n'
              << "remainder(+5.1, -3.0) = " << std::remainder(5.1, -3) << '\n'
              << "remainder(-5.1, -3.0) = " << std::remainder(-5.1, -3) << '\n';
 
    // special values
    std::cout << "remainder(-0.0, 1.0) = " << std::remainder(-0.0, 1) << '\n'
              << "remainder(5.1, Inf) = " << std::remainder(5.1, INFINITY) << '\n';
 
    // error handling
    std::feclearexcept(FE_ALL_EXCEPT);
    std::cout << "remainder(+5.1, 0) = " << std::remainder(5.1, 0) << '\n';
    if (fetestexcept(FE_INVALID))
        std::cout << "    FE_INVALID raised\n";
}

Возможный вывод:

remainder(+5.1, +3.0) = -0.9
remainder(-5.1, +3.0) = 0.9
remainder(+5.1, -3.0) = -0.9
remainder(-5.1, -3.0) = 0.9
remainder(-0.0, 1.0) = -0
remainder(5.1, Inf) = 5.1
remainder(+5.1, 0) = -nan
    FE_INVALID raised

См. также

div(int)ldivlldiv (C++11)	вычисляет частное и остаток от целочисленного деления (функция)
fmodfmodffmodl (C++11)(C++11)	остаток от деления с плавающей запятой (функция)
remquoremquofremquol (C++11)(C++11)(C++11)	остаток от деления со знаком, а также три последних бита от деления (функция)
Документация C для `remainder`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/numeric/math/remainder