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

Определено в заголовке `<cmath>`
	(1)
float hypot ( float x, float y ); double hypot ( double x, double y ); long double hypot ( long double x, long double y );		(с C++11) (до C++23)
/* floating-point-type / hypot ( / floating-point-type / x, / floating-point-type */ y );		(с 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)
	(4)
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 );		(с C++17) (до C++23)
/* floating-point-type / hypot ( / floating-point-type / x, / floating-point-type / y, / floating-point-type */ z );		(с 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) (constexpr с C++26)

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) Если ошибки не произошли, возвращается расстояние от начала координат в 3D пространстве, \(\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) в 3D пространстве можно вычислить с помощью трёхаргументной перегрузки std::hypot как std::hypot(x2 - x1, y2 - y1, z2 - z1).

(с C++17)

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

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

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`

Пример

#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/w/cpp/numeric/math/hypot