View Issue Details

IDProjectCategoryView StatusLast Update
0033805FPCDocumentationpublic2018-06-28 10:38
ReporterWolfgang EhrhardtAssigned ToMichael Van Canneyt 
PrioritynormalSeverityminorReproducibilityN/A
Status resolvedResolutionfixed 
Product VersionProduct Build 
Target Version3.2.0Fixed in Version3.1.1 
Summary0033805: Misleading documentation for TFPURoundingMode
DescriptionThe docmentation for TFPURoundingMode in https://www.freepascal.org/docs-html/rtl/system/tfpuroundingmode.html is misleading.

The TFPURoundingMode enumerates the FPU Rounding modes, which is applied to all non-exact floating-point operation.

The current description describes only the special case when used with the round function.

type TFPURoundingMode = (
  rmNearest, Round to nearest integer
  rmDown, Round to biggest integer smaller than value.
  rmUp, Round to smallest integer larger than value
  rmTruncate Cut off fractional part
);

The Delphi6 Help

rmNearest Rounds to the closest value.
rmDown Rounds toward negative infinity.
rmUp Rounds toward positive infinity.
rmTruncate Truncates the value, rounding positive numbers down and negative numbers up.

and Wikipedia (https://en.wikipedia.org/wiki/IEEE_floating_point#Rounding_rules) are more
exact

So I suggest to use something like this

type TFPURoundingMode = (
  rmNearest, Rounding to nearest-even (least significant 0 in case of a tie)
  rmDown, Rounding towards negative infinity (also known as rounding down).
  rmUp, Rounding towards positive infinity (also known as rounding up).
  rmTruncate Rounding towards zero (also known as truncation).
);
Additional InformationThis issue report comes from http://www.lazarusforum.de/viewtopic.php?p=103793#p103793 ff.
TagsNo tags attached.
Fixed in Revision1489
FPCOldBugId
FPCTarget
Attached Files

Activities

wp

2018-05-30 15:06

reporter   ~0108590

Sorry, but what is a "tie" here? Certainly not the thing which I don't like being wrapped around my neck.

Please avoid such special words not known to the average programmer in a documentation article.

Wolfgang Ehrhardt

2018-05-30 15:41

reporter   ~0108591

Last edited: 2018-05-30 15:47

View 3 revisions

See https://en.wikipedia.org/wiki/Rounding#Rounding_to_the_nearest_integer:
Rounding a number y to the nearest integer requires some tie-breaking rule for those cases when y is exactly half-way between two integers — that is, when the fraction part of y is exactly 0.5.

or

https://en.wikipedia.org/wiki/Rounding#Round_half_to_even

The problem with these references is that they are also misleading, because they once again argue for the round function only, e.g. whether 0.5 or 1.5 should be rounded up or down.

The FPU rounding controls applies to ALL operations and an exact description has to introduce some more exotic terms than tie-breaking, namely rounding-bit. sticky-bit etc. See e.g. https://stackoverflow.com/questions/19146131/rounding-floating-point-numbers-after-addition-guard-sticky-and-round-bits or https://stackoverflow.com/questions/45662113/guard-round-sticky-bits-floating-point?rq=1 or do a web search with sticky bit rounding

So may be this is a bit better:

type TFPURoundingMode = (
  rmNearest, Rounding to nearest-even (round to even, i.e. the least significant bit will be 0, if the number falls midway between to floating-point numbers)
  rmDown, Rounding towards negative infinity (also known as rounding down).
  rmUp, Rounding towards positive infinity (also known as rounding up).
  rmTruncate Rounding towards zero (also known as truncation).
);

Marģers

2018-05-30 21:13

reporter   ~0108595

i'm so confused. "rmNearest" does not follow common rule of rounding, so it should be explained more detailed. i'm agree with Wolfgang Ehrhardt, that documentation is misleading, even if it is satisfy the standard of rounding floating point numbers.

Michael Van Canneyt

2018-06-28 10:38

administrator   ~0109100

Improved the wording for rmNearest and rmTruncate, making the use of banker's rounding explicit.

Issue History

Date Modified Username Field Change
2018-05-30 13:36 Wolfgang Ehrhardt New Issue
2018-05-30 13:36 Wolfgang Ehrhardt Status new => assigned
2018-05-30 13:36 Wolfgang Ehrhardt Assigned To => Michael Van Canneyt
2018-05-30 15:06 wp Note Added: 0108590
2018-05-30 15:41 Wolfgang Ehrhardt Note Added: 0108591
2018-05-30 15:42 Wolfgang Ehrhardt Note Edited: 0108591 View Revisions
2018-05-30 15:47 Wolfgang Ehrhardt Note Edited: 0108591 View Revisions
2018-05-30 21:13 Marģers Note Added: 0108595
2018-06-28 10:38 Michael Van Canneyt Fixed in Revision => 1489
2018-06-28 10:38 Michael Van Canneyt Note Added: 0109100
2018-06-28 10:38 Michael Van Canneyt Status assigned => resolved
2018-06-28 10:38 Michael Van Canneyt Fixed in Version => 3.1.1
2018-06-28 10:38 Michael Van Canneyt Resolution open => fixed
2018-06-28 10:38 Michael Van Canneyt Target Version => 3.2.0