contrib/openbsd_libm/man/hypot.3

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