1math::fuzzy(n)                 Tcl Math Library                 math::fuzzy(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       math::fuzzy - Fuzzy comparison of floating-point numbers
9

SYNOPSIS

11       package require Tcl  ?8.3?
12
13       package require math::fuzzy  ?0.2?
14
15       ::math::fuzzy::teq value1 value2
16
17       ::math::fuzzy::tne value1 value2
18
19       ::math::fuzzy::tge value1 value2
20
21       ::math::fuzzy::tle value1 value2
22
23       ::math::fuzzy::tlt value1 value2
24
25       ::math::fuzzy::tgt value1 value2
26
27       ::math::fuzzy::tfloor value
28
29       ::math::fuzzy::tceil value
30
31       ::math::fuzzy::tround value
32
33       ::math::fuzzy::troundn value ndigits
34
35______________________________________________________________________________
36

DESCRIPTION

38       The package Fuzzy is meant to solve common problems with floating-point
39       numbers in a systematic way:
40
41       ·      Comparing two numbers that are "supposed" to be identical,  like
42              1.0  and  2.1/(1.2+0.9)  is not guaranteed to give the intuitive
43              result.
44
45       ·      Rounding a number that is halfway two integer numbers can  cause
46              strange errors, like int(100.0*2.8) != 28 but 27
47
48       The Fuzzy package is meant to help sorting out this type of problems by
49       defining "fuzzy" comparison procedures for floating-point numbers.   It
50       does so by allowing for a small margin that is determined automatically
51       - the margin is three times the "epsilon" value, that  is  three  times
52       the smallest number eps such that 1.0 and 1.0+$eps canbe distinguished.
53       In Tcl, which uses double precision  floating-point  numbers,  this  is
54       typically 1.1e-16.
55

PROCEDURES

57       Effectively the package provides the following procedures:
58
59       ::math::fuzzy::teq value1 value2
60              Compares  two floating-point numbers and returns 1 if their val‐
61              ues fall within a small range. Otherwise it returns 0.
62
63       ::math::fuzzy::tne value1 value2
64              Returns the negation, that is, if the difference is larger  than
65              the margin, it returns 1.
66
67       ::math::fuzzy::tge value1 value2
68              Compares  two floating-point numbers and returns 1 if their val‐
69              ues either fall within a small range or if the first  number  is
70              larger than the second. Otherwise it returns 0.
71
72       ::math::fuzzy::tle value1 value2
73              Returns  1 if the two numbers are equal according to [teq] or if
74              the first is smaller than the second.
75
76       ::math::fuzzy::tlt value1 value2
77              Returns the opposite of [tge].
78
79       ::math::fuzzy::tgt value1 value2
80              Returns the opposite of [tle].
81
82       ::math::fuzzy::tfloor value
83              Returns the integer number that is lower or equal to  the  given
84              floating-point number, within a well-defined tolerance.
85
86       ::math::fuzzy::tceil value
87              Returns the integer number that is greater or equal to the given
88              floating-point number, within a well-defined tolerance.
89
90       ::math::fuzzy::tround value
91              Rounds the floating-point number off.
92
93       ::math::fuzzy::troundn value ndigits
94              Rounds the floating-point number off to the specified number  of
95              decimals (Pro memorie).
96
97       Usage:
98
99
100              if { [teq $x $y] } { puts "x == y" }
101              if { [tne $x $y] } { puts "x != y" }
102              if { [tge $x $y] } { puts "x >= y" }
103              if { [tgt $x $y] } { puts "x > y" }
104              if { [tlt $x $y] } { puts "x < y" }
105              if { [tle $x $y] } { puts "x <= y" }
106
107              set fx      [tfloor $x]
108              set fc      [tceil  $x]
109              set rounded [tround $x]
110              set roundn  [troundn $x $nodigits]
111
112

TEST CASES

114       The problems that can occur with floating-point numbers are illustrated
115       by the test cases in the file "fuzzy.test":
116
117       ·      Several test case use the ordinary comparisons,  and  they  fail
118              invariably to produce understandable results
119
120       ·      One  test  case  uses  [expr]  without  braces ({ and }). It too
121              fails.
122
123       The conclusion from this is that any expression should be surrounded by
124       braces,  because  otherwise  very awkward things can happen if you need
125       accuracy. Furthermore, accuracy and understandable results are enhanced
126       by using these "tolerant" or fuzzy comparisons.
127
128       Note  that  besides  the Tcl-only package, there is also a C-based ver‐
129       sion.
130

REFERENCES

132       Original implementation in Fortran by dr. H.D. Knoble (Penn State  Uni‐
133       versity).
134
135       P.  E.  Hagerty,  "More  on  Fuzzy  Floor  and Ceiling," APL QUOTE QUAD
136       8(4):20-24, June 1978. Note that TFLOOR=FL5 took five years of refereed
137       evolution (publication).
138
139       L.  M. Breed, "Definitions for Fuzzy Floor and Ceiling", APL QUOTE QUAD
140       8(3):16-23, March 1978.
141
142       D. Knuth, Art of Computer Programming, Vol. 1, Problem 1.2.4-5.
143

BUGS, IDEAS, FEEDBACK

145       This document, and the package it describes, will  undoubtedly  contain
146       bugs  and  other  problems.  Please report such in the category math ::
147       fuzzy of the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].
148       Please  also  report any ideas for enhancements you may have for either
149       package and/or documentation.
150
151       When proposing code changes, please provide unified diffs, i.e the out‐
152       put of diff -u.
153
154       Note  further  that  attachments  are  strongly  preferred over inlined
155       patches. Attachments can be made by going  to  the  Edit  form  of  the
156       ticket  immediately  after  its  creation, and then using the left-most
157       button in the secondary navigation bar.
158

KEYWORDS

160       floating-point, math, rounding
161

CATEGORY

163       Mathematics
164
165
166
167tcllib                                0.2                       math::fuzzy(n)
Impressum