-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | This has a bunch of code for specifying and managing ranges in your code.
--   
--   range is built to allow you to use ranges in your code quickly and
--   efficiently. There are many occasions where you will want to check if
--   certain values are within a range and this library will make it
--   trivial for you to do so. It also attempts to do so in the most
--   efficient way possible.
@package range
@version 0.2.0.0


-- | Internally the range library converts your ranges into an internal
--   efficient representation of multiple ranges. When you do multiple
--   unions and intersections in a row converting to and from that data
--   structure becomes extra work that is not required. To amortize those
--   costs away the <tt>RangeExpr</tt> algebra exists. You can specify a
--   tree of operations in advance and then evaluate them all at once. This
--   is not only useful for efficiency but for parsing too. Build up
--   <tt>RangeExpr</tt>'s whenever you wish to perform multiple operations
--   in a row, and evaluate it in one step to be as efficient as possible.
module Data.Range.Algebra
data RangeExpr a

-- | Lifts the input value as a constant into an expression.
const :: a -> RangeExpr a

-- | Returns an expression that represents the inverse of the input
--   expression.
invert :: RangeExpr a -> RangeExpr a

-- | Returns an expression that represents the set union of the input
--   expressions.
union :: RangeExpr a -> RangeExpr a -> RangeExpr a

-- | Returns an expression that represents the set intersection of the
--   input expressions.
intersection :: RangeExpr a -> RangeExpr a -> RangeExpr a

-- | Returns an expression that represents the set difference of the input
--   expressions.
difference :: RangeExpr a -> RangeExpr a -> RangeExpr a
type Algebra f a = f a -> a

-- | Represents the fact that there exists an algebra for the given
--   representation of a range, so that a range expression of the same type
--   can be evaluated, yielding that representation.
class RangeAlgebra a
eval :: RangeAlgebra a => Algebra RangeExpr a
instance (GHC.Classes.Ord a, GHC.Enum.Enum a) => Data.Range.Algebra.RangeAlgebra [Data.Range.Data.Range a]
instance Data.Range.Algebra.RangeAlgebra (a -> GHC.Types.Bool)


-- | <i>Deprecated: Use <a>Data.Range.Algebra</a> instead</i>
module Data.Range.RangeTree

-- | Evaluates a Range Tree into the final set of ranges that it compresses
--   down to. Use this whenever you want to finally evaluate your
--   constructed Range Tree.
evaluate :: (Ord a, Enum a) => RangeTree a -> [Range a]

-- | A Range Tree is a construct that can be built and then efficiently
--   evaluated so that you can compress an entire tree of operations on
--   ranges into a single range quickly. The only purpose of this tree is
--   to allow efficient construction of range operations that can be
--   evaluated as is required.
data RangeTree a

-- | Combine two range trees together with a single operation
RangeNode :: RangeOperation -> (RangeTree a) -> (RangeTree a) -> RangeTree a

-- | Invert a range tree, this is a <a>not</a> operation.
RangeNodeInvert :: (RangeTree a) -> RangeTree a

-- | A leaf with a set of ranges that are collected together.
RangeLeaf :: [Range a] -> RangeTree a

-- | These are the operations that can join two disjunct lists of ranges
--   together.
data RangeOperation

-- | Represents the set union operation.
RangeUnion :: RangeOperation

-- | Represents the set intersection operation.
RangeIntersection :: RangeOperation

-- | Represents the set difference operation.
RangeDifference :: RangeOperation


-- | This entire library is concerned with ranges and this module
--   implements the absolute basic range functions.
module Data.Range.Range

-- | The Range Data structure; it is capable of representing any type of
--   range. This is the primary data structure in this library. Everything
--   should be possible to convert back into this datatype. All ranges in
--   this structure are inclusively bound.
data Range a

-- | Represents a single element as a range.
SingletonRange :: a -> Range a

-- | Represents a bounded and inclusive range of elements.
SpanRange :: a -> a -> Range a

-- | Represents a range with only an inclusive lower bound.
LowerBoundRange :: a -> Range a

-- | Represents a range with only an inclusive upper bound.
UpperBoundRange :: a -> Range a

-- | Represents an infinite range over all values.
InfiniteRange :: Range a

-- | Given a range and a value it will tell you wether or not the value is
--   in the range. Remember that all ranges are inclusive.
inRange :: (Ord a) => Range a -> a -> Bool

-- | Given a list of ranges this function tells you if a value is in any of
--   those ranges. This is especially useful for more complex ranges.
inRanges :: (Ord a) => [Range a] -> a -> Bool

-- | A check to see if two ranges overlap. If they do then true is
--   returned; false otherwise.
rangesOverlap :: (Ord a) => Range a -> Range a -> Bool

-- | When you create a range there may be overlaps in your ranges. However,
--   for the sake of efficiency you probably want the list of ranges with
--   no overlaps. The mergeRanges function takes a set of ranges and
--   returns the same set specified by the minimum number of Range objects.
--   A useful function for cleaning up your ranges. Please note that, if
--   you use any of the other operations on sets of ranges like invert,
--   union and intersection then this is automatically done for you. Which
--   means that a function like this is redundant: mergeRanges .
--   intersection
mergeRanges :: (Ord a, Enum a) => [Range a] -> [Range a]

-- | An inversion function, given a set of ranges it returns the inverse
--   set of ranges.
invert :: (Ord a, Enum a) => [Range a] -> [Range a]

-- | Performs a set union between the two input ranges and returns the
--   resultant set of ranges.
union :: (Ord a, Enum a) => [Range a] -> [Range a] -> [Range a]

-- | Performs a set intersection between the two input ranges and returns
--   the resultant set of ranges.
intersection :: (Ord a, Enum a) => [Range a] -> [Range a] -> [Range a]

-- | Performs a set difference between the two input ranges and returns the
--   resultant set of ranges.
difference :: (Ord a, Enum a) => [Range a] -> [Range a] -> [Range a]

-- | A set of ranges represents a collection of real values without
--   actually instantiating those values. This allows you to have infinite
--   ranges. However, sometimes you wish to actually get the values that
--   your range represents, or even get a sample set of the values. This
--   function generates as many of the values that belong to your range as
--   you like.
fromRanges :: (Ord a, Enum a) => [Range a] -> [a]


-- | It should not be unexpected that you will be given a string
--   representation of some ranges and you will need to parse them so that
--   you can then do some further processing. This parser exists in order
--   to make the most common forms of range strings easy to parse. It does
--   not cover all cases however but you should not be too worried about
--   that because you should be able to write your own parser using parsec
--   or Alex/Happy and then you can convert everything that you parse into
--   a RangeTree object for easier processing.
module Data.Range.Parser

-- | Given a string this function will either return a parse error back to
--   the user or the list of ranges that are represented by the parsed
--   string.
parseRanges :: (Read a) => String -> Either ParseError [Range a]

-- | Given the parser arguments this returns a parser that is capable of
--   parsing a list of ranges.
ranges :: (Read a) => RangeParserArgs -> Parser [Range a]

-- | The arguments that are used, and can be modified, while parsing a
--   standard range string.
data RangeParserArgs
Args :: String -> String -> String -> RangeParserArgs

-- | A separator that represents a union.
[unionSeparator] :: RangeParserArgs -> String

-- | A separator that separates the two halves of a range.
[rangeSeparator] :: RangeParserArgs -> String

-- | A separator that implies an unbounded range.
[wildcardSymbol] :: RangeParserArgs -> String

-- | These are the default arguments that are used by the parser. Please
--   feel free to use the default arguments for you own parser and modify
--   it from the defaults at will.
defaultArgs :: RangeParserArgs
instance GHC.Show.Show Data.Range.Parser.RangeParserArgs


-- | Nested Ranges are common in practical usage. They appear in such forms
--   as library version numbers ("Version 1.4.5.6" for example). And it is
--   very useful to be able to compare these ranges to one another. This
--   module exists for the purpose of allowing these comparisons between
--   nested ranges. The module builds upon the basic range concept from
--   other parts of this library.
module Data.Range.NestedRange

-- | The Nested Range is a structure that in a nested form of many ranges
--   where there can be multiple ranges at every level.
data NestedRange a
NestedRange :: [[Range a]] -> NestedRange a

-- | Given a list of nested values and a nested range tell us wether the
--   nested value exists inside the nested range.
inNestedRange :: Ord a => [a] -> NestedRange a -> Bool