lib/libm/man/remainder.3

   1 .\" $NetBSD: remainder.3,v 1.2 2011/09/18 05:33:14 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd September 18, 2011
  28 .Dt REMAINDER 3
  29 .Os
  30 .Sh NAME
  31 .Nm remainder ,
  32 .Nm remainderf ,
  33 .Nm remquo ,
  34 .Nm remquof
  35 .Nd remainder functions
  36 .Sh LIBRARY
  37 .Lb libm
  38 .Sh SYNOPSIS
  39 .In math.h
  40 .Ft double
  41 .Fn remainder "double x" "double y"
  42 .Ft float
  43 .Fn remainderf "float x" "float y"
  44 .Ft double
  45 .Fn remquo "double x" "double y" "int *quo"
  46 .Ft float
  47 .Fn remquof "float x" "float y" "int *quo"
  48 .Sh DESCRIPTION
  49 Provided that
  50 .Fa y
  51 \*(Ne 0 ,
  52 the
  53 .Fn remainder
  54 and
  55 .Fn remainderf
  56 functions calculate the floating-point remainder
  57 .Fa r
  58 of
  59 .Bd -ragged -offset indent
  60 .Va r
  61 =
  62 .Va x - ny ,
  63 .Ed
  64 .Pp
  65 where
  66 .Fa n
  67 is the integral value nearest to the exact value of
  68 .Fa x
  69 /
  70 .Fa y .
  71 If
  72 .Bd -ragged -offset indent
  73 .Va | n
  74 -
  75 .Va x / y |
  76 = 1/2 ,
  77 .Ed
  78 .Pp
  79 the value
  80 .Fa n
  81 is chosen to be even.
  82 Consequently, the remainder is computed exactly and
  83 .Va | r |
  84 \*(Le
  85 .Fa | y |
  86 / 2 .
  87 .Pp
  88 Also the
  89 .Fn remquo
  90 and
  91 .Fn remquof
  92 functions calculate the remainder as described above.
  93 But these additionally use
  94 .Fa quo
  95 to store a value whose sign is the sign of
  96 .Va x / y
  97 and whose magnitude is congruent modulo
  98 .Va 2^k
  99 to the magnitude of the integral quotient of
 100 .Va x / y ,
 101 where
 102 .Fa k
 103 is an implementation-defined integer greater than or equal to 3.
 104 .Pp
 105 The rationale of the
 106 .Fn remquo
 107 family of functions relates to situations where
 108 only few bits of the quotient are required.
 109 The exact representation of the quotient may not be meaningful when
 110 .Fa x
 111 is large in magnitude compared to
 112 .Fa y .
 113 .Sh RETURN VALUES
 114 The functions return the remainder independent of the rounding mode.
 115 If
 116 .Fa y
 117 is zero ,
 118 \*(Na
 119 is returned and a domain error occurs.
 120 A domain error occurs and a
 121 \*(Na
 122 is returned also when
 123 .Fa x
 124 is infinite but
 125 .Fa y
 126 is not a
 127 \*(Na.
 128 If either
 129 .Fa x
 130 or
 131 .Fa y
 132 is
 133 \*(Na,
 134 a
 135 \*(Na
 136 is always returned.
 137 .Sh SEE ALSO
 138 .Xr div 3 ,
 139 .Xr fast_remainder32 3 ,
 140 .Xr fmod 3 ,
 141 .Xr math 3
 142 .Sh STANDARDS
 143 The described functions conform to
 144 .St -isoC-99 .