/usr/share/doc/libmpfr-doc/mpfr.html/Rounding-Modes.html

<html lang="en">
<head>
<title>Rounding Modes - GNU MPFR 3.1.0</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="How to install and use GNU MPFR, a library for reliable multiple precision
floating-point arithmetic, version 3.1.0.">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="MPFR-Basics.html#MPFR-Basics" title="MPFR Basics">
<link rel="prev" href="MPFR-Variable-Conventions.html#MPFR-Variable-Conventions" title="MPFR Variable Conventions">
<link rel="next" href="Floating_002dPoint-Values-on-Special-Numbers.html#Floating_002dPoint-Values-on-Special-Numbers" title="Floating-Point Values on Special Numbers">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This manual documents how to install and use the Multiple Precision
Floating-Point Reliable Library, version 3.1.0.

Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later
version published by the Free Software Foundation; with no Invariant Sections,
with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the
license is included in *note GNU Free Documentation License::.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Rounding-Modes"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Floating_002dPoint-Values-on-Special-Numbers.html#Floating_002dPoint-Values-on-Special-Numbers">Floating-Point Values on Special Numbers</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="MPFR-Variable-Conventions.html#MPFR-Variable-Conventions">MPFR Variable Conventions</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="MPFR-Basics.html#MPFR-Basics">MPFR Basics</a>
<hr>
</div>

<!-- node-name,  next,  previous,  up -->
<h3 class="section">4.4 Rounding Modes</h3>

<p>The following five rounding modes are supported:

     <ul>
<li><code>MPFR_RNDN</code>: round to nearest (roundTiesToEven in IEEE 754-2008),
<li><code>MPFR_RNDZ</code>: round toward zero (roundTowardZero in IEEE 754-2008),
<li><code>MPFR_RNDU</code>: round toward plus infinity (roundTowardPositive in IEEE 754-2008),
<li><code>MPFR_RNDD</code>: round toward minus infinity (roundTowardNegative in IEEE 754-2008),
<li><code>MPFR_RNDA</code>: round away from zero. 
</ul>

   <p>The &lsquo;<samp><span class="samp">round to nearest</span></samp>&rsquo; mode works as in the IEEE 754 standard: in
case the number to be rounded lies exactly in the middle of two representable
numbers, it is rounded to the one with the least significant bit set to zero. 
For example, the number 2.5, which is represented by (10.1) in binary, is
rounded to (10.0)=2 with a precision of two bits, and not to (11.0)=3. 
This rule avoids the <dfn>drift</dfn> phenomenon mentioned by Knuth in volume 2
of The Art of Computer Programming (Section 4.2.2).

   <p><a name="ternary-value"></a><a name="index-Ternary-value-22"></a>Most MPFR functions take as first argument the destination variable, as
second and following arguments the input variables, as last argument a
rounding mode, and have a return value of type <code>int</code>, called the
<dfn>ternary value</dfn>. The value stored in the destination variable is
correctly rounded, i.e., MPFR behaves as if it computed the result with
an infinite precision, then rounded it to the precision of this variable. 
The input variables are regarded as exact (in particular, their precision
does not affect the result).

   <p>As a consequence, in case of a non-zero real rounded result, the error
on the result is less or equal to 1/2 ulp (unit in the last place) of
that result in the rounding to nearest mode, and less than 1 ulp of that
result in the directed rounding modes (a ulp is the weight of the least
significant represented bit of the result after rounding). 
<!-- Since subnormals are not supported, we must take into account the ulp of -->
<!-- the rounded result, not the one of the exact result, for full generality. -->

   <p>Unless documented otherwise, functions returning an <code>int</code> return
a ternary value. 
If the ternary value is zero, it means that the value stored in the
destination variable is the exact result of the corresponding mathematical
function. If the ternary value is positive (resp. negative), it means
the value stored in the destination variable is greater (resp. lower)
than the exact result. For example with the <code>MPFR_RNDU</code> rounding mode,
the ternary value is usually positive, except when the result is exact, in
which case it is zero. In the case of an infinite result, it is considered
as inexact when it was obtained by overflow, and exact otherwise. A NaN
result (Not-a-Number) always corresponds to an exact return value. 
The opposite of a returned ternary value is guaranteed to be representable
in an <code>int</code>.

   <p>Unless documented otherwise, functions returning as result the value <code>1</code>
(or any other value specified in this manual)
for special cases (like <code>acos(0)</code>) yield an overflow or
an underflow if that value is not representable in the current exponent range.

   </body></html>
libmpfr-doc 3.1.0-3ubuntu2 / usr / share / doc / libmpfr-doc / mpfr.html / Rounding-Modes.html
