1[manpage_begin math::fuzzy n 0.2] 2[moddesc {Tcl Math Library}] 3[titledesc {Fuzzy comparison of floating-point numbers}] 4[category Mathematics] 5[require Tcl [opt 8.3]] 6[require math::fuzzy [opt 0.2]] 7[description] 8[para] 9The package Fuzzy is meant to solve common problems with floating-point 10numbers in a systematic way: 11 12[list_begin itemized] 13[item] 14Comparing two numbers that are "supposed" to be identical, like 151.0 and 2.1/(1.2+0.9) is not guaranteed to give the 16intuitive result. 17 18[item] 19Rounding a number that is halfway two integer numbers can cause 20strange errors, like int(100.0*2.8) != 28 but 27 21[list_end] 22 23[para] 24The Fuzzy package is meant to help sorting out this type of problems 25by defining "fuzzy" comparison procedures for floating-point numbers. 26It does so by allowing for a small margin that is determined 27automatically - the margin is three times the "epsilon" value, that is 28three times the smallest number [emph eps] such that 1.0 and 1.0+$eps 29canbe distinguished. In Tcl, which uses double precision floating-point 30numbers, this is typically 1.1e-16. 31 32[section "PROCEDURES"] 33Effectively the package provides the following procedures: 34 35[list_begin definitions] 36[call [cmd ::math::fuzzy::teq] [arg value1] [arg value2]] 37Compares two floating-point numbers and returns 1 if their values 38fall within a small range. Otherwise it returns 0. 39 40[call [cmd ::math::fuzzy::tne] [arg value1] [arg value2]] 41Returns the negation, that is, if the difference is larger than 42the margin, it returns 1. 43 44[call [cmd ::math::fuzzy::tge] [arg value1] [arg value2]] 45Compares two floating-point numbers and returns 1 if their values 46either fall within a small range or if the first number is larger 47than the second. Otherwise it returns 0. 48 49[call [cmd ::math::fuzzy::tle] [arg value1] [arg value2]] 50Returns 1 if the two numbers are equal according to 51[lb]teq[rb] or if the first is smaller than the second. 52 53[call [cmd ::math::fuzzy::tlt] [arg value1] [arg value2]] 54Returns the opposite of [lb]tge[rb]. 55 56[call [cmd ::math::fuzzy::tgt] [arg value1] [arg value2]] 57Returns the opposite of [lb]tle[rb]. 58 59[call [cmd ::math::fuzzy::tfloor] [arg value]] 60Returns the integer number that is lower or equal 61to the given floating-point number, within a well-defined 62tolerance. 63[call [cmd ::math::fuzzy::tceil] [arg value]] 64Returns the integer number that is greater or equal to the given 65floating-point number, within a well-defined tolerance. 66 67[call [cmd ::math::fuzzy::tround] [arg value]] 68Rounds the floating-point number off. 69 70[call [cmd ::math::fuzzy::troundn] [arg value] [arg ndigits]] 71Rounds the floating-point number off to the 72specified number of decimals (Pro memorie). 73 74[list_end] 75 76Usage: 77[example_begin] 78if { [lb]teq $x $y[rb] } { puts "x == y" } 79if { [lb]tne $x $y[rb] } { puts "x != y" } 80if { [lb]tge $x $y[rb] } { puts "x >= y" } 81if { [lb]tgt $x $y[rb] } { puts "x > y" } 82if { [lb]tlt $x $y[rb] } { puts "x < y" } 83if { [lb]tle $x $y[rb] } { puts "x <= y" } 84 85set fx [lb]tfloor $x[rb] 86set fc [lb]tceil $x[rb] 87set rounded [lb]tround $x[rb] 88set roundn [lb]troundn $x $nodigits[rb] 89[example_end] 90 91[section {TEST CASES}] 92The problems that can occur with floating-point numbers are illustrated 93by the test cases in the file "fuzzy.test": 94[list_begin itemized] 95[item] 96Several test case use the ordinary comparisons, and they 97fail invariably to produce understandable results 98 99[item] 100One test case uses [lb]expr[rb] without braces ({ and }). It too 101fails. 102[list_end] 103 104The conclusion from this is that any expression should be surrounded by 105braces, because otherwise very awkward things can happen if you need 106accuracy. Furthermore, accuracy and understandable results are 107enhanced by using these "tolerant" or fuzzy comparisons. 108[para] 109Note that besides the Tcl-only package, there is also a C-based version. 110 111[section REFERENCES] 112Original implementation in Fortran by dr. H.D. Knoble (Penn State 113University). 114[para] 115P. E. Hagerty, "More on Fuzzy Floor and Ceiling," 116 117APL QUOTE QUAD 8(4):20-24, June 1978. Note that TFLOOR=FL5 took five 118years of refereed evolution (publication). 119[para] 120L. M. Breed, "Definitions for Fuzzy Floor and Ceiling", 121 122APL QUOTE QUAD 8(3):16-23, March 1978. 123[para] 124D. Knuth, Art of Computer Programming, 125 126Vol. 1, Problem 1.2.4-5. 127 128[section {BUGS, IDEAS, FEEDBACK}] 129 130This document, and the package it describes, will undoubtedly contain 131bugs and other problems. 132 133Please report such in the category [emph {math :: fuzzy}] of the 134[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 135 136Please also report any ideas for enhancements you may have for either 137package and/or documentation. 138 139 140[keywords math floating-point rounding] 141[manpage_end] 142