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


-- | An efficient and versatile range library.
--   
--   The range library alows the use of performant and versatile ranges in
--   your code. It supports bounded and unbounded ranges, ranges in a
--   nested manner (like library versions), an efficient algebra of range
--   computation and even a simplified interface for ranges for the common
--   cases. This library is far more efficient than using the default
--   Data.List functions to approximate range behaviour. Performance is the
--   major value offering of this library. If this is your first time using
--   this library it is highly recommended that you start with
--   <a>Data.Range</a>; it contains the basics of this library that meet
--   most use cases.
@package range
@version 1.0.0.0


-- | Internally the range library converts your ranges into an internal
--   efficient representation. When you perform multiple unions and
--   intersections in a row, converting to and from that representation on
--   every step is extra work. The <tt>RangeExpr</tt> algebra amortises
--   this cost: build a tree of operations first, then evaluate the whole
--   tree in one pass.
--   
--   <b>When to use this module:</b> Build a <a>RangeExpr</a> when you are
--   combining three or more operations in a pipeline, or when you want to
--   evaluate the same expression against multiple targets (e.g. both
--   <a>Ranges</a> and <tt>a -&gt; <a>Bool</a></tt>). A single <tt>union a
--   b</tt> is no faster through the algebra than a direct call.
--   
--   <b>Note:</b> This module is based on F-Algebras. If you have never
--   encountered them before, see <a>this introduction</a> from the School
--   of Haskell.
--   
--   <h2>Examples</h2>
--   
--   Evaluate to a <a>Ranges</a> value (the typical use):
--   
--   <pre>
--   import qualified Data.Range.Algebra as A
--   import Data.Ranges
--   
--   expr :: A.RangeExpr (Ranges Integer)
--   expr = A.invert (A.const (SingletonRange 5))
--   
--   A.eval expr :: Ranges Integer
--   -- Ranges [ube 4,lbi 6]
--   </pre>
--   
--   Evaluate the same expression as a predicate (no intermediate structure
--   built):
--   
--   <pre>
--   import qualified Data.Range.Algebra as A
--   import Data.Ranges
--   
--   let expr = A.union (A.const (1 +=+ 10)) (A.const (20 +=+ 30)) :: A.RangeExpr (Ranges Integer)
--   A.eval (fmap inRanges expr) 25  -- True
--   A.eval (fmap inRanges expr) 15  -- False
--   </pre>
module Data.Range.Algebra

-- | An expression tree representing a sequence of set operations on
--   ranges. Construct trees with <a>const</a>, <a>union</a>,
--   <a>intersection</a>, <a>difference</a>, and <a>invert</a>, then
--   collapse the tree with <a>eval</a>.
--   
--   The type parameter <tt>a</tt> is the range representation the tree
--   will eventually evaluate to (e.g. <tt>[<a>Range</a> Integer]</tt> or
--   <tt>Integer -&gt; <a>Bool</a></tt>).
--   
--   <tt>RangeExpr</tt> is a <a>Functor</a>, so you can map over the leaf
--   values before evaluation.
data RangeExpr a

-- | Lifts a value as a constant leaf into an expression tree.
--   
--   Note: this function shadows <a>const</a>. The
--   <a>Data.Range.Algebra</a> module uses <tt>import Prelude hiding
--   (const)</tt>; callers that import both should qualify.
const :: a -> RangeExpr a

-- | Wraps an expression in a set-complement (invert) node. When evaluated,
--   produces all values <i>not</i> covered by the inner expression. Note
--   that <tt><a>invert</a> . <a>invert</a> == <a>id</a></tt>.
invert :: RangeExpr a -> RangeExpr a

-- | Wraps two expressions in a set-union node. When evaluated, produces
--   all values covered by either expression.
union :: RangeExpr a -> RangeExpr a -> RangeExpr a

-- | Wraps two expressions in a set-intersection node. When evaluated,
--   produces only values covered by both expressions.
intersection :: RangeExpr a -> RangeExpr a -> RangeExpr a

-- | Wraps two expressions in a set-difference node. When evaluated,
--   produces values in the first expression that are absent from the
--   second.
difference :: RangeExpr a -> RangeExpr a -> RangeExpr a

-- | The type of an evaluation function for a <a>RangeExpr</a>. You will
--   not normally need to reference this alias directly; it exists to
--   express the signature of <a>eval</a>.
--   
--   Concretely, <tt>Algebra f a = f a -&gt; a</tt>, meaning: given a
--   functor <tt>f</tt> applied to an already-evaluated <tt>a</tt>, produce
--   the final <tt>a</tt>. The <a>iter</a> function from the <tt>free</tt>
--   package drives the bottom-up fold.
type Algebra (f :: Type -> Type) a = f a -> a

-- | A type class for types that a <a>RangeExpr</a> can be evaluated to.
--   Three instances are provided out of the box; additional targets can be
--   added by implementing this class.
class RangeAlgebra a

-- | Collapses a <a>RangeExpr</a> tree into its target representation by
--   evaluating every node bottom-up. Three evaluation targets are
--   supported:
--   
--   <ul>
--   <li><a>Ranges</a> <tt>a</tt> — canonical, indexed set with pre-built
--   membership predicate. The primary target for user code; instance
--   defined in <a>Data.Ranges</a>.</li>
--   <li><tt>[<a>Range</a> a]</tt> — a merged, canonical list. Used
--   internally and useful when you need to inspect individual ranges.</li>
--   <li><tt>a -&gt; <a>Bool</a></tt> — a membership predicate; no
--   intermediate structure built.</li>
--   </ul>
eval :: RangeAlgebra a => Algebra RangeExpr a
instance Data.Range.Algebra.RangeAlgebra (a -> GHC.Types.Bool)
instance GHC.Classes.Ord a => Data.Range.Algebra.RangeAlgebra [Data.Range.Data.Range a]


-- | Ordering newtypes for <a>Range</a>.
--   
--   <a>Range</a> deliberately has no <a>Ord</a> instance because there is
--   no single natural ordering — the right choice depends on the use case.
--   This module provides two explicit wrappers:
--   
--   <ul>
--   <li><a>KeyRange</a> — a consistent structural ordering, suitable for
--   use as a <a>Map</a> key or in a <a>Set</a>.</li>
--   <li><a>SortedRange</a> — a positional ordering by location on the
--   number line, suitable for sorting ranges for display.</li>
--   </ul>
--   
--   <h2>Example: Map keyed on ranges</h2>
--   
--   <pre>
--   import Data.Range (Range, (+=+), lbi)
--   import Data.Range.Ord (KeyRange(..))
--   import qualified Data.Map.Strict as Map
--   
--   type RuleMap = Map (KeyRange Integer) String
--   
--   rules :: RuleMap
--   rules = Map.fromList
--     [ (KeyRange (1 +=+ 10),  "low")
--     , (KeyRange (11 +=+ 50), "medium")
--     , (KeyRange (lbi 51),    "high")
--     ]
--   </pre>
--   
--   <h2>Example: sorting ranges by position on the number line</h2>
--   
--   <pre>
--   import Data.List (sortOn)
--   import Data.Range (Range, (+=+), lbi, ube)
--   import Data.Range.Ord (SortedRange(..))
--   
--   sortOn SortedRange [lbi 10, 1 +=+ 5, ube 0 :: Range Integer]
--   -- [ube 0, 1 +=+ 5, lbi 10]
--   
--   -- or equivalently:
--   displayRanges :: Ord a =&gt; [Range a] -&gt; [Range a]
--   displayRanges = sortOn SortedRange
--   </pre>
module Data.Range.Ord

-- | Wraps <a>Range</a> with a structural <a>Ord</a> instance, suitable for
--   use as a <a>Map</a> key or in a <a>Set</a>.
--   
--   Constructor order: <tt>SingletonRange &lt; SpanRange &lt;
--   LowerBoundRange &lt; UpperBoundRange &lt; InfiniteRange</tt>. Fields
--   within the same constructor are compared lexicographically.
--   
--   This ordering is not semantically meaningful on the number line —
--   <tt>SingletonRange 5</tt> and <tt>SpanRange (Bound 5 Inclusive) (Bound
--   5 Inclusive)</tt> are considered distinct. It is only appropriate
--   where any consistent total order will do (deduplication, <a>Map</a>
--   keys).
--   
--   Use <a>unKeyRange</a> to unwrap the underlying <a>Range</a>.
--   
--   See also <a>SortedRange</a> for ordering by position on the number
--   line.
newtype KeyRange a
KeyRange :: Range a -> KeyRange a
[unKeyRange] :: KeyRange a -> Range a

-- | Wraps <a>Range</a> with a positional <a>Ord</a> instance: ranges are
--   ordered by where they sit on the number line, lower bound first with
--   upper bound as a tiebreaker.
--   
--   The <a>Eq</a> instance is consistent with <a>Ord</a>: two
--   <a>SortedRange</a> values are equal iff they have the same lower and
--   upper bounds. This means <tt>SortedRange (SingletonRange 5)</tt> and
--   <tt>SortedRange (5 +=+ 5)</tt> are considered equal (they occupy the
--   same point on the number line).
--   
--   Use <a>unSortedRange</a> to unwrap the underlying <a>Range</a>.
--   Typical usage:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.List (sortOn)
--   
--   &gt;&gt;&gt; sortOn SortedRange [SingletonRange 5, SingletonRange 1, SingletonRange 3 :: Range Integer]
--   [SingletonRange 1,SingletonRange 3,SingletonRange 5]
--   </pre>
--   
--   See also <a>KeyRange</a> for a structural ordering suitable for
--   <a>Map</a> keys.
newtype SortedRange a
SortedRange :: Range a -> SortedRange a
[unSortedRange] :: SortedRange a -> Range a
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Range.Ord.KeyRange a)
instance GHC.Classes.Ord a => GHC.Classes.Eq (Data.Range.Ord.SortedRange a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Range.Ord.KeyRange a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Range.Ord.SortedRange a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Range.Ord.KeyRange a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Range.Ord.SortedRange a)


-- | The primary interface to the range library.
--   
--   A <a>Range</a> describes a membership set over any <a>Ord</a> type.
--   This module provides the <a>Ranges</a> type — a canonicalised, indexed
--   collection of <a>Range</a> values — along with construction operators,
--   set operations, and membership predicates.
--   
--   <h1>Quick start</h1>
--   
--   Build ranges with the construction operators and combine them with
--   <tt>(<a>&lt;&gt;</a>)</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; (1 +=+ 5 :: Ranges Integer) &lt;&gt; (3 +=+ 8)
--   Ranges [1 +=+ 8]
--   </pre>
--   
--   Test membership:
--   
--   <pre>
--   &gt;&gt;&gt; inRanges (1 +=+ 10 &lt;&gt; 20 +=+ 30 :: Ranges Integer) 5
--   True
--   
--   &gt;&gt;&gt; inRanges (1 +=+ 10 &lt;&gt; 20 +=+ 30 :: Ranges Integer) 15
--   False
--   </pre>
--   
--   Use <a>mconcat</a> to build from a list:
--   
--   <pre>
--   &gt;&gt;&gt; mconcat [1 +=+ 5, 10 +=+ 15, 12 +=+ 20 :: Ranges Integer]
--   Ranges [1 +=+ 5,10 +=+ 20]
--   </pre>
--   
--   <h1>Transforming ranges</h1>
--   
--   <a>Ranges</a> does not implement <a>Functor</a>. Mapping a function
--   over boundary values is not a well-defined operation for half-infinite
--   ranges: an order-reversing function like <tt>negate</tt> applied to
--   <a>lbi</a> would need to produce <a>ubi</a>, but <a>Functor</a> cannot
--   express that structural flip.
--   
--   The idiomatic alternative is to <b>map the query value</b>, not the
--   ranges. Instead of converting boundaries to a new domain, convert
--   incoming queries back to the range's domain:
--   
--   <pre>
--   -- Unit conversion: test a Fahrenheit value against Celsius ranges
--   let safeTemp = 20 +=+ 37 :: Ranges Double  -- defined in °C
--   let inSafeTemp f = inRanges safeTemp ((f - 32) * 5 / 9)
--   </pre>
--   
--   This is always correct regardless of whether the conversion is
--   monotone, never requires re-canonicalisation, and avoids the
--   constructor-flip hazard.
--   
--   <h1>Module guide</h1>
--   
--   <ul>
--   <li><a>Data.Ranges</a> — <b>start here</b>. <a>Ranges</a> type, all
--   set operations.</li>
--   <li><a>Data.Range</a> — deprecated re-export shim; use
--   <a>Data.Ranges</a> instead.</li>
--   <li><a>Data.Range.Ord</a> — <a>KeyRange</a> and <a>SortedRange</a> for
--   <a>Ord</a>-requiring contexts.</li>
--   <li><a>Data.Range.Parser</a> — Parsec-based parser for range
--   strings.</li>
--   <li><a>Data.Range.Algebra</a> — F-Algebra for deferred, efficient
--   expression trees.</li>
--   </ul>
module Data.Ranges

-- | 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. <tt>SingletonRange a</tt> is
--   equivalent to <tt>SpanRange (Bound a Inclusive) (Bound a
--   Inclusive)</tt>.
SingletonRange :: a -> Range a

-- | Represents a bounded span of elements. The first argument is expected
--   to be less than or equal to the second argument.
SpanRange :: Bound a -> Bound a -> Range a

-- | Represents a range with a finite lower bound and an infinite upper
--   bound.
LowerBoundRange :: Bound a -> Range a

-- | Represents a range with an infinite lower bound and a finite upper
--   bound.
UpperBoundRange :: Bound a -> Range a

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

-- | Represents a bound at a particular value with a <a>BoundType</a>.
--   There is no implicit understanding if this is a lower or upper bound,
--   it could be either.
data Bound a
Bound :: a -> BoundType -> Bound a

-- | The value at the edge of this bound.
[boundValue] :: Bound a -> a

-- | The type of bound. Should be <a>Inclusive</a> or <a>Exclusive</a>.
[boundType] :: Bound a -> BoundType

-- | Represents a type of boundary.
data BoundType

-- | The value at the boundary should be included in the bound.
Inclusive :: BoundType

-- | The value at the boundary should be excluded in the bound.
Exclusive :: BoundType

-- | A set of ranges represented as a merged, canonical list of
--   non-overlapping <a>Range</a> values, with pre-built O(log n)
--   membership, O(1) above, and O(1) below predicates.
--   
--   Construct values with the operators (<a>+=+</a>, <a>lbi</a>, etc.) or
--   with <a>mergeRanges</a>. Combine with <tt>(<a>&lt;&gt;</a>)</tt> or
--   <a>mconcat</a>.
--   
--   <b>Semigroup</b>: <tt>(<a>&lt;&gt;</a>)</tt> computes the set union
--   and merges the result into canonical form.
--   
--   <pre>
--   &gt;&gt;&gt; (1 +=+ 5 :: Ranges Integer) &lt;&gt; (3 +=+ 8)
--   Ranges [1 +=+ 8]
--   </pre>
--   
--   <b>Monoid</b>: <a>mempty</a> is the empty set. <a>mconcat</a> merges
--   an entire list in a single pass, more efficiently than repeated
--   <tt>(<a>&lt;&gt;</a>)</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; mconcat [1 +=+ 5, 10 +=+ 15, 12 +=+ 20 :: Ranges Integer]
--   Ranges [1 +=+ 5,10 +=+ 20]
--   </pre>
--   
--   Use <a>unRanges</a> to extract the underlying list.
data Ranges a

-- | Mathematically equivalent to <tt>[x, y]</tt>. See <a>SpanRange</a> for
--   the underlying constructor.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +=+ 5 :: Ranges Integer
--   Ranges [1 +=+ 5]
--   </pre>
(+=+) :: Ord a => a -> a -> Ranges a

-- | Mathematically equivalent to <tt>[x, y)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; 1 +=* 5 :: Ranges Integer
--   Ranges [1 +=* 5]
--   </pre>
(+=*) :: Ord a => a -> a -> Ranges a

-- | Mathematically equivalent to <tt>(x, y]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; 1 *=+ 5 :: Ranges Integer
--   Ranges [1 *=+ 5]
--   </pre>
(*=+) :: Ord a => a -> a -> Ranges a

-- | Mathematically equivalent to <tt>(x, y)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; 1 *=* 5 :: Ranges Integer
--   Ranges [1 *=* 5]
--   </pre>
(*=*) :: Ord a => a -> a -> Ranges a

-- | Mathematically equivalent to <tt>[x, ∞)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; lbi 5 :: Ranges Integer
--   Ranges [lbi 5]
--   </pre>
lbi :: Ord a => a -> Ranges a

-- | Mathematically equivalent to <tt>(x, ∞)</tt>.
lbe :: Ord a => a -> Ranges a

-- | Mathematically equivalent to <tt>(−∞, x]</tt>.
ubi :: Ord a => a -> Ranges a

-- | Mathematically equivalent to <tt>(−∞, x)</tt>.
ube :: Ord a => a -> Ranges a

-- | The infinite range, covering all values.
inf :: Ord a => Ranges a

-- | Returns <a>True</a> if the value falls within the single range.
--   Respects <a>Inclusive</a> and <a>Exclusive</a> bounds.
--   
--   See <a>inRanges</a> for testing against a <a>Ranges</a> collection.
--   
--   <pre>
--   &gt;&gt;&gt; inRange (SpanRange (Bound 1 Inclusive) (Bound 10 Inclusive)) (5 :: Integer)
--   True
--   
--   &gt;&gt;&gt; inRange (SpanRange (Bound 1 Inclusive) (Bound 10 Exclusive)) (10 :: Integer)
--   False
--   </pre>
inRange :: Ord a => Range a -> a -> Bool

-- | Returns <a>True</a> if the value is strictly above (greater than the
--   upper bound of) the given range.
--   
--   <pre>
--   &gt;&gt;&gt; aboveRange (SpanRange (Bound 1 Inclusive) (Bound 5 Inclusive)) (6 :: Integer)
--   True
--   
--   &gt;&gt;&gt; aboveRange (LowerBoundRange (Bound 0 Inclusive)) (6 :: Integer)
--   False
--   </pre>
aboveRange :: Ord a => Range a -> a -> Bool

-- | Returns <a>True</a> if the value is strictly below (less than the
--   lower bound of) the given range.
--   
--   <pre>
--   &gt;&gt;&gt; belowRange (SpanRange (Bound 1 Inclusive) (Bound 5 Inclusive)) (0 :: Integer)
--   True
--   
--   &gt;&gt;&gt; belowRange (UpperBoundRange (Bound 6 Inclusive)) (0 :: Integer)
--   False
--   </pre>
belowRange :: Ord a => Range a -> a -> Bool

-- | Returns <a>True</a> if two ranges share at least one value.
--   
--   <pre>
--   &gt;&gt;&gt; rangesOverlap (SpanRange (Bound 1 Inclusive) (Bound 5 Inclusive)) (SpanRange (Bound 3 Inclusive) (Bound 7 Inclusive) :: Range Integer)
--   True
--   
--   &gt;&gt;&gt; rangesOverlap (SpanRange (Bound 1 Inclusive) (Bound 5 Exclusive)) (SpanRange (Bound 5 Inclusive) (Bound 7 Inclusive) :: Range Integer)
--   False
--   </pre>
rangesOverlap :: Ord a => Range a -> Range a -> Bool

-- | Returns <a>True</a> if two ranges touch at a single exclusive boundary
--   but share no values.
--   
--   <pre>
--   &gt;&gt;&gt; rangesAdjoin (SpanRange (Bound 1 Inclusive) (Bound 5 Exclusive)) (SpanRange (Bound 5 Inclusive) (Bound 7 Inclusive) :: Range Integer)
--   True
--   
--   &gt;&gt;&gt; rangesAdjoin (SpanRange (Bound 1 Inclusive) (Bound 5 Inclusive)) (SpanRange (Bound 3 Inclusive) (Bound 7 Inclusive) :: Range Integer)
--   False
--   </pre>
rangesAdjoin :: Ord a => Range a -> Range a -> Bool

-- | Returns <a>True</a> if the value falls within any of the given ranges.
--   
--   The membership predicate is pre-built when the <a>Ranges</a> value is
--   constructed, so each call is O(log n) in the number of spans. Partial
--   application is idiomatic:
--   
--   <pre>
--   let memberOf = inRanges myRanges
--   filter memberOf largeList
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; inRanges (1 +=+ 10 &lt;&gt; 20 +=+ 30 :: Ranges Integer) 5
--   True
--   
--   &gt;&gt;&gt; inRanges (1 +=+ 10 &lt;&gt; 20 +=+ 30 :: Ranges Integer) 15
--   False
--   </pre>
inRanges :: Ord a => Ranges a -> a -> Bool

-- | Returns <a>True</a> if the value is strictly above all of the given
--   ranges.
--   
--   This predicate is O(1): the answer is determined by the last element
--   of the canonical range list (which has the largest upper bound),
--   cached at construction time.
--   
--   <pre>
--   &gt;&gt;&gt; aboveRanges (1 +=+ 5 &lt;&gt; 10 +=+ 15 :: Ranges Integer) 20
--   True
--   
--   &gt;&gt;&gt; aboveRanges (1 +=+ 5 &lt;&gt; lbi 10 :: Ranges Integer) 20
--   False
--   </pre>
aboveRanges :: Ord a => Ranges a -> a -> Bool

-- | Returns <a>True</a> if the value is strictly below all of the given
--   ranges.
--   
--   This predicate is O(1): the answer is determined by the first element
--   of the canonical range list (which has the smallest lower bound),
--   cached at construction time.
--   
--   <pre>
--   &gt;&gt;&gt; belowRanges (5 +=+ 10 &lt;&gt; 20 +=+ 30 :: Ranges Integer) 1
--   True
--   
--   &gt;&gt;&gt; belowRanges (ubi 10 &lt;&gt; 20 +=+ 30 :: Ranges Integer) 1
--   False
--   </pre>
belowRanges :: Ord a => Ranges a -> a -> Bool

-- | Canonicalise a raw list of <a>Range</a> values into a <a>Ranges</a>.
--   Overlapping ranges are merged; the result is sorted and
--   non-overlapping.
--   
--   <pre>
--   &gt;&gt;&gt; mergeRanges [LowerBoundRange (Bound 12 Inclusive), SpanRange (Bound 1 Inclusive) (Bound 10 Inclusive), SpanRange (Bound 5 Inclusive) (Bound 15 Inclusive) :: Range Integer]
--   Ranges [lbi 1]
--   </pre>
mergeRanges :: Ord a => [Range a] -> Ranges a

-- | Set union. Equivalent to <tt>(<a>&lt;&gt;</a>)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; union (1 +=+ 10) (5 +=+ 15 :: Ranges Integer)
--   Ranges [1 +=+ 15]
--   </pre>
union :: Ord a => Ranges a -> Ranges a -> Ranges a

-- | Set intersection. Returns only values present in both.
--   
--   <pre>
--   &gt;&gt;&gt; intersection (1 +=+ 10) (5 +=+ 15 :: Ranges Integer)
--   Ranges [5 +=+ 10]
--   </pre>
intersection :: Ord a => Ranges a -> Ranges a -> Ranges a

-- | Set difference: values in the first <a>Ranges</a> not in the second.
--   
--   <pre>
--   &gt;&gt;&gt; difference (1 +=+ 10) (5 +=+ 15 :: Ranges Integer)
--   Ranges [1 +=* 5]
--   </pre>
difference :: Ord a => Ranges a -> Ranges a -> Ranges a

-- | Complement: all values <i>not</i> covered by the given <a>Ranges</a>.
--   <tt><a>invert</a> . <a>invert</a> == <a>id</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; invert (1 +=* 10 &lt;&gt; 15 *=+ 20 :: Ranges Integer)
--   Ranges [ube 1,10 +=+ 15,lbe 20]
--   </pre>
invert :: Ord a => Ranges a -> Ranges a

-- | Instantiate all values covered by the ranges as a list.
--   <b>Warning:</b> not efficient. Prefer <a>inRanges</a> for membership
--   tests. Combine with <a>take</a> to avoid evaluating infinite ranges.
--   
--   <pre>
--   &gt;&gt;&gt; take 5 . fromRanges $ (1 +=+ 10 :: Ranges Integer)
--   [1,2,3,4,5]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; take 6 . fromRanges $ (1 +=+ 3 :: Ranges Integer) &lt;&gt; (10 +=+ 12)
--   [1,10,2,11,3,12]
--   </pre>
fromRanges :: (Ord a, Enum a) => Ranges a -> [a]

-- | Join adjacent ranges that are contiguous for <a>Enum</a> types. For
--   example, <tt>[1 +=+ 5, 6 +=+ 10]</tt> collapses to <tt>[1 +=+ 10]</tt>
--   for <a>Integer</a> because there is no integer between 5 and 6.
--   
--   <pre>
--   &gt;&gt;&gt; joinRanges (mconcat [1 +=+ 5, 6 +=+ 10] :: Ranges Integer)
--   Ranges [1 +=+ 10]
--   </pre>
joinRanges :: (Ord a, Enum a) => Ranges a -> Ranges a
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Ranges.Ranges a)
instance GHC.Classes.Ord a => GHC.Base.Monoid (Data.Ranges.Ranges a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Ranges.Ranges a)
instance GHC.Classes.Ord a => Data.Range.Algebra.RangeAlgebra (Data.Ranges.Ranges a)
instance GHC.Classes.Ord a => GHC.Base.Semigroup (Data.Ranges.Ranges a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Ranges.Ranges a)


-- | A simple parser for human-readable range strings, designed for CLI
--   programs.
--   
--   By default, ranges are separated by commas and span endpoints by a
--   hyphen:
--   
--   <pre>
--   &gt;&gt;&gt; parseRanges "-5,8-10,13-15,20-" :: Either ParseError (Ranges Integer)
--   Right (Ranges [ubi 5,8 +=+ 10,13 +=+ 15,lbi 20])
--   </pre>
--   
--   The <tt>*</tt> wildcard produces an infinite range:
--   
--   <pre>
--   &gt;&gt;&gt; parseRanges "*" :: Either ParseError (Ranges Integer)
--   Right (Ranges [inf])
--   </pre>
--   
--   Use <a>customParseRanges</a> to change the separator characters:
--   
--   <pre>
--   &gt;&gt;&gt; let args = defaultArgs { unionSeparator = ";", rangeSeparator = ".." }
--   
--   &gt;&gt;&gt; customParseRanges args "1..5;10" :: Either ParseError (Ranges Integer)
--   Right (Ranges [1 +=+ 5,SingletonRange 10])
--   </pre>
--   
--   <b>Known limitations:</b>
--   
--   <ul>
--   <li>Only non-negative integer literals are recognised. The input
--   <tt>"-5"</tt> is parsed as <tt>UpperBoundRange 5</tt> (an
--   upper-bounded range), not <tt>SingletonRange (-5)</tt>. For negative
--   values, use <a>customParseRanges</a> with a different
--   <a>rangeSeparator</a>, or pre-process the input string.</li>
--   <li>Unrecognised input is silently consumed as an empty set rather
--   than producing a parse error. For example, <tt>parseRanges "abc"</tt>
--   returns <tt>Right mempty</tt>. This is a consequence of using
--   <a>sepBy</a> internally and is by design for CLI use where partial
--   input is common.</li>
--   </ul>
--   
--   For more complex parsing (e.g. <tt>.cabal</tt> or
--   <tt>package.json</tt> files), parse version strings with Parsec or
--   Alex/Happy and convert the results into <a>Range</a> values directly,
--   then call <a>mergeRanges</a>.
module Data.Range.Parser

-- | Parses a range string using the default separators (<tt>,</tt> and
--   <tt>-</tt>). Returns either a <a>ParseError</a> or a canonicalised
--   <a>Ranges</a> value ready for membership testing and set operations.
--   
--   The <a>Read</a> instance of <tt>a</tt> is used to parse individual
--   numeric literals, so the type must have a well-behaved <a>Read</a>.
--   Exotic types with unusual <a>Read</a> instances may not parse
--   correctly.
--   
--   See the module documentation for known limitations around negative
--   numbers and unrecognised input.
parseRanges :: (Read a, Ord a) => String -> Either ParseError (Ranges a)

-- | Like <a>parseRanges</a> but with caller-supplied separator
--   configuration. Use this when the default <tt>,</tt> and <tt>-</tt>
--   characters conflict with your input format.
--   
--   <pre>
--   &gt;&gt;&gt; let args = defaultArgs { unionSeparator = ";", rangeSeparator = ".." }
--   
--   &gt;&gt;&gt; customParseRanges args "1..5;10" :: Either ParseError (Ranges Integer)
--   Right (Ranges [1 +=+ 5,SingletonRange 10])
--   </pre>
customParseRanges :: (Read a, Ord a) => RangeParserArgs -> String -> Either ParseError (Ranges a)

-- | Configuration for the range parser. All three fields are plain
--   strings, so multi-character separators (e.g. <tt>".."</tt>) are
--   supported.
data RangeParserArgs
Args :: String -> String -> String -> RangeParserArgs

-- | Separates multiple ranges in a union. Default: <tt>","</tt>.
[unionSeparator] :: RangeParserArgs -> String

-- | Separates the two endpoints of a span. Default: <tt>"-"</tt>.
[rangeSeparator] :: RangeParserArgs -> String

-- | Symbol for an infinite range. Default: <tt>"*"</tt>.
[wildcardSymbol] :: RangeParserArgs -> String

-- | The default parser configuration: comma-separated ranges,
--   hyphen-separated endpoints, and <tt>*</tt> as the wildcard. Modify
--   individual fields with record syntax:
--   
--   <pre>
--   &gt;&gt;&gt; defaultArgs { unionSeparator = ";", rangeSeparator = ".." }
--   Args {unionSeparator = ";", rangeSeparator = "..", wildcardSymbol = "*"}
--   </pre>
defaultArgs :: RangeParserArgs

-- | Returns a Parsec <a>Parser</a> for a list of ranges using the given
--   configuration. Use this when embedding range parsing into a larger
--   Parsec grammar; for standalone parsing prefer <a>parseRanges</a> or
--   <a>customParseRanges</a>.
--   
--   The returned list is unmerged — call <a>mergeRanges</a> on the result
--   to produce a canonical <a>Ranges</a> value.
ranges :: Read a => RangeParserArgs -> Parser [Range a]
data ParseError
instance GHC.Show.Show Data.Range.Parser.RangeParserArgs


-- | <b>Deprecated.</b> Import <a>Data.Ranges</a> instead.
--   
--   This module is a re-export shim kept for backwards compatibility. All
--   types and functions are now in <a>Data.Ranges</a>.

-- | <i>Deprecated: Import Data.Ranges instead of Data.Range.</i>
module Data.Range
