std::remquo, std::remquof, std::remquol

Определено в заголовочном файле `<cmath>`
float remquo ( float x, float y, int* quo ); double remquo ( double x, double y, int* quo ); long double remquo ( long double x, long double y, int* quo );	(1)	(начиная с C++11) (до C++23)
constexpr /* floating-point-type / remquo ( / floating-point-type / x, / floating-point-type / y, int quo );	(1)		(начиная с C++23)
float remquof( float x, float y, int* quo );	(2)	(начиная с C++11) (constexpr начиная с C++23)
long double remquol( long double x, long double y, int* quo );	(3)	(начиная с C++11) (constexpr начиная с C++23)
Дополнительные перегрузки
Определено в заголовочном файле `<cmath>`
template< class Arithmetic1, class Arithmetic2 > /* common-floating-point-type / remquo( Arithmetic1 x, Arithmetic2 y, int quo );	(A)	(начиная с C++11) (constexpr начиная с C++23)

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

A) Предоставляются дополнительные перегрузки для всех остальных комбинаций арифметических типов.

Параметры

x, y	-	значения с плавающей точкой или целочисленные значения
quo	-	указатель на int для сохранения знака и некоторых битов `x / y`

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

В случае успеха возвращает остаток от деления чисел с плавающей точкой x / y, определённый в std::remainder, и сохраняет в *quo знак и как минимум три младших значащих бита x / y (формально сохраняет значение, знак которого совпадает со знаком x / y, а величина сравнима по модулю 2ⁿ с величиной целой части частного x / y, где n — целое число, определяемое реализацией, большее или равное 3).

Если y равно нулю, сохранённое в *quo значение не определено.

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

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

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

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

Об ошибках сообщается в соответствии с math_errhandling.

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

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

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

Примечания

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

Эта функция полезна при реализации периодических функций с периодом, точно представимым в виде числа с плавающей точкой: при вычислении sin(πx) для очень большого x прямой вызов std::sin может привести к большой погрешности. Однако если сначала выполнить редукцию аргумента функции с помощью std::remquo, младшие биты частного можно использовать для определения знака и октанта результата в пределах периода, а остаток — для вычисления значения с высокой точностью.

На некоторых платформах эта операция поддерживается аппаратно (например, на процессорах Intel после завершения FPREM1 в частном остаются ровно 3 бита точности).

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

Если num1 или num2 имеет тип longdouble, то std::remquo(num1, num2, quo) действует так же, как std::remquo(static_cast<long double>(num1),static_cast<long double>(num2), quo).
Иначе, если num1 и/или num2 имеет тип double или целочисленный тип, то std::remquo(num1, num2, quo) действует так же, как std::remquo(static_cast<double>(num1),static_cast<double>(num2), quo).
Иначе, если num1 или num2 имеет тип float, то std::remquo(num1, num2, quo) действует так же, как std::remquo(static_cast<float>(num1),static_cast<float>(num2), quo).

(до C++23)

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

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

(начиная с C++23)

Пример

#include <cfenv>
#include <cmath>
#include <iostream>

#ifndef __GNUC__
#pragma STDC FENV_ACCESS ON
#endif

const double pi = std::acos(-1); // or std::numbers::pi since C++20

double cos_pi_x_naive(double x)
{
    return std::cos(pi * x);
}

// the period is 2, values are (0;0.5) positive, (0.5;1.5) negative, (1.5,2) positive
double cos_pi_x_smart(double x)
{
    int quadrant;
    double rem = std::remquo(x, 1, &quadrant);
    quadrant = static_cast<unsigned>(quadrant) % 2; // The period is 2.
    return quadrant == 0 ?  std::cos(pi * rem)
                         : -std::cos(pi * rem);
}

int main()
{
    std::cout << std::showpos
              << "naive:\n"
              << "  cos(pi * 0.25) = " << cos_pi_x_naive(0.25) << '\n'
              << "  cos(pi * 1.25) = " << cos_pi_x_naive(1.25) << '\n'
              << "  cos(pi * 2.25) = " << cos_pi_x_naive(2.25) << '\n'
              << "smart:\n"
              << "  cos(pi * 0.25) = " << cos_pi_x_smart(0.25) << '\n'
              << "  cos(pi * 1.25) = " << cos_pi_x_smart(1.25) << '\n'
              << "  cos(pi * 2.25) = " << cos_pi_x_smart(2.25) << '\n'
              << "naive:\n"
              << "  cos(pi * 1000000000000.25) = "
              << cos_pi_x_naive(1000000000000.25) << '\n'
              << "  cos(pi * 1000000000001.25) = "
              << cos_pi_x_naive(1000000000001.25) << '\n'
              << "smart:\n"
              << "  cos(pi * 1000000000000.25) = "
              << cos_pi_x_smart(1000000000000.25) << '\n'
              << "  cos(pi * 1000000000001.25) = "
              << cos_pi_x_smart(1000000000001.25) << '\n';
    
    // error handling
    std::feclearexcept(FE_ALL_EXCEPT);
    
    int quo;
    std::cout << "remquo(+Inf, 1) = " << std::remquo(INFINITY, 1, &quo) << '\n';
    if (fetestexcept(FE_INVALID))
        std::cout << "  FE_INVALID raised\n";
}

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

naive:
  cos(pi * 0.25) = +0.707107
  cos(pi * 1.25) = -0.707107
  cos(pi * 2.25) = +0.707107
smart:
  cos(pi * 0.25) = +0.707107
  cos(pi * 1.25) = -0.707107
  cos(pi * 2.25) = +0.707107
naive:
  cos(pi * 1000000000000.25) = +0.707123
  cos(pi * 1000000000001.25) = -0.707117
smart:
  cos(pi * 1000000000000.25) = +0.707107
  cos(pi * 1000000000001.25) = -0.707107
remquo(+Inf, 1) = -nan
  FE_INVALID raised

См. также

div(int)ldivlldiv (C++11)	вычисляет частное и остаток от целочисленного деления (функция)
fmodfmodffmodl (C++11)(C++11)	остаток от деления чисел с плавающей точкой (функция)
remainderremainderfremainderl (C++11)(C++11)(C++11)	знаковый остаток от деления (функция)
Документация C для `remquo`

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