xref: /freebsd/lib/msun/man/hypot.3 (revision aa1a8ff2d6dbc51ef058f46f3db5a8bb77967145)
1.\" Copyright (c) 1985, 1991 Regents of the University of California.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd March 30, 2008
29.Dt HYPOT 3
30.Os
31.Sh NAME
32.Nm hypot ,
33.Nm hypotf ,
34.Nm hypotl ,
35.Nm cabs ,
36.Nm cabsf ,
37.Nm cabsl
38.Nd Euclidean distance and complex absolute value functions
39.Sh LIBRARY
40.Lb libm
41.Sh SYNOPSIS
42.In math.h
43.Ft double
44.Fn hypot "double x" "double y"
45.Ft float
46.Fn hypotf "float x" "float y"
47.Ft "long double"
48.Fn hypotl "long double x" "long double y"
49.In complex.h
50.Ft double
51.Fn cabs "double complex z"
52.Ft float
53.Fn cabsf "float complex z"
54.Ft "long double"
55.Fn cabsl "long double complex z"
56.Sh DESCRIPTION
57The
58.Fn hypot ,
59.Fn hypotf
60and
61.Fn hypotl
62functions
63compute the
64sqrt(x*x+y*y)
65in such a way that underflow will not happen, and overflow
66occurs only if the final result deserves it.
67The
68.Fn cabs ,
69.Fn cabsf
70and
71.Fn cabsl
72functions compute the complex absolute value of
73.Fa z .
74.Pp
75.Fn hypot "\*(If" "v"
76=
77.Fn hypot "v" "\*(If"
78= +\*(If for all
79.Fa v ,
80including \*(Na.
81.Sh ERROR (due to Roundoff, etc.)
82Below 0.97
83.Em ulps .
84Consequently
85.Fn hypot "5.0" "12.0"
86= 13.0
87exactly;
88in general, hypot and cabs return an integer whenever an
89integer might be expected.
90.Sh NOTES
91As might be expected,
92.Fn hypot "v" "\*(Na"
93and
94.Fn hypot "\*(Na" "v"
95are \*(Na for all
96.Em finite
97.Fa v .
98But programmers
99might be surprised at first to discover that
100.Fn hypot "\(+-\*(If" "\*(Na"
101= +\*(If.
102This is intentional; it happens because
103.Fn hypot "\*(If" "v"
104= +\*(If
105for
106.Em all
107.Fa v ,
108finite or infinite.
109Hence
110.Fn hypot "\*(If" "v"
111is independent of
112.Fa v .
113Unlike the reserved operand fault on a
114.Tn VAX ,
115the
116.Tn IEEE
117\*(Na is designed to
118disappear when it turns out to be irrelevant, as it does in
119.Fn hypot "\*(If" "\*(Na" .
120.Sh SEE ALSO
121.Xr carg 3 ,
122.Xr math 3 ,
123.Xr sqrt 3
124.Sh STANDARDS
125The
126.Fn hypot ,
127.Fn hypotf ,
128.Fn hypotl ,
129.Fn cabs ,
130.Fn cabsf ,
131and
132.Fn cabsl
133functions conform to
134.St -isoC-99 .
135.Sh HISTORY
136Both a
137.Fn hypot
138function and a
139.Fn cabs
140function
141appeared in
142.At v7 .
143