std::hypot, std::hypotf, std::hypotl

Определено в заголовочном файле `<cmath>`
float hypot ( float x, float y ); double hypot ( double x, double y ); long double hypot ( long double x, long double y );	(1)	(начиная с C++11) (до C++23)
/floating-point-type/ hypot ( /floating-point-type/ x, /floating-point-type/ y );	(1)		(начиная с C++23) (constexpr начиная с C++26)
float hypotf( float x, float y );	(2)	(начиная с C++11) (constexpr начиная с C++26)
long double hypotl( long double x, long double y );	(3)	(начиная с C++11) (constexpr начиная с C++26)
float hypot ( float x, float y, float z ); double hypot ( double x, double y, double z ); long double hypot ( long double x, long double y, long double z );	(4)	(начиная с C++17) (до C++23)
/floating-point-type/ hypot ( /floating-point-type/ x, /floating-point-type/ y, /floating-point-type/ z );	(4)		(начиная с C++23) (constexpr начиная с C++26)
Дополнительные перегрузки
Определено в заголовочном файле `<cmath>`
template< class Arithmetic1, Arithmetic2 > /common-floating-point-type/ hypot ( Arithmetic1 x, Arithmetic2 y );	(A)	(начиная с C++11) (constexpr начиная с C++26)
template< class Arithmetic1, Arithmetic2, Arithmetic3 > /common-floating-point-type/ hypot ( Arithmetic1 x, Arithmetic2 y, Arithmetic3 z );	(B)	(начиная с C++17)

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

4) Вычисляет квадратный корень из суммы квадратов x, y и z, не допуская чрезмерного переполнения или потери значимости на промежуточных этапах вычисления.Библиотека предоставляет перегрузки std::hypot для всех типов с плавающей точкой без cv-квалификаторов в качестве типов параметров x, y и z.(начиная с C++23)

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

Значение, вычисляемое двухаргументной версией этой функции, является длиной гипотенузы прямоугольного треугольника с катетами длиной x и y, расстоянием от точки (x,y) до начала координат (0,0) или модулем комплексного числа x+iy.

Значение, вычисляемое трёхаргументной версией этой функции, является расстоянием от точки (x,y,z) до начала координат (0,0,0).

Параметры

x, y, z

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

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

1-3,A) Если ошибок не возникает, возвращается гипотенуза прямоугольного треугольника, \(\scriptsize{\sqrt{x^2+y^2} }\)√x²+y². 4,B) Если ошибок не возникает, возвращается расстояние от начала координат в трёхмерном пространстве, \(\scriptsize{\sqrt{x^2+y^2+z^2} }\)√x²+y²+z².

При ошибке диапазона, вызванной переполнением, возвращается +HUGE_VAL, +HUGE_VALF или +HUGE_VALL.

При ошибке диапазона, вызванной потерей значимости, возвращается правильный результат (после округления).

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

Об ошибках сообщается согласно math_errhandling.

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

std::hypot(x, y), std::hypot(y, x) и std::hypot(x, -y) эквивалентны.
если один из аргументов равен ±0, std::hypot(x, y) эквивалентен std::fabs, вызванной с ненулевым аргументом.
если один из аргументов равен ±∞, std::hypot(x, y) возвращает +∞, даже если другой аргумент равен NaN.
в противном случае, если любой из аргументов равен NaN, возвращается NaN.

Примечания

Реализации обычно гарантируют точность менее 1 единицы младшего разряда (ULP): GNU, BSD.

std::hypot(x, y) эквивалентен std::abs(std::complex<double>(x, y)).

В POSIX указано, что потеря значимости может происходить только тогда, когда оба аргумента являются субнормальными числами и правильный результат также является субнормальным (это исключает наивные реализации).

Расстояние между двумя точками (x1, y1, z1) и (x2, y2, z2) в трёхмерном пространстве можно вычислить с помощью трёхаргументной перегрузки std::hypot как std::hypot(x2 - x1, y2 - y1, z2 - z1).

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

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

Если num1, num2 или num3 имеет тип longdouble, то

std::hypot(num1, num2) действует так же, как std::hypot(static_cast<long double>(num1),static_cast<long double>(num2)), и
std::hypot(num1, num2, num3) действует так же, как std::hypot(static_cast<long double>(num1),static_cast<long double>(num2),static_cast<long double>(num3)).

В противном случае, если num1, num2 и/или num3 имеет тип double или целочисленный тип, то

std::hypot(num1, num2) действует так же, как std::hypot(static_cast<double>(num1),static_cast<double>(num2)), и
std::hypot(num1, num2, num3) действует так же, как std::hypot(static_cast<double>(num1),static_cast<double>(num2),static_cast<double>(num3)).

В противном случае, если num1, num2 или num3 имеет тип float, то

std::hypot(num1, num2) действует так же, как std::hypot(static_cast<float>(num1),static_cast<float>(num2)), и
std::hypot(num1, num2, num3) действует так же, как std::hypot(static_cast<float>(num1),static_cast<float>(num2),static_cast<float>(num3)).

(до C++23)

Если num1, num2 и num3 имеют арифметические типы, то

std::hypot(num1, num2) действует так же, как std::hypot(static_cast</*common-floating-point-type*/>(num1),static_cast</*common-floating-point-type*/>(num2)), и
std::hypot(num1, num2, num3) действует так же, как std::hypot(static_cast</*common-floating-point-type*/>(num1),static_cast</*common-floating-point-type*/>(num2),static_cast</*common-floating-point-type*/>(num3)),

где /*common-floating-point-type*/ — тип с плавающей точкой с наибольшим рангом преобразования типов с плавающей точкой и наибольшим подрангом преобразования типов с плавающей точкой среди типов num1, num2 и num3; считается, что аргументы целочисленного типа имеют тот же ранг преобразования типов с плавающей точкой, что и double.

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

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

Макрос проверки поддержки возможностей	Значение	Стандарт	Возможность
`__cpp_lib_hypot`	`201603L`	(C++17)	трёхаргументная перегрузка `std::hypot` (4,B)

Пример

#include <cerrno>
#include <cfenv>
#include <cfloat>
#include <cmath>
#include <cstring>
#include <iostream>

// #pragma STDC FENV_ACCESS ON

struct Point3D { float x, y, z; };

int main()
{
    // typical usage
    std::cout << "(1,1) cartesian is (" << std::hypot(1, 1)
              << ',' << std::atan2(1,1) << ") polar\n";
    
    Point3D a{3.14, 2.71, 9.87}, b{1.14, 5.71, 3.87};
    // C++17 has 3-argument hypot overload:
    std::cout << "distance(a,b) = "
              << std::hypot(a.x - b.x, a.y - b.y, a.z - b.z) << '\n';
    
    // special values
    std::cout << "hypot(NAN,INFINITY) = " << std::hypot(NAN, INFINITY) << '\n';
    
    // error handling
    errno = 0;
    std::feclearexcept(FE_ALL_EXCEPT);
    std::cout << "hypot(DBL_MAX,DBL_MAX) = " << std::hypot(DBL_MAX, DBL_MAX) << '\n';
    
    if (errno == ERANGE)
        std::cout << "    errno = ERANGE " << std::strerror(errno) << '\n';
    if (std::fetestexcept(FE_OVERFLOW))
        std::cout << "    FE_OVERFLOW raised\n";
}

Вывод:

(1,1) cartesian is (1.41421,0.785398) polar
distance(a,b) = 7
hypot(NAN,INFINITY) = inf
hypot(DBL_MAX,DBL_MAX) = inf
    errno = ERANGE Numerical result out of range
    FE_OVERFLOW raised

См. также

powpowfpowl (C++11)(C++11)	возводит число в заданную степень (\(\small{x^y}\)x^y) (функция)
sqrtsqrtfsqrtl (C++11)(C++11)	вычисляет квадратный корень (\(\small{\sqrt{x}}\)√x) (функция)
cbrtcbrtfcbrtl (C++11)(C++11)(C++11)	вычисляет кубический корень (\(\small{\sqrt[3]{x}}\)3√x) (функция)
abs(std::complex)	возвращает модуль комплексного числа (шаблон функции)
Документация по C для `hypot`

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