Initial checkin for a module for tolerant comparison of reals

doc/specs/index.md

@@ -22,6 +22,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
  - [stats](./stdlib_stats.html) - Descriptive Statistics
  - [stats_distribution_PRNG](./stdlib_stats_distribution_PRNG.html) - Probability Distributions random number generator
  - [string\_type](./stdlib_string_type.html) - Basic string support
+ - [tolerant](./stdlib_tolerant.html) - Tolerant comparisons of reals
 
 ## Missing specs
 

doc/specs/stdlib_tolerant.md

@@ -0,0 +1,85 @@
+---
+title: tolerant
+---
+
+# Tolerant comparison of reals
+
+[TOC]
+
+## Introduction
+
+The age-old adagium is that you should never compare real variables directly, as rounding/truncation errors can
+give false results. This module provides the means to allow a certain tolerance with such comparisons. In addition
+it provides tolerant versions of the `floor`, `ceil` and `round` functions. The operation is in most respects
+simple, in that a margin is used which is based on the "epsilon" value for the given kind of reals.
+
+
+## Procedures and operators provided
+
+The module's procedures and operators work on ordinary single-precision and double-precision reals.
+
+### `teq`, `tne`, `tgt`, `tge`, `tlt`, `tle` - Tolerant relational operators
+
+#### Description
+
+Compare two reals with a tolerance based on a small margin (set to three times the epsilon value).
+The implementation is such that if `x .teq. y` is true, then `x .tne. y` is never true and vice versa.
+Similarly for the pairs `.tlt.` and `.tge.`, `.tle.` and `.tgt.`.
+
+#### Syntax
+
+`if ( x .teq. y ) write(*,*) 'x and y are equal'`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Operator.
+
+#### Arguments
+
+`x`, `y`: Two reals (of the same kind) to be compared
+
+#### Result value
+
+A logical indicating whether the two operands are different enough or not.
+
+
+### `tfloor`, `tceil`, `tround` - Tolerant versions of the `floor`, `ceil` and `round` functions
+
+#### Description
+
+Provide tolerant versions of the `floor`, `ceil` and `round` functions that take a small interval into account.
+While the actual interval can be set, the advised default is three times epsilon(). Note that the implementation
+is actually much more involved  than would seem necessary. It is the result of extensive research.
+
+
+#### Syntax
+
+```fortran
+    fl = [[stdlib_tolerant(module):tfloor(interface)]](x)  ! Or: tfloor( x, ct ) if you want control over the interval
+    cl = [[stdlib_tolerant(module):tfceil(interface)]](x)  ! Or: tceil( x, ct )
+    rnd = [[stdlib_tolerant(module):tround(interface)]](x) ! Or: tround( x, ct )
+```
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemental function
+
+#### Arguments
+
+`x`: The real number that is to be truncated or rounded
+
+`ct`: Tolearance for comparison (optional, defaults to 3*epsilon)
+
+#### Return value
+
+A real value of the same kind as the argument but with proper truncation or rounding in accordance
+with the function.
+

src/CMakeLists.txt

@@ -43,6 +43,7 @@ set(SRC
     stdlib_logger.f90
     stdlib_string_type.f90
     stdlib_system.F90
+    stdlib_tolerant.f90
     ${outFiles}
 )