Copyright | (c) Michael Szvetits 2019 |
---|---|

License | BSD3 (see the file LICENSE) |

Maintainer | typedbyte@qualified.name |

Stability | stable |

Portability | portable |

Safe Haskell | Safe |

Language | Haskell2010 |

This module exports the types and functions needed to construct, combine and process lower and upper bounds of numeric intervals.

Package users might want to use the module Numeric.Domain instead, since it provides a convenient abstraction for intervals and their bounds.

## Synopsis

- data LowerBound a
- data UpperBound a
- closedLower :: a -> LowerBound a
- closedUpper :: a -> UpperBound a
- openLower :: Dist a => a -> LowerBound a
- openUpper :: Dist a => a -> UpperBound a
- infiniteLower :: LowerBound a
- infiniteUpper :: UpperBound a
- adjacentLower :: Dist a => UpperBound a -> Maybe (LowerBound a)
- adjacentUpper :: Dist a => LowerBound a -> Maybe (UpperBound a)
- mergeable :: Dist a => UpperBound a -> LowerBound a -> Bool
- isAbove :: Ord a => LowerBound a -> UpperBound a -> Bool
- isBelow :: Ord a => UpperBound a -> LowerBound a -> Bool
- isSingleton :: Eq a => LowerBound a -> UpperBound a -> Bool
- isInfiniteLower :: LowerBound a -> Bool
- isInfiniteUpper :: UpperBound a -> Bool
- isPositiveLower :: (Num a, Ord a) => LowerBound a -> Bool
- isPositiveUpper :: (Num a, Ord a) => UpperBound a -> Bool
- isNegativeLower :: (Num a, Ord a) => LowerBound a -> Bool
- isNegativeUpper :: (Num a, Ord a) => UpperBound a -> Bool
- isZeroLower :: (Eq a, Num a) => LowerBound a -> Bool
- isZeroUpper :: (Eq a, Num a) => UpperBound a -> Bool
- containsLower :: Ord a => a -> LowerBound a -> Bool
- containsUpper :: Ord a => a -> UpperBound a -> Bool
- elems :: Enum a => LowerBound a -> UpperBound a -> Maybe [a]
- minValue :: LowerBound a -> Maybe a
- maxValue :: UpperBound a -> Maybe a
- data Result a
- = Lower (LowerBound a)
- | Upper (UpperBound a)
- | Both (LowerBound a) (UpperBound a)

- applyResult :: Ord a => (Maybe (LowerBound a), Maybe (UpperBound a)) -> Result a -> (Maybe (LowerBound a), Maybe (UpperBound a))
- plusLower :: Num a => LowerBound a -> LowerBound a -> LowerBound a
- plusUpper :: Num a => UpperBound a -> UpperBound a -> UpperBound a
- minusLower :: Num a => UpperBound a -> LowerBound a -> UpperBound a
- minusUpper :: Num a => LowerBound a -> UpperBound a -> LowerBound a
- timesLower :: (Num a, Ord a) => LowerBound a -> LowerBound a -> Result a
- timesUpper :: (Num a, Ord a) => UpperBound a -> UpperBound a -> Result a
- timesMixed :: (Num a, Ord a) => LowerBound a -> UpperBound a -> Result a
- divLower :: Integral a => LowerBound a -> LowerBound a -> Result a
- divUpper :: Integral a => UpperBound a -> UpperBound a -> Result a
- divLowerUpper :: Integral a => LowerBound a -> UpperBound a -> Result a
- divUpperLower :: Integral a => UpperBound a -> LowerBound a -> Result a
- recipLower :: Fractional a => LowerBound a -> UpperBound a
- recipUpper :: Fractional a => UpperBound a -> LowerBound a
- negateLower :: Num a => LowerBound a -> UpperBound a
- negateUpper :: Num a => UpperBound a -> LowerBound a
- prettyLower :: Show a => LowerBound a -> String
- prettyUpper :: Show a => UpperBound a -> String

# Core Types

data LowerBound a Source #

The lower bound of an interval. Can be open, closed or negative infinity.

## Instances

Eq a => Eq (LowerBound a) Source # | |

Defined in Numeric.Bound (==) :: LowerBound a -> LowerBound a -> Bool # (/=) :: LowerBound a -> LowerBound a -> Bool # | |

Ord a => Ord (LowerBound a) Source # | |

Defined in Numeric.Bound compare :: LowerBound a -> LowerBound a -> Ordering # (<) :: LowerBound a -> LowerBound a -> Bool # (<=) :: LowerBound a -> LowerBound a -> Bool # (>) :: LowerBound a -> LowerBound a -> Bool # (>=) :: LowerBound a -> LowerBound a -> Bool # max :: LowerBound a -> LowerBound a -> LowerBound a # min :: LowerBound a -> LowerBound a -> LowerBound a # | |

Show a => Show (LowerBound a) Source # | |

Defined in Numeric.Bound showsPrec :: Int -> LowerBound a -> ShowS # show :: LowerBound a -> String # showList :: [LowerBound a] -> ShowS # |

data UpperBound a Source #

The upper bound of an interval. Can be open, closed or positive infinity.

## Instances

Eq a => Eq (UpperBound a) Source # | |

Defined in Numeric.Bound (==) :: UpperBound a -> UpperBound a -> Bool # (/=) :: UpperBound a -> UpperBound a -> Bool # | |

Ord a => Ord (UpperBound a) Source # | |

Defined in Numeric.Bound compare :: UpperBound a -> UpperBound a -> Ordering # (<) :: UpperBound a -> UpperBound a -> Bool # (<=) :: UpperBound a -> UpperBound a -> Bool # (>) :: UpperBound a -> UpperBound a -> Bool # (>=) :: UpperBound a -> UpperBound a -> Bool # max :: UpperBound a -> UpperBound a -> UpperBound a # min :: UpperBound a -> UpperBound a -> UpperBound a # | |

Show a => Show (UpperBound a) Source # | |

Defined in Numeric.Bound showsPrec :: Int -> UpperBound a -> ShowS # show :: UpperBound a -> String # showList :: [UpperBound a] -> ShowS # |

# Bound Construction

closedLower :: a -> LowerBound a Source #

Creates a closed lower bound.

closedUpper :: a -> UpperBound a Source #

Creates a closed upper bound.

openLower :: Dist a => a -> LowerBound a Source #

Creates an open lower bound. Internally, the bound is converted to a closed one, if possible.

openUpper :: Dist a => a -> UpperBound a Source #

Creates an open upper bound. Internally, the bound is converted to a closed one, if possible.

infiniteLower :: LowerBound a Source #

Creates a negative infinite lower bound.

infiniteUpper :: UpperBound a Source #

Creates a positive infinite upper bound.

# Bound Combination

adjacentLower :: Dist a => UpperBound a -> Maybe (LowerBound a) Source #

Creates a lower bound that is adjacent to (i.e., directly above) a given upper bound.

Returns `Nothing`

if the upper bound is positive infinity.

adjacentUpper :: Dist a => LowerBound a -> Maybe (UpperBound a) Source #

Creates an upper bound that is adjacent to (i.e., directly below) a given lower bound.

Returns `Nothing`

if the lower bound is negative infinity.

# Bound Predicates

mergeable :: Dist a => UpperBound a -> LowerBound a -> Bool Source #

Checks if an upper bound and a lower bound are mergeable, i.e. if they overlap or if they are adjacent to each other.

Note that adjacency depends on the type of the bound values, e.g. the
upper bound `[...,3]`

and lower bound `[4,...]`

can be merged for
`Interval Int`

, but not for `Interval Double`

.

Infinite bounds (negative infinity, positive infinity) are never mergeable.

isAbove :: Ord a => LowerBound a -> UpperBound a -> Bool Source #

Checks if a lower bound is above an upper bound.

isBelow :: Ord a => UpperBound a -> LowerBound a -> Bool Source #

Checks if an upper bound is below a lower bound.

isSingleton :: Eq a => LowerBound a -> UpperBound a -> Bool Source #

Checks if a lower bound and an upper bound contain exactly one element.

isInfiniteLower :: LowerBound a -> Bool Source #

Checks if a lower bound is negative infinity.

isInfiniteUpper :: UpperBound a -> Bool Source #

Checks if an upper bound is positive infinity.

isPositiveLower :: (Num a, Ord a) => LowerBound a -> Bool Source #

Checks if a lower bound is positive.

isPositiveUpper :: (Num a, Ord a) => UpperBound a -> Bool Source #

Checks if an upper bound is positive.

isNegativeLower :: (Num a, Ord a) => LowerBound a -> Bool Source #

Checks if a lower bound is negative.

isNegativeUpper :: (Num a, Ord a) => UpperBound a -> Bool Source #

Checks if an upper bound is negative.

isZeroLower :: (Eq a, Num a) => LowerBound a -> Bool Source #

Checks if a lower bound is zero. It is ignored if the bound is open or closed.

isZeroUpper :: (Eq a, Num a) => UpperBound a -> Bool Source #

Checks if an upper bound is zero. It is ignored if the bound is open or closed.

containsLower :: Ord a => a -> LowerBound a -> Bool Source #

Checks if a lower bound contains a specific value, i.e. if the value is equal to (if closed) or greater than (if open or closed) the lower bound.

containsUpper :: Ord a => a -> UpperBound a -> Bool Source #

Checks if an upper bound contains a specific value, i.e. if the value is equal to (if closed) or less than (if open or closed) the upper bound.

# Bound Values

elems :: Enum a => LowerBound a -> UpperBound a -> Maybe [a] Source #

minValue :: LowerBound a -> Maybe a Source #

Returns the smallest value of a lower bound.

Only succeeds if the lower bound is closed.

maxValue :: UpperBound a -> Maybe a Source #

Returns the greatest value of an upper bound.

Only succeeds if the upper bound is closed.

# Bound Arithmetic

A special type for representing the result of bound multiplications and divisions. These operations can either yield a lower bound, an upper bound or both.

Lower (LowerBound a) | |

Upper (UpperBound a) | |

Both (LowerBound a) (UpperBound a) |

applyResult :: Ord a => (Maybe (LowerBound a), Maybe (UpperBound a)) -> Result a -> (Maybe (LowerBound a), Maybe (UpperBound a)) Source #

Given a possible lower bound and upper bound as well as a result from a bound multiplication or division, this function updates the bounds depending on whether the result was a lower bound, upper bound or both.

The lower bound is updated by favouring the smaller one, while the upper bound is updated by favouring the greater one.

plusLower :: Num a => LowerBound a -> LowerBound a -> LowerBound a Source #

Adds the values of two lower bounds.

plusUpper :: Num a => UpperBound a -> UpperBound a -> UpperBound a Source #

Adds the values of two upper bounds.

minusLower :: Num a => UpperBound a -> LowerBound a -> UpperBound a Source #

Subtracts the value of a lower bound from the value of an upper bound.

minusUpper :: Num a => LowerBound a -> UpperBound a -> LowerBound a Source #

Subtracts the value of an upper bound from the value of a lower bound.

timesLower :: (Num a, Ord a) => LowerBound a -> LowerBound a -> Result a Source #

Multiplies the values of two lower bounds.

timesUpper :: (Num a, Ord a) => UpperBound a -> UpperBound a -> Result a Source #

Multiplies the values of two upper bounds.

timesMixed :: (Num a, Ord a) => LowerBound a -> UpperBound a -> Result a Source #

Multiplies the value of a lower bound and the value of an upper bound.

divLower :: Integral a => LowerBound a -> LowerBound a -> Result a Source #

Divides the values of two lower bounds using integer division.

Note that it is not checked if the divisor bound is zero, which yields an error. Such a check must happen before calling this function.

divUpper :: Integral a => UpperBound a -> UpperBound a -> Result a Source #

Divides the values of two upper bounds using integer division.

Note that it is not checked if the divisor bound is zero, which yields an error. Such a check must happen before calling this function.

divLowerUpper :: Integral a => LowerBound a -> UpperBound a -> Result a Source #

Divides the values of a lower bound and an upper bound using integer division.

Note that it is not checked if the divisor bound is zero, which yields an error. Such a check must happen before calling this function.

divUpperLower :: Integral a => UpperBound a -> LowerBound a -> Result a Source #

Divides the values of an upper bound and a lower bound using integer division.

recipLower :: Fractional a => LowerBound a -> UpperBound a Source #

Calculates the reciprocal of a lower bound and transforms it into an upper bound.

recipUpper :: Fractional a => UpperBound a -> LowerBound a Source #

Calculates the reciprocal of an upper bound and transforms it into a lower bound.

negateLower :: Num a => LowerBound a -> UpperBound a Source #

Negates a lower bound and transforms it into an upper bound.

negateUpper :: Num a => UpperBound a -> LowerBound a Source #

Negates an upper bound and transforms it into a lower bound.

# Bound Presentation

prettyLower :: Show a => LowerBound a -> String Source #

Returns a pretty string for a lower bound by using the Unicode symbol for negative infinity.

prettyUpper :: Show a => UpperBound a -> String Source #

Returns a pretty string for an upper bound by using the Unicode symbol for positive infinity.