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


-- | Non-empty variants of containers data types, with full API
--   
--   Efficient and optimized non-empty versions of types from
--   <i>containers</i>. Inspired by <i>non-empty-containers</i> library,
--   except attempting a more faithful port (with under-the-hood
--   optimizations) of the full <i>containers</i> API. Also contains a
--   convenient typeclass abstraction for converting betwewen non-empty and
--   possibly-empty variants. See README.md for more information.
@package nonempty-containers
@version 0.3.4.2


-- | Unsafe internal-use functions used in the implementation of
--   <a>Data.IntMap.NonEmpty</a>. These functions can potentially be used
--   to break the abstraction of <a>NEIntMap</a> and produce unsound maps,
--   so be wary!
module Data.IntMap.NonEmpty.Internal

-- | A non-empty (by construction) map from integer keys to values
--   <tt>a</tt>. At least one key-value pair exists in an
--   <tt><a>NEIntMap</a> v</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NEIntMap</a> can safely operate on it
--   with the assumption that it has at least one key-value pair.
--   
--   Functions that <i>return</i> an <a>NEIntMap</a> provide an assurance
--   that the result has at least one key-value pair.
--   
--   <a>Data.IntMap.NonEmpty</a> re-exports the API of <a>Data.IntMap</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output maps are both
--   non-empty (like <a>insert</a>) return <a>NEIntMap</a>, but functions
--   that might potentially return an empty map (like <a>delete</a>) return
--   a <a>IntMap</a> instead.
--   
--   You can directly construct an <a>NEIntMap</a> with the API from
--   <a>Data.IntMap.NonEmpty</a>; it's more or less the same as
--   constructing a normal <a>IntMap</a>, except you don't have access to
--   <a>empty</a>. There are also a few ways to construct an
--   <a>NEIntMap</a> from a <a>IntMap</a>:
--   
--   <ol>
--   <li>The <a>nonEmptyMap</a> smart constructor will convert a
--   <tt><a>IntMap</a> k a</tt> into a <tt><a>Maybe</a> (<a>NEIntMap</a> k
--   a)</tt>, returning <a>Nothing</a> if the original <a>IntMap</a> was
--   empty.</li>
--   <li>You can use the <a>insertIntMap</a> family of functions to insert
--   a value into a <a>IntMap</a> to create a guaranteed
--   <a>NEIntMap</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>IntMap</a> to reveal it as either containing a
--   <a>NEIntMap</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>IntMap</a> and treating it as if it were an
--   <a>NEIntMap</a>.</li>
--   </ol>
--   
--   You can convert an <a>NEIntMap</a> into a <a>IntMap</a> with
--   <a>toMap</a> or <a>IsNonEmpty</a>, essentially "obscuring" the
--   non-empty property from the type.
data NEIntMap a
NEIntMap :: !Key -> a -> !IntMap a -> NEIntMap a

-- | invariant: must be smaller than smallest key in map
[neimK0] :: NEIntMap a -> !Key
[neimV0] :: NEIntMap a -> a
[neimIntMap] :: NEIntMap a -> !IntMap a
type Key = Int

-- | <i>O(1)</i>. A map with a single element.
--   
--   <pre>
--   singleton 1 'a'        == fromList ((1, 'a') :| [])
--   size (singleton 1 'a') == 1
--   </pre>
singleton :: Key -> a -> NEIntMap a

-- | <i>O(log n)</i>. Smart constructor for an <a>NEIntMap</a> from a
--   <a>IntMap</a>. Returns <a>Nothing</a> if the <a>IntMap</a> was
--   originally actually empty, and <tt><a>Just</a> n</tt> with an
--   <a>NEIntMap</a>, if the <a>IntMap</a> was not empty.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>IntMap</a> being an <a>NEIntMap</a>.
--   
--   <pre>
--   nonEmptyMap (Data.IntMap.fromList [(3,"a"), (5,"b")]) == Just (fromList ((3,"a") :| [(5,"b")]))
--   </pre>
nonEmptyMap :: IntMap a -> Maybe (NEIntMap a)

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>IntMap</a> as if it were an <a>NEIntMap</a>.
--   <tt><a>withNonEmpty</a> def f</tt> will take a <a>IntMap</a>. If map
--   is empty, it will evaluate to <tt>def</tt>. Otherwise, a non-empty map
--   <a>NEIntMap</a> will be fed to the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptyMap</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NEIntMap a -> r) -> IntMap a -> r

-- | <i>O(n*log n)</i>. Build a non-empty map from a non-empty list of
--   key/value pairs. See also <a>fromAscList</a>. If the list contains
--   more than one value for the same key, the last value for the key is
--   retained.
--   
--   <pre>
--   fromList ((5,"a") :| [(3,"b"), (5, "c")]) == fromList ((5,"c") :| [(3,"b")])
--   fromList ((5,"c") :| [(3,"b"), (5, "a")]) == fromList ((5,"a") :| [(3,"b")])
--   </pre>
fromList :: NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n)</i>. Convert the map to a non-empty list of key/value pairs.
--   
--   <pre>
--   toList (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
toList :: NEIntMap a -> NonEmpty (Key, a)

-- | <i>O(n)</i>. IntMap a function over all values in the map.
--   
--   <pre>
--   map (++ "x") (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "bx") :| [(5, "ax")])
--   </pre>
map :: (a -> b) -> NEIntMap a -> NEIntMap b

-- | <i>O(log n)</i>. Insert with a function, combining new value and old
--   value. <tt><a>insertWith</a> f key value mp</tt> will insert the pair
--   (key, value) into <tt>mp</tt> if key does not exist in the map. If the
--   key does exist, the function will insert the pair <tt>(key, f
--   new_value old_value)</tt>.
--   
--   See <a>insertIntMapWith</a> for a version where the first argument is
--   a <a>IntMap</a>.
--   
--   <pre>
--   insertWith (++) 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "xxxa")])
--   insertWith (++) 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   </pre>
insertWith :: (a -> a -> a) -> Key -> a -> NEIntMap a -> NEIntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression (<tt><a>union</a>
--   t1 t2</tt>) takes the left-biased union of <tt>t1</tt> and
--   <tt>t2</tt>. It prefers <tt>t1</tt> when duplicate keys are
--   encountered, i.e. (<tt><a>union</a> == <a>unionWith</a>
--   <a>const</a></tt>).
--   
--   <pre>
--   union (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "a"), (7, "C")])
--   </pre>
union :: NEIntMap a -> NEIntMap a -> NEIntMap a

-- | The left-biased union of a non-empty list of maps.
--   
--   <pre>
--   unions (fromList ((5, "a") :| [(3, "b")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "A3") :| [(3, "B3")])])
--       == fromList [(3, "b"), (5, "a"), (7, "C")]
--   unions (fromList ((5, "A3") :| [(3, "B3")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "a") :| [(3, "b")])])
--       == fromList ((3, "B3") :| [(5, "A3"), (7, "C")])
--   </pre>
unions :: Foldable1 f => f (NEIntMap a) -> NEIntMap a

-- | <i>O(n)</i>. Return all elements of the map in the ascending order of
--   their keys.
--   
--   <pre>
--   elems (fromList ((5,"a") :| [(3,"b")])) == ("b" :| ["a"])
--   </pre>
elems :: NEIntMap a -> NonEmpty a

-- | <i>O(1)</i>. The number of elements in the map. Guaranteed to be
--   greater than zero.
--   
--   <pre>
--   size (singleton 1 'a')                          == 1
--   size (fromList ((1,'a') :| [(2,'c'), (3,'b')])) == 3
--   </pre>
size :: NEIntMap a -> Int

-- | <i>O(log n)</i>. Convert a non-empty map back into a normal
--   possibly-empty map, for usage with functions that expect
--   <a>IntMap</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the map in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toMap (fromList ((3,"a") :| [(5,"b")])) == Data.IntMap.fromList [(3,"a"), (5,"b")]
--   </pre>
toMap :: NEIntMap a -> IntMap a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList map = foldr (:) [] map
--   </pre>
--   
--   <pre>
--   let f a len = len + (length a)
--   foldr f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldr :: (a -> b -> b) -> b -> NEIntMap a -> b

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> NEIntMap a -> b

-- | <i>O(n)</i>. A version of <a>foldr</a> that uses the value at the
--   maximal key in the map as the starting value.
--   
--   Note that, unlike <a>foldr1</a> for <a>IntMap</a>, this function is
--   total if the input function is total.
foldr1 :: (a -> a -> a) -> NEIntMap a -> a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList = reverse . foldl (flip (:)) []
--   </pre>
--   
--   <pre>
--   let f len a = len + (length a)
--   foldl f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldl :: (a -> b -> a) -> a -> NEIntMap b -> a

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> NEIntMap b -> a

-- | <i>O(n)</i>. A version of <a>foldl</a> that uses the value at the
--   minimal key in the map as the starting value.
--   
--   Note that, unlike <a>foldl1</a> for <a>IntMap</a>, this function is
--   total if the input function is total.
foldl1 :: (a -> a -> a) -> NEIntMap a -> a

-- | <i>O(n)</i>. <tt><a>traverseWithKey</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt> That is, behaves exactly like a regular
--   <a>traverse</a> except that the traversing function also has access to
--   the key associated with a value.
--   
--   <i>Use <a>traverseWithKey1</a></i> whenever possible (if your
--   <a>Applicative</a> also has <a>Apply</a> instance). This version is
--   provided only for types that do not have <a>Apply</a> instance, since
--   <a>Apply</a> is not at the moment (and might not ever be) an official
--   superclass of <a>Applicative</a>.
--   
--   <b>WARNING</b>: Differs from <tt>Data.IntMap.traverseWithKey</tt>,
--   which traverses positive items first, then negative items.
--   
--   <pre>
--   <a>traverseWithKey</a> f = <a>unwrapApplicative</a> . <a>traverseWithKey1</a> (\k -&gt; WrapApplicative . f k)
--   </pre>
traverseWithKey :: Applicative t => (Key -> a -> t b) -> NEIntMap a -> t (NEIntMap b)

-- | <i>O(n)</i>. <tt><a>traverseWithKey1</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse1</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt>
--   
--   That is, behaves exactly like a regular <a>traverse1</a> except that
--   the traversing function also has access to the key associated with a
--   value.
--   
--   <b>WARNING</b>: Differs from <tt>Data.IntMap.traverseWithKey</tt>,
--   which traverses positive items first, then negative items.
--   
--   Is more general than <a>traverseWithKey</a>, since works with all
--   <a>Apply</a>, and not just <a>Applicative</a>.
traverseWithKey1 :: Apply t => (Key -> a -> t b) -> NEIntMap a -> t (NEIntMap b)

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   semigroup, such that
--   
--   <pre>
--   <a>foldMapWithKey</a> f = <a>fold1</a> . <a>mapWithKey</a> f
--   </pre>
--   
--   <b>WARNING</b>: Differs from <tt>Data.IntMap.foldMapWithKey</tt>,
--   which traverses positive items first, then negative items.
--   
--   This can be an asymptotically faster than <a>foldrWithKey</a> or
--   <a>foldlWithKey</a> for some monoids.
foldMapWithKey :: Semigroup m => (Key -> a -> m) -> NEIntMap a -> m

-- | <i>O(n)</i>. A fixed version of <a>traverseWithKey</a> that traverses
--   items in ascending order of keys.
traverseMapWithKey :: Applicative t => (Key -> a -> t b) -> IntMap a -> t (IntMap b)

-- | <i>O(log n)</i>. Insert new key and value into a map where keys are
--   <i>strictly greater than</i> the new key. That is, the new key must be
--   <i>strictly less than</i> all keys present in the <a>IntMap</a>. /The
--   precondition is not checked./
--   
--   At the moment this is simply an alias for <tt>Data.IntSet.insert</tt>,
--   but it's left here as a placeholder in case this eventually gets
--   implemented in a more efficient way.
insertMinMap :: Key -> a -> IntMap a -> IntMap a

-- | <i>O(log n)</i>. Insert new key and value into a map where keys are
--   <i>strictly less than</i> the new key. That is, the new key must be
--   <i>strictly greater than</i> all keys present in the <a>IntMap</a>.
--   /The precondition is not checked./
--   
--   At the moment this is simply an alias for <tt>Data.IntSet.insert</tt>,
--   but it's left here as a placeholder in case this eventually gets
--   implemented in a more efficient way.
insertMaxMap :: Key -> a -> IntMap a -> IntMap a

-- | <i>O(n)</i>. Test if the internal map structure is valid.
valid :: NEIntMap a -> Bool

-- | CPP for new functions not in old containers
--   ---------------------------------------------
--   
--   Compatibility layer for <a>lookupMinMap</a>.
lookupMinMap :: IntMap a -> Maybe (Key, a)

-- | Compatibility layer for <a>lookupMaxMap</a>.
lookupMaxMap :: IntMap a -> Maybe (Key, a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Functor.Classes.Eq1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Functor.Classes.Ord1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Functor.Classes.Show1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Functor.Classes.Read1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Read.Read e => GHC.Read.Read (Data.IntMap.NonEmpty.Internal.NEIntMap e)
instance GHC.Show.Show a => GHC.Show.Show (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Data.Data a => Data.Data.Data (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance GHC.Base.Semigroup (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance GHC.Base.Functor Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Foldable.Foldable Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Traversable.Traversable Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Semigroup.Foldable.Class.Foldable1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Semigroup.Traversable.Class.Traversable1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance Control.Comonad.Comonad Data.IntMap.NonEmpty.Internal.NEIntMap


-- | Unsafe internal-use functions used in the implementation of
--   <a>Data.IntSet.NonEmpty</a>. These functions can potentially be used
--   to break the abstraction of <a>NEIntSet</a> and produce unsound sets,
--   so be wary!
module Data.IntSet.NonEmpty.Internal

-- | A non-empty (by construction) set of integers. At least one value
--   exists in an <tt><a>NEIntSet</a> a</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NEIntSet</a> can safely operate on it
--   with the assumption that it has at least one item.
--   
--   Functions that <i>return</i> an <a>NEIntSet</a> provide an assurance
--   that the result has at least one item.
--   
--   <a>Data.IntSet.NonEmpty</a> re-exports the API of <a>Data.IntSet</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output sets are both
--   non-empty (like <a>insert</a>) return <a>NEIntSet</a>, but functions
--   that might potentially return an empty map (like <a>delete</a>) return
--   a <a>IntSet</a> instead.
--   
--   You can directly construct an <a>NEIntSet</a> with the API from
--   <a>Data.IntSet.NonEmpty</a>; it's more or less the same as
--   constructing a normal <a>IntSet</a>, except you don't have access to
--   <a>empty</a>. There are also a few ways to construct an
--   <a>NEIntSet</a> from a <a>IntSet</a>:
--   
--   <ol>
--   <li>The <a>nonEmptySet</a> smart constructor will convert a
--   <tt><a>IntSet</a> a</tt> into a <tt><a>Maybe</a> (<a>NEIntSet</a>
--   a)</tt>, returning <a>Nothing</a> if the original <a>IntSet</a> was
--   empty.</li>
--   <li>You can use the <a>insertIntSet</a> family of functions to insert
--   a value into a <a>IntSet</a> to create a guaranteed
--   <a>NEIntSet</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>IntSet</a> to reveal it as either containing a
--   <a>NEIntSet</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>IntSet</a> and treating it as if it were an
--   <a>NEIntSet</a>.</li>
--   </ol>
--   
--   You can convert an <a>NEIntSet</a> into a <a>IntSet</a> with
--   <a>toSet</a> or <a>IsNonEmpty</a>, essentially "obscuring" the
--   non-empty property from the type.
data NEIntSet
NEIntSet :: !Key -> !IntSet -> NEIntSet

-- | invariant: must be smaller than smallest value in set
[neisV0] :: NEIntSet -> !Key
[neisIntSet] :: NEIntSet -> !IntSet
type Key = Int

-- | <i>O(log n)</i>. Smart constructor for an <a>NEIntSet</a> from a
--   <a>IntSet</a>. Returns <a>Nothing</a> if the <a>IntSet</a> was
--   originally actually empty, and <tt><a>Just</a> n</tt> with an
--   <a>NEIntSet</a>, if the <a>IntSet</a> was not empty.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>IntSet</a> being an <a>NEIntSet</a>.
--   
--   <pre>
--   nonEmptySet (Data.IntSet.fromList [3,5]) == Just (fromList (3:|[5]))
--   </pre>
nonEmptySet :: IntSet -> Maybe NEIntSet

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>IntSet</a> as if it were an <a>NEIntSet</a>.
--   <tt><a>withNonEmpty</a> def f</tt> will take a <a>IntSet</a>. If set
--   is empty, it will evaluate to <tt>def</tt>. Otherwise, a non-empty set
--   <a>NEIntSet</a> will be fed to the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptySet</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NEIntSet -> r) -> IntSet -> r

-- | <i>O(log n)</i>. Convert a non-empty set back into a normal
--   possibly-empty map, for usage with functions that expect
--   <a>IntSet</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the set in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toSet (fromList ((3,"a") :| [(5,"b")])) == Data.IntSet.fromList [(3,"a"), (5,"b")]
--   </pre>
toSet :: NEIntSet -> IntSet

-- | <i>O(1)</i>. Create a singleton set.
singleton :: Key -> NEIntSet

-- | <i>O(n*log n)</i>. Create a set from a list of elements.
fromList :: NonEmpty Key -> NEIntSet

-- | <i>O(n)</i>. Convert the set to a non-empty list of elements.
toList :: NEIntSet -> NonEmpty Key

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The union of two sets, preferring
--   the first set when equal elements are encountered.
union :: NEIntSet -> NEIntSet -> NEIntSet

-- | The union of a non-empty list of sets
unions :: Foldable1 f => f NEIntSet -> NEIntSet

-- | <i>O(n)</i>. Test if the internal set structure is valid.
valid :: NEIntSet -> Bool

-- | <i>O(log n)</i>. Insert new value into a set where values are
--   <i>strictly greater than</i> the new values That is, the new value
--   must be <i>strictly less than</i> all values present in the
--   <a>IntSet</a>. /The precondition is not checked./
--   
--   At the moment this is simply an alias for <tt>Data.IntSet.insert</tt>,
--   but it's left here as a placeholder in case this eventually gets
--   implemented in a more efficient way.
insertMinSet :: Key -> IntSet -> IntSet

-- | <i>O(log n)</i>. Insert new value into a set where values are
--   /strictly less than<i> the new value. That is, the new value must be
--   </i>strictly greater than<i> all values present in the <a>IntSet</a>.
--   </i>The precondition is not checked./
--   
--   At the moment this is simply an alias for <tt>Data.IntSet.insert</tt>,
--   but it's left here as a placeholder in case this eventually gets
--   implemented in a more efficient way.
insertMaxSet :: Key -> IntSet -> IntSet

-- | CPP for new functions not in old containers
--   ---------------------------------------------
--   
--   Comptability layer for <a>disjoint</a>.
disjointSet :: IntSet -> IntSet -> Bool
instance GHC.Classes.Eq Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Classes.Ord Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Show.Show Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Read.Read Data.IntSet.NonEmpty.Internal.NEIntSet
instance Control.DeepSeq.NFData Data.IntSet.NonEmpty.Internal.NEIntSet
instance Data.Data.Data Data.IntSet.NonEmpty.Internal.NEIntSet
instance Data.Aeson.Types.ToJSON.ToJSON Data.IntSet.NonEmpty.Internal.NEIntSet
instance Data.Aeson.Types.FromJSON.FromJSON Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Base.Semigroup Data.IntSet.NonEmpty.Internal.NEIntSet


-- | <h1>Non-Empty Finite Integer Sets</h1>
--   
--   The <a>NEIntSet</a> type represents a non-empty set of integers.
--   
--   See documentation for <a>NEIntSet</a> for information on how to
--   convert and manipulate such non-empty set.
--   
--   This module essentially re-imports the API of <a>Data.IntSet</a> and
--   its <a>IntSet</a> type, along with semantics and asymptotics. In most
--   situations, asymptotics are different only by a constant factor. In
--   some situations, asmyptotics are even better (constant-time instead of
--   log-time).
--   
--   Because <a>NEIntSet</a> is implemented using <a>IntSet</a>, all of the
--   caveats of using <a>IntSet</a> apply (such as the limitation of the
--   maximum size of sets).
--   
--   All functions take non-empty sets as inputs. In situations where their
--   results can be guarunteed to also be non-empty, they also return
--   non-empty sets. In situations where their results could potentially be
--   empty, <a>IntSet</a> is returned instead.
--   
--   Some functions (<a>partition</a>, <a>split</a>) have modified return
--   types to account for possible configurations of non-emptiness.
--   
--   This module is intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> and <a>Data.IntSet</a> functions:
--   
--   <pre>
--   import qualified Data.IntSet.NonEmpty as NEIS
--   </pre>
--   
--   Note that all asmyptotics <i>O(f(n))</i> in this module are actually
--   <i>O(min(W, f(n)))</i>, where <tt>W</tt> is the number of bits in an
--   <a>Int</a> (32 or 64). That is, if <tt>f(n)</tt> is greater than
--   <tt>W</tt>, all operations are constant-time.
module Data.IntSet.NonEmpty

-- | A non-empty (by construction) set of integers. At least one value
--   exists in an <tt><a>NEIntSet</a> a</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NEIntSet</a> can safely operate on it
--   with the assumption that it has at least one item.
--   
--   Functions that <i>return</i> an <a>NEIntSet</a> provide an assurance
--   that the result has at least one item.
--   
--   <a>Data.IntSet.NonEmpty</a> re-exports the API of <a>Data.IntSet</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output sets are both
--   non-empty (like <a>insert</a>) return <a>NEIntSet</a>, but functions
--   that might potentially return an empty map (like <a>delete</a>) return
--   a <a>IntSet</a> instead.
--   
--   You can directly construct an <a>NEIntSet</a> with the API from
--   <a>Data.IntSet.NonEmpty</a>; it's more or less the same as
--   constructing a normal <a>IntSet</a>, except you don't have access to
--   <a>empty</a>. There are also a few ways to construct an
--   <a>NEIntSet</a> from a <a>IntSet</a>:
--   
--   <ol>
--   <li>The <a>nonEmptySet</a> smart constructor will convert a
--   <tt><a>IntSet</a> a</tt> into a <tt><a>Maybe</a> (<a>NEIntSet</a>
--   a)</tt>, returning <a>Nothing</a> if the original <a>IntSet</a> was
--   empty.</li>
--   <li>You can use the <a>insertIntSet</a> family of functions to insert
--   a value into a <a>IntSet</a> to create a guaranteed
--   <a>NEIntSet</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>IntSet</a> to reveal it as either containing a
--   <a>NEIntSet</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>IntSet</a> and treating it as if it were an
--   <a>NEIntSet</a>.</li>
--   </ol>
--   
--   You can convert an <a>NEIntSet</a> into a <a>IntSet</a> with
--   <a>toSet</a> or <a>IsNonEmpty</a>, essentially "obscuring" the
--   non-empty property from the type.
data NEIntSet
type Key = Int

-- | <i>O(1)</i> match, <i>O(log n)</i> usage of contents. The
--   <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow you to treat a
--   <a>IntSet</a> as if it were either a <tt><a>IsNonEmpty</a> n</tt>
--   (where <tt>n</tt> is a <a>NEIntSet</a>) or an <a>IsEmpty</a>.
--   
--   For example, you can pattern match on a <a>IntSet</a>:
--   
--   <pre>
--   myFunc :: <a>IntSet</a> X -&gt; Y
--   myFunc (<a>IsNonEmpty</a> n) =  -- here, the user provided a non-empty set, and <tt>n</tt> is the <a>NEIntSet</a>
--   myFunc <a>IsEmpty</a>        =  -- here, the user provided an empty set
--   </pre>
--   
--   Matching on <tt><a>IsNonEmpty</a> n</tt> means that the original
--   <a>IntSet</a> was <i>not</i> empty, and you have a verified-non-empty
--   <a>NEIntSet</a> <tt>n</tt> to use.
--   
--   Note that patching on this pattern is <i>O(1)</i>. However, using the
--   contents requires a <i>O(log n)</i> cost that is deferred until after
--   the pattern is matched on (and is not incurred at all if the contents
--   are never used).
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsNonEmpty</a> to
--   convert a <a>NEIntSet</a> back into a <a>IntSet</a>, obscuring its
--   non-emptiness (see <a>toSet</a>).
pattern IsNonEmpty :: NEIntSet -> IntSet

-- | <i>O(1)</i>. The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow
--   you to treat a <a>IntSet</a> as if it were either a
--   <tt><a>IsNonEmpty</a> n</tt> (where <tt>n</tt> is a <a>NEIntSet</a>)
--   or an <a>IsEmpty</a>.
--   
--   Matching on <a>IsEmpty</a> means that the original <a>IntSet</a> was
--   empty.
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsEmpty</a> as an
--   expression, and it will be interpreted as <a>empty</a>.
--   
--   See <a>IsNonEmpty</a> for more information.
pattern IsEmpty :: IntSet

-- | <i>O(log n)</i>. Smart constructor for an <a>NEIntSet</a> from a
--   <a>IntSet</a>. Returns <a>Nothing</a> if the <a>IntSet</a> was
--   originally actually empty, and <tt><a>Just</a> n</tt> with an
--   <a>NEIntSet</a>, if the <a>IntSet</a> was not empty.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>IntSet</a> being an <a>NEIntSet</a>.
--   
--   <pre>
--   nonEmptySet (Data.IntSet.fromList [3,5]) == Just (fromList (3:|[5]))
--   </pre>
nonEmptySet :: IntSet -> Maybe NEIntSet

-- | <i>O(log n)</i>. Convert a non-empty set back into a normal
--   possibly-empty map, for usage with functions that expect
--   <a>IntSet</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the set in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toSet (fromList ((3,"a") :| [(5,"b")])) == Data.IntSet.fromList [(3,"a"), (5,"b")]
--   </pre>
toSet :: NEIntSet -> IntSet

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>IntSet</a> as if it were an <a>NEIntSet</a>.
--   <tt><a>withNonEmpty</a> def f</tt> will take a <a>IntSet</a>. If set
--   is empty, it will evaluate to <tt>def</tt>. Otherwise, a non-empty set
--   <a>NEIntSet</a> will be fed to the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptySet</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NEIntSet -> r) -> IntSet -> r

-- | <i>O(log n)</i>. Convert a <a>IntSet</a> into an <a>NEIntSet</a> by
--   adding a value. Because of this, we know that the set must have at
--   least one element, and so therefore cannot be empty.
--   
--   See <a>insertSetMin</a> for a version that is constant-time if the new
--   value is <i>strictly smaller than</i> all values in the original set
--   
--   <pre>
--   insertSet 4 (Data.IntSet.fromList [5, 3]) == fromList (3 :| [4, 5])
--   insertSet 4 Data.IntSet.empty == singleton 4 "c"
--   </pre>
insertSet :: Key -> IntSet -> NEIntSet

-- | <i>O(1)</i> Convert a <a>IntSet</a> into an <a>NEIntSet</a> by adding
--   a value where the value is <i>strictly less than</i> all values in the
--   input set The values in the original map must all be <i>strictly
--   greater than</i> the new value. <i>The precondition is not
--   checked.</i>
--   
--   <pre>
--   insertSetMin 2 (Data.IntSet.fromList [5, 3]) == fromList (2 :| [3, 5])
--   valid (insertSetMin 2 (Data.IntSet.fromList [5, 3])) == True
--   valid (insertSetMin 7 (Data.IntSet.fromList [5, 3])) == False
--   valid (insertSetMin 3 (Data.IntSet.fromList [5, 3])) == False
--   </pre>
insertSetMin :: Key -> IntSet -> NEIntSet

-- | <i>O(log n)</i> Convert a <a>IntSet</a> into an <a>NEIntSet</a> by
--   adding a value where the value is <i>strictly less than</i> all values
--   in the input set The values in the original map must all be
--   <i>strictly greater than</i> the new value. <i>The precondition is not
--   checked.</i>
--   
--   At the current moment, this is identical simply <a>insertSet</a>;
--   however, it is left both for consistency and as a placeholder for a
--   future version where optimizations are implemented to allow for a
--   faster implementation.
--   
--   <pre>
--   insertSetMin 7 (Data.IntSet.fromList [5, 3]) == fromList (3 :| [5, 7])
--   </pre>
insertSetMax :: Key -> IntSet -> NEIntSet

-- | <i>O(log n)</i>. Unsafe version of <a>nonEmptySet</a>. Coerces a
--   <a>IntSet</a> into an <a>NEIntSet</a>, but is undefined (throws a
--   runtime exception when evaluation is attempted) for an empty
--   <a>IntSet</a>.
unsafeFromSet :: IntSet -> NEIntSet

-- | <i>O(1)</i>. Create a singleton set.
singleton :: Key -> NEIntSet

-- | <i>O(n*log n)</i>. Create a set from a list of elements.
fromList :: NonEmpty Key -> NEIntSet

-- | <i>O(n)</i>. Build a set from an ascending list in linear time. /The
--   precondition (input list is ascending) is not checked./
fromAscList :: NonEmpty Key -> NEIntSet

-- | <i>O(n)</i>. Build a set from an ascending list of distinct elements
--   in linear time. <i>The precondition (input list is strictly ascending)
--   is not checked.</i>
fromDistinctAscList :: NonEmpty Key -> NEIntSet

-- | <i>O(log n)</i>. Insert an element in a set. If the set already
--   contains an element equal to the given value, it is replaced with the
--   new value.
insert :: Key -> NEIntSet -> NEIntSet

-- | <i>O(log n)</i>. Delete an element from a set.
delete :: Key -> NEIntSet -> IntSet

-- | <i>O(log n)</i>. Is the element in the set?
member :: Key -> NEIntSet -> Bool

-- | <i>O(log n)</i>. Is the element not in the set?
notMember :: Key -> NEIntSet -> Bool

-- | <i>O(log n)</i>. Find largest element smaller than the given one.
--   
--   <pre>
--   lookupLT 3 (fromList (3 :| [5])) == Nothing
--   lookupLT 5 (fromList (3 :| [5])) == Just 3
--   </pre>
lookupLT :: Key -> NEIntSet -> Maybe Key

-- | <i>O(log n)</i>. Find smallest element greater than the given one.
--   
--   <pre>
--   lookupLT 4 (fromList (3 :| [5])) == Just 5
--   lookupLT 5 (fromList (3 :| [5])) == Nothing
--   </pre>
lookupGT :: Key -> NEIntSet -> Maybe Key

-- | <i>O(log n)</i>. Find largest element smaller or equal to the given
--   one.
--   
--   <pre>
--   lookupLT 2 (fromList (3 :| [5])) == Nothing
--   lookupLT 4 (fromList (3 :| [5])) == Just 3
--   lookupLT 5 (fromList (3 :| [5])) == Just 5
--   </pre>
lookupLE :: Key -> NEIntSet -> Maybe Key

-- | <i>O(log n)</i>. Find smallest element greater or equal to the given
--   one.
--   
--   <pre>
--   lookupLT 3 (fromList (3 :| [5])) == Just 3
--   lookupLT 4 (fromList (3 :| [5])) == Just 5
--   lookupLT 6 (fromList (3 :| [5])) == Nothing
--   </pre>
lookupGE :: Key -> NEIntSet -> Maybe Key

-- | <i>O(1)</i>. The number of elements in the set. Guaranteed to be
--   greater than zero.
size :: NEIntSet -> Int

-- | <i>O(n+m)</i>. Is this a subset? <tt>(s1 `isSubsetOf` s2)</tt> tells
--   whether <tt>s1</tt> is a subset of <tt>s2</tt>.
isSubsetOf :: NEIntSet -> NEIntSet -> Bool

-- | <i>O(n+m)</i>. Is this a proper subset? (ie. a subset but not equal).
isProperSubsetOf :: NEIntSet -> NEIntSet -> Bool

-- | <i>O(n+m)</i>. Check whether two sets are disjoint (i.e. their
--   intersection is empty).
--   
--   <pre>
--   disjoint (fromList (2:|[4,6]))   (fromList (1:|[3]))     == True
--   disjoint (fromList (2:|[4,6,8])) (fromList (2:|[3,5,7])) == False
--   disjoint (fromList (1:|[2]))     (fromList (1:|[2,3,4])) == False
--   </pre>
disjoint :: NEIntSet -> NEIntSet -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The union of two sets, preferring
--   the first set when equal elements are encountered.
union :: NEIntSet -> NEIntSet -> NEIntSet

-- | The union of a non-empty list of sets
unions :: Foldable1 f => f NEIntSet -> NEIntSet

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Difference of two sets.
--   
--   Returns a potentially empty set (<a>IntSet</a>) because the first set
--   might be a subset of the second set, and therefore have all of its
--   elements removed.
difference :: NEIntSet -> NEIntSet -> IntSet

-- | Same as <a>difference</a>.
(\\) :: NEIntSet -> NEIntSet -> IntSet

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The intersection of two sets.
--   
--   Returns a potentially empty set (<a>IntSet</a>), because the two sets
--   might have an empty intersection.
--   
--   Elements of the result come from the first set, so for example
--   
--   <pre>
--   import qualified Data.IntSet.NonEmpty as NES
--   data AB = A | B deriving Show
--   instance Ord AB where compare _ _ = EQ
--   instance Eq AB where _ == _ = True
--   main = print (NES.singleton A `NES.intersection` NES.singleton B,
--                 NES.singleton B `NES.intersection` NES.singleton A)
--   </pre>
--   
--   prints <tt>(fromList (A:|[]),fromList (B:|[]))</tt>.
intersection :: NEIntSet -> NEIntSet -> IntSet

-- | <i>O(n)</i>. Filter all elements that satisfy the predicate.
--   
--   Returns a potentially empty set (<a>IntSet</a>) because the predicate
--   might filter out all items in the original non-empty set.
filter :: (Key -> Bool) -> NEIntSet -> IntSet

-- | <i>O(n)</i>. Partition the map according to a predicate.
--   
--   Returns a <a>These</a> with potentially two non-empty sets:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate was true for all
--   items.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate was false for all
--   items.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (all of the items
--   that were true for the predicate) and <tt>n2</tt> (all of the items
--   that were false for the predicate).</li>
--   </ul>
--   
--   See also <a>split</a>.
--   
--   <pre>
--   partition (&gt; 3) (fromList (5 :| [3])) == These (singleton 5) (singleton 3)
--   partition (&lt; 7) (fromList (5 :| [3])) == This  (fromList (3 :| [5]))
--   partition (&gt; 7) (fromList (5 :| [3])) == That  (fromList (3 :| [5]))
--   </pre>
partition :: (Key -> Bool) -> NEIntSet -> These NEIntSet NEIntSet

-- | <i>O(log n)</i>. The expression (<tt><a>split</a> x set</tt>) is
--   potentially a <a>These</a> containing up to two <a>NEIntSet</a>s based
--   on splitting the set into sets containing items before and after the
--   value <tt>x</tt>. It will never return a set that contains <tt>x</tt>
--   itself.
--   
--   <ul>
--   <li><a>Nothing</a> means that <tt>x</tt> was the only value in the the
--   original set, and so there are no items before or after it.</li>
--   <li><tt><a>Just</a> (<a>This</a> n1)</tt> means <tt>x</tt> was larger
--   than or equal to all items in the set, and <tt>n1</tt> is the entire
--   original set (minus <tt>x</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>That</a> n2)</tt> means <tt>x</tt> was smaller
--   than or equal to all items in the set, and <tt>n2</tt> is the entire
--   original set (minus <tt>x</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>These</a> n1 n2)</tt> gives <tt>n1</tt> (the
--   set of all values from the original set less than <tt>x</tt>) and
--   <tt>n2</tt> (the set of all values from the original set greater than
--   <tt>x</tt>).</li>
--   </ul>
--   
--   <pre>
--   split 2 (fromList (5 :| [3])) == Just (That  (fromList (3 :| [5]))      )
--   split 3 (fromList (5 :| [3])) == Just (That  (singleton 5)              )
--   split 4 (fromList (5 :| [3])) == Just (These (singleton 3) (singleton 5))
--   split 5 (fromList (5 :| [3])) == Just (This  (singleton 3)              )
--   split 6 (fromList (5 :| [3])) == Just (This  (fromList (3 :| [5]))      )
--   split 5 (singleton 5)         == Nothing
--   </pre>
split :: Key -> NEIntSet -> Maybe (These NEIntSet NEIntSet)

-- | <i>O(log n)</i>. The expression (<tt><a>splitMember</a> x set</tt>)
--   splits a set just like <a>split</a> but also returns <tt><a>member</a>
--   x set</tt> (whether or not <tt>x</tt> was in <tt>set</tt>)
--   
--   <pre>
--   splitMember 2 (fromList (5 :| [3])) == (False, Just (That  (fromList (3 :| [5)]))))
--   splitMember 3 (fromList (5 :| [3])) == (True , Just (That  (singleton 5)))
--   splitMember 4 (fromList (5 :| [3])) == (False, Just (These (singleton 3) (singleton 5)))
--   splitMember 5 (fromList (5 :| [3])) == (True , Just (This  (singleton 3))
--   splitMember 6 (fromList (5 :| [3])) == (False, Just (This  (fromList (3 :| [5])))
--   splitMember 5 (singleton 5)         == (True , Nothing)
--   </pre>
splitMember :: Key -> NEIntSet -> (Bool, Maybe (These NEIntSet NEIntSet))

-- | <i>O(1)</i>. Decompose a set into pieces based on the structure of the
--   underlying tree. This function is useful for consuming a set in
--   parallel.
--   
--   No guarantee is made as to the sizes of the pieces; an internal, but
--   deterministic process determines this. However, it is guaranteed that
--   the pieces returned will be in ascending order (all elements in the
--   first subset less than all elements in the second, and so on).
--   
--   Note that the current implementation does not return more than four
--   subsets, but you should not depend on this behaviour because it can
--   change in the future without notice.
splitRoot :: NEIntSet -> NonEmpty NEIntSet

-- | <i>O(n*log n)</i>. <tt><a>map</a> f s</tt> is the set obtained by
--   applying <tt>f</tt> to each element of <tt>s</tt>.
--   
--   It's worth noting that the size of the result may be smaller if, for
--   some <tt>(x,y)</tt>, <tt>x /= y &amp;&amp; f x == f y</tt>
map :: (Key -> Key) -> NEIntSet -> NEIntSet

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   elemsList set = foldr (:) [] set
--   </pre>
foldr :: (Key -> b -> b) -> b -> NEIntSet -> b

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   descElemsList set = foldl (flip (:)) [] set
--   </pre>
foldl :: (a -> Key -> a) -> a -> NEIntSet -> a

-- | <i>O(n)</i>. A version of <a>foldr</a> that uses the value at the
--   maximal value in the set as the starting value.
--   
--   Note that, unlike <a>foldr1</a> for <a>IntSet</a>, this function is
--   total if the input function is total.
foldr1 :: (Key -> Key -> Key) -> NEIntSet -> Key

-- | <i>O(n)</i>. A version of <a>foldl</a> that uses the value at the
--   minimal value in the set as the starting value.
--   
--   Note that, unlike <a>foldl1</a> for <a>IntSet</a>, this function is
--   total if the input function is total.
foldl1 :: (Key -> Key -> Key) -> NEIntSet -> Key

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (Key -> b -> b) -> b -> NEIntSet -> b

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> Key -> a) -> a -> NEIntSet -> a

-- | <i>O(n)</i>. A strict version of <a>foldr1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldr1' :: (Key -> Key -> Key) -> NEIntSet -> Key

-- | <i>O(n)</i>. A strict version of <a>foldl1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldl1' :: (Key -> Key -> Key) -> NEIntSet -> Key

-- | <i>O(1)</i>. The minimal element of a set. Note that this is total,
--   making <a>lookupMin</a> obsolete. It is constant-time, so has better
--   asymptotics than <tt>Data.IntSet.lookupMin</tt> and
--   <tt>Data.Map.findMin</tt> as well.
--   
--   <pre>
--   findMin (fromList (5 :| [3])) == 3
--   </pre>
findMin :: NEIntSet -> Key

-- | <i>O(log n)</i>. The maximal key of a set Note that this is total,
--   making <a>lookupMin</a> obsolete.
--   
--   <pre>
--   findMax (fromList (5 :| [3])) == 5
--   </pre>
findMax :: NEIntSet -> Key

-- | <i>O(1)</i>. Delete the minimal element. Returns a potentially empty
--   set (<a>IntSet</a>), because we might delete the final item in a
--   singleton set. It is constant-time, so has better asymptotics than
--   <tt>Data.IntSet.deleteMin</tt>.
--   
--   <pre>
--   deleteMin (fromList (5 :| [3, 7])) == Data.IntSet.fromList [5, 7]
--   deleteMin (singleton 5) == Data.IntSet.empty
--   </pre>
deleteMin :: NEIntSet -> IntSet

-- | <i>O(log n)</i>. Delete the maximal element. Returns a potentially
--   empty set (<a>IntSet</a>), because we might delete the final item in a
--   singleton set.
--   
--   <pre>
--   deleteMax (fromList (5 :| [3, 7])) == Data.IntSet.fromList [3, 5]
--   deleteMax (singleton 5) == Data.IntSet.empty
--   </pre>
deleteMax :: NEIntSet -> IntSet

-- | <i>O(1)</i>. Delete and find the minimal element. It is constant-time,
--   so has better asymptotics that <tt>Data.IntSet.minView</tt> for
--   <a>IntSet</a>.
--   
--   Note that unlike <tt>Data.IntSet.deleteFindMin</tt> for <a>IntSet</a>,
--   this cannot ever fail, and so is a total function. However, the result
--   <a>IntSet</a> is potentially empty, since the original set might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMin (fromList (5 :| [3, 10])) == (3, Data.IntSet.fromList [5, 10])
--   </pre>
deleteFindMin :: NEIntSet -> (Key, IntSet)

-- | <i>O(log n)</i>. Delete and find the minimal element.
--   
--   Note that unlike <tt>Data.IntSet.deleteFindMax</tt> for <a>IntSet</a>,
--   this cannot ever fail, and so is a total function. However, the result
--   <a>IntSet</a> is potentially empty, since the original set might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMax (fromList (5 :| [3, 10])) == (10, Data.IntSet.fromList [3, 5])
--   </pre>
deleteFindMax :: NEIntSet -> (Key, IntSet)

-- | <i>O(n)</i>. An alias of <a>toAscList</a>. The elements of a set in
--   ascending order.
elems :: NEIntSet -> NonEmpty Key

-- | <i>O(n)</i>. Convert the set to a non-empty list of elements.
toList :: NEIntSet -> NonEmpty Key

-- | <i>O(n)</i>. Convert the set to an ascending non-empty list of
--   elements.
toAscList :: NEIntSet -> NonEmpty Key

-- | <i>O(n)</i>. Convert the set to a descending non-empty list of
--   elements.
toDescList :: NEIntSet -> NonEmpty Key

-- | <i>O(n)</i>. Test if the internal set structure is valid.
valid :: NEIntSet -> Bool


-- | <h1>Non-Empty Finite Integer-Indexed Maps (lazy interface)</h1>
--   
--   The <tt><a>NEIntMap</a> v</tt> type represents a non-empty finite map
--   (sometimes called a dictionary) from integer keys to values of type
--   <tt>v</tt>. An <a>NEIntMap</a> is strict in its keys but lazy in its
--   values.
--   
--   See documentation for <a>NEIntMap</a> for information on how to
--   convert and manipulate such non-empty maps.
--   
--   This module essentially re-imports the API of <a>Data.IntMap.Lazy</a>
--   and its <a>IntMap</a> type, along with semantics and asymptotics. In
--   most situations, asymptotics are different only by a constant factor.
--   In some situations, asmyptotics are even better (constant-time instead
--   of log-time).
--   
--   Because <a>NEIntMap</a> is implemented using <a>IntMap</a>, all of the
--   caveats of using <a>IntMap</a> apply (such as the limitation of the
--   maximum size of maps).
--   
--   All functions take non-empty maps as inputs. In situations where their
--   results can be guarunteed to also be non-empty, they also return
--   non-empty maps. In situations where their results could potentially be
--   empty, <a>IntMap</a> is returned instead.
--   
--   Some variants of functions (like <a>alter'</a>, <a>alterF'</a>,
--   <a>adjustMin</a>, <a>adjustMax</a>, <a>adjustMinWithKey</a>,
--   <a>adjustMaxWithKey</a>) are provided in a way restructured to
--   preserve guaruntees of non-empty maps being returned.
--   
--   Some functions (like <a>mapEither</a>, <a>partition</a>, <a>split</a>)
--   have modified return types to account for possible configurations of
--   non-emptiness.
--   
--   This module is intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> and <a>Data.IntMap</a> functions:
--   
--   <pre>
--   import qualified Data.IntMap.NonEmpty as NEIM
--   </pre>
--   
--   Note that all asmyptotics <i>O(f(n))</i> in this module are actually
--   <i>O(min(W, f(n)))</i>, where <tt>W</tt> is the number of bits in an
--   <a>Int</a> (32 or 64). That is, if <tt>f(n)</tt> is greater than
--   <tt>W</tt>, all operations are constant-time.
--   
--   At the moment, this package does not provide a variant strict on
--   values for these functions, like <i>containers</i> does. This is a
--   planned future implementation (PR's are appreciated). For now, you can
--   simulate a strict interface by manually forcing values before
--   returning results.
module Data.IntMap.NonEmpty

-- | A non-empty (by construction) map from integer keys to values
--   <tt>a</tt>. At least one key-value pair exists in an
--   <tt><a>NEIntMap</a> v</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NEIntMap</a> can safely operate on it
--   with the assumption that it has at least one key-value pair.
--   
--   Functions that <i>return</i> an <a>NEIntMap</a> provide an assurance
--   that the result has at least one key-value pair.
--   
--   <a>Data.IntMap.NonEmpty</a> re-exports the API of <a>Data.IntMap</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output maps are both
--   non-empty (like <a>insert</a>) return <a>NEIntMap</a>, but functions
--   that might potentially return an empty map (like <a>delete</a>) return
--   a <a>IntMap</a> instead.
--   
--   You can directly construct an <a>NEIntMap</a> with the API from
--   <a>Data.IntMap.NonEmpty</a>; it's more or less the same as
--   constructing a normal <a>IntMap</a>, except you don't have access to
--   <a>empty</a>. There are also a few ways to construct an
--   <a>NEIntMap</a> from a <a>IntMap</a>:
--   
--   <ol>
--   <li>The <a>nonEmptyMap</a> smart constructor will convert a
--   <tt><a>IntMap</a> k a</tt> into a <tt><a>Maybe</a> (<a>NEIntMap</a> k
--   a)</tt>, returning <a>Nothing</a> if the original <a>IntMap</a> was
--   empty.</li>
--   <li>You can use the <a>insertIntMap</a> family of functions to insert
--   a value into a <a>IntMap</a> to create a guaranteed
--   <a>NEIntMap</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>IntMap</a> to reveal it as either containing a
--   <a>NEIntMap</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>IntMap</a> and treating it as if it were an
--   <a>NEIntMap</a>.</li>
--   </ol>
--   
--   You can convert an <a>NEIntMap</a> into a <a>IntMap</a> with
--   <a>toMap</a> or <a>IsNonEmpty</a>, essentially "obscuring" the
--   non-empty property from the type.
data NEIntMap a
type Key = Int

-- | <i>O(1)</i> match, <i>O(log n)</i> usage of contents. The
--   <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow you to treat a
--   <a>IntMap</a> as if it were either a <tt><a>IsNonEmpty</a> n</tt>
--   (where <tt>n</tt> is a <a>NEIntMap</a>) or an <a>IsEmpty</a>.
--   
--   For example, you can pattern match on a <a>IntMap</a>:
--   
--   <pre>
--   myFunc :: <a>IntMap</a> K X -&gt; Y
--   myFunc (<a>IsNonEmpty</a> n) =  -- here, the user provided a non-empty map, and <tt>n</tt> is the <a>NEIntMap</a>
--   myFunc <a>IsEmpty</a>        =  -- here, the user provided an empty map.
--   </pre>
--   
--   Matching on <tt><a>IsNonEmpty</a> n</tt> means that the original
--   <a>IntMap</a> was <i>not</i> empty, and you have a verified-non-empty
--   <a>NEIntMap</a> <tt>n</tt> to use.
--   
--   Note that patching on this pattern is <i>O(1)</i>. However, using the
--   contents requires a <i>O(log n)</i> cost that is deferred until after
--   the pattern is matched on (and is not incurred at all if the contents
--   are never used).
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsNonEmpty</a> to
--   convert a <a>NEIntMap</a> back into a <a>IntMap</a>, obscuring its
--   non-emptiness (see <a>toMap</a>).
pattern IsNonEmpty :: NEIntMap a -> IntMap a

-- | <i>O(1)</i>. The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow
--   you to treat a <a>IntMap</a> as if it were either a
--   <tt><a>IsNonEmpty</a> n</tt> (where <tt>n</tt> is a <a>NEIntMap</a>)
--   or an <a>IsEmpty</a>.
--   
--   Matching on <a>IsEmpty</a> means that the original <a>IntMap</a> was
--   empty.
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsEmpty</a> as an
--   expression, and it will be interpreted as <a>empty</a>.
--   
--   See <a>IsNonEmpty</a> for more information.
pattern IsEmpty :: IntMap a

-- | <i>O(log n)</i>. Smart constructor for an <a>NEIntMap</a> from a
--   <a>IntMap</a>. Returns <a>Nothing</a> if the <a>IntMap</a> was
--   originally actually empty, and <tt><a>Just</a> n</tt> with an
--   <a>NEIntMap</a>, if the <a>IntMap</a> was not empty.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>IntMap</a> being an <a>NEIntMap</a>.
--   
--   <pre>
--   nonEmptyMap (Data.IntMap.fromList [(3,"a"), (5,"b")]) == Just (fromList ((3,"a") :| [(5,"b")]))
--   </pre>
nonEmptyMap :: IntMap a -> Maybe (NEIntMap a)

-- | <i>O(log n)</i>. Convert a non-empty map back into a normal
--   possibly-empty map, for usage with functions that expect
--   <a>IntMap</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the map in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toMap (fromList ((3,"a") :| [(5,"b")])) == Data.IntMap.fromList [(3,"a"), (5,"b")]
--   </pre>
toMap :: NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>IntMap</a> as if it were an <a>NEIntMap</a>.
--   <tt><a>withNonEmpty</a> def f</tt> will take a <a>IntMap</a>. If map
--   is empty, it will evaluate to <tt>def</tt>. Otherwise, a non-empty map
--   <a>NEIntMap</a> will be fed to the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptyMap</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NEIntMap a -> r) -> IntMap a -> r

-- | <i>O(log n)</i>. Convert a <a>IntMap</a> into an <a>NEIntMap</a> by
--   adding a key-value pair. Because of this, we know that the map must
--   have at least one element, and so therefore cannot be empty. If key is
--   already present, will overwrite the original value.
--   
--   See <a>insertMapMin</a> for a version that is constant-time if the new
--   key is <i>strictly smaller than</i> all keys in the original map.
--   
--   <pre>
--   insertMap 4 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(4,"c"), (5,"a")])
--   insertMap 4 "c" Data.IntMap.empty == singleton 4 "c"
--   </pre>
insertMap :: Key -> a -> IntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Convert a <a>IntMap</a> into an <a>NEIntMap</a> by
--   adding a key-value pair. Because of this, we know that the map must
--   have at least one element, and so therefore cannot be empty. Uses a
--   combining function with the new value as the first argument if the key
--   is already present.
--   
--   <pre>
--   insertMapWith (++) 4 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(4,"c"), (5,"a")])
--   insertMapWith (++) 5 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(5,"ca")])
--   </pre>
insertMapWith :: (a -> a -> a) -> Key -> a -> IntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Convert a <a>IntMap</a> into an <a>NEIntMap</a> by
--   adding a key-value pair. Because of this, we know that the map must
--   have at least one element, and so therefore cannot be empty. Uses a
--   combining function with the key and new value as the first and second
--   arguments if the key is already present.
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertWithKey f 5 "xxx" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((3, "b") :| [(5, "5:xxx|a")])
--   insertWithKey f 7 "xxx" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   insertWithKey f 5 "xxx" Data.IntMap.empty                         == singleton 5 "xxx"
--   </pre>
insertMapWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> NEIntMap a

-- | <i>O(1)</i> Convert a <a>IntMap</a> into an <a>NEIntMap</a> by adding
--   a key-value pair where the key is <i>strictly less than</i> all keys
--   in the input map. The keys in the original map must all be <i>strictly
--   greater than</i> the new key. <i>The precondition is not checked.</i>
--   
--   <pre>
--   insertMapMin 2 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((2,"c") :| [(3,"b"), (5,"a")])
--   valid (insertMapMin 2 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")])) == True
--   valid (insertMapMin 7 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")])) == False
--   valid (insertMapMin 3 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")])) == False
--   </pre>
insertMapMin :: Key -> a -> IntMap a -> NEIntMap a

-- | <i>O(log n)</i> Convert a <a>IntMap</a> into an <a>NEIntMap</a> by
--   adding a key-value pair where the key is <i>strictly greater than</i>
--   all keys in the input map. The keys in the original map must all be
--   <i>strictly less than</i> the new key. <i>The precondition is not
--   checked.</i>
--   
--   At the current moment, this is identical simply <a>insertMap</a>;
--   however, it is left both for consistency and as a placeholder for a
--   future version where optimizations are implemented to allow for a
--   faster implementation.
--   
--   <pre>
--   insertMap 7 "c" (Data.IntMap.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(5,"a"), (7,"c")])
--   </pre>
insertMapMax :: Key -> a -> IntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Unsafe version of <a>nonEmptyMap</a>. Coerces a
--   <a>IntMap</a> into an <a>NEIntMap</a>, but is undefined (throws a
--   runtime exception when evaluation is attempted) for an empty
--   <a>IntMap</a>.
unsafeFromMap :: IntMap a -> NEIntMap a

-- | <i>O(1)</i>. A map with a single element.
--   
--   <pre>
--   singleton 1 'a'        == fromList ((1, 'a') :| [])
--   size (singleton 1 'a') == 1
--   </pre>
singleton :: Key -> a -> NEIntMap a

-- | <i>O(n)</i>. Build a non-empty map from a non-empty set of keys and a
--   function which for each key computes its value.
--   
--   <pre>
--   fromSet (\k -&gt; replicate k 'a') (Data.Set.NonEmpty.fromList (3 :| [5])) == fromList ((5,"aaaaa") :| [(3,"aaa")])
--   </pre>
fromSet :: (Key -> a) -> NEIntSet -> NEIntMap a

-- | <i>O(n*log n)</i>. Build a non-empty map from a non-empty list of
--   key/value pairs. See also <a>fromAscList</a>. If the list contains
--   more than one value for the same key, the last value for the key is
--   retained.
--   
--   <pre>
--   fromList ((5,"a") :| [(3,"b"), (5, "c")]) == fromList ((5,"c") :| [(3,"b")])
--   fromList ((5,"c") :| [(3,"b"), (5, "a")]) == fromList ((5,"a") :| [(3,"b")])
--   </pre>
fromList :: NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n*log n)</i>. Build a map from a non-empty list of key/value
--   pairs with a combining function. See also <a>fromAscListWith</a>.
--   
--   <pre>
--   fromListWith (++) ((5,"a") :| [(5,"b"), (3,"b"), (3,"a"), (5,"a")]) == fromList ((3, "ab") :| [(5, "aba")])
--   </pre>
fromListWith :: (a -> a -> a) -> NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n*log n)</i>. Build a map from a non-empty list of key/value
--   pairs with a combining function. See also <a>fromAscListWithKey</a>.
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ a1 ++ a2
--   fromListWithKey f ((5,"a") :| [(5,"b"), (3,"b"), (3,"a"), (5,"a")]) == fromList ((3, "3ab") :| [(5, "5a5ba")])
--   </pre>
fromListWithKey :: (Key -> a -> a -> a) -> NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list in linear
--   time. <i>The precondition (input list is ascending) is not
--   checked.</i>
--   
--   <pre>
--   fromAscList ((3,"b") :| [(5,"a")])          == fromList ((3, "b") :| [(5, "a")])
--   fromAscList ((3,"b") :| [(5,"a"), (5,"b")]) == fromList ((3, "b") :| [(5, "b")])
--   valid (fromAscList ((3,"b") :| [(5,"a"), (5,"b")])) == True
--   valid (fromAscList ((5,"a") :| [(3,"b"), (5,"b")])) == False
--   </pre>
fromAscList :: NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list in linear
--   time with a combining function for equal keys. /The precondition
--   (input list is ascending) is not checked./
--   
--   <pre>
--   fromAscListWith (++) ((3,"b") :| [(5,"a"), (5,"b")]) == fromList ((3, "b") :| [(5, "ba")])
--   valid (fromAscListWith (++) ((3,"b") :| [(5,"a"), (5,"b"))]) == True
--   valid (fromAscListWith (++) ((5,"a") :| [(3,"b"), (5,"b"))]) == False
--   </pre>
fromAscListWith :: (a -> a -> a) -> NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list in linear
--   time with a combining function for equal keys. /The precondition
--   (input list is ascending) is not checked./
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
--   fromAscListWithKey f ((3,"b") :| [(5,"a"), (5,"b"), (5,"b")]) == fromList ((3, "b") :| [(5, "5:b5:ba")])
--   valid (fromAscListWithKey f ((3,"b") :| [(5,"a"), (5,"b"), (5,"b")])) == True
--   valid (fromAscListWithKey f ((5,"a") :| [(3,"b"), (5,"b"), (5,"b")])) == False
--   </pre>
fromAscListWithKey :: (Key -> a -> a -> a) -> NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list of distinct
--   elements in linear time. <i>The precondition is not checked.</i>
--   
--   <pre>
--   fromDistinctAscList ((3,"b") :| [(5,"a")]) == fromList ((3, "b") :| [(5, "a")])
--   valid (fromDistinctAscList ((3,"b") :| [(5,"a")]))          == True
--   valid (fromDistinctAscList ((3,"b") :| [(5,"a"), (5,"b")])) == False
--   </pre>
fromDistinctAscList :: NonEmpty (Key, a) -> NEIntMap a

-- | <i>O(log n)</i>. Insert a new key and value in the map. If the key is
--   already present in the map, the associated value is replaced with the
--   supplied value. <a>insert</a> is equivalent to <tt><a>insertWith</a>
--   <a>const</a></tt>.
--   
--   See <a>insertMap</a> for a version where the first argument is a
--   <a>IntMap</a>.
--   
--   <pre>
--   insert 5 'x' (fromList ((5,'a') :| [(3,'b')])) == fromList ((3, 'b') :| [(5, 'x')])
--   insert 7 'x' (fromList ((5,'a') :| [(3,'b')])) == fromList ((3, 'b') :| [(5, 'a'), (7, 'x')])
--   </pre>
insert :: Key -> a -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Insert with a function, combining new value and old
--   value. <tt><a>insertWith</a> f key value mp</tt> will insert the pair
--   (key, value) into <tt>mp</tt> if key does not exist in the map. If the
--   key does exist, the function will insert the pair <tt>(key, f
--   new_value old_value)</tt>.
--   
--   See <a>insertIntMapWith</a> for a version where the first argument is
--   a <a>IntMap</a>.
--   
--   <pre>
--   insertWith (++) 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "xxxa")])
--   insertWith (++) 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   </pre>
insertWith :: (a -> a -> a) -> Key -> a -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Insert with a function, combining key, new value and
--   old value. <tt><a>insertWithKey</a> f key value mp</tt> will insert
--   the pair (key, value) into <tt>mp</tt> if key does not exist in the
--   map. If the key does exist, the function will insert the pair
--   <tt>(key,f key new_value old_value)</tt>. Note that the key passed to
--   f is the same key passed to <a>insertWithKey</a>.
--   
--   See <a>insertMapWithKey</a> for a version where the first argument is
--   a <a>IntMap</a>.
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertWithKey f 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "5:xxx|a")])
--   insertWithKey f 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   </pre>
insertWithKey :: (Key -> a -> a -> a) -> Key -> a -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Combines insert operation with old value retrieval.
--   The expression (<tt><a>insertLookupWithKey</a> f k x map</tt>) is a
--   pair where the first element is equal to (<tt><a>lookup</a> k
--   map</tt>) and the second element equal to (<tt><a>insertWithKey</a> f
--   k x map</tt>).
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertLookupWithKey f 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == (Just "a", fromList ((3, "b") :| [(5, "5:xxx|a")]))
--   insertLookupWithKey f 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == (Nothing,  fromList ((3, "b") :| [(5, "a"), (7, "xxx")]))
--   </pre>
--   
--   This is how to define <tt>insertLookup</tt> using
--   <tt>insertLookupWithKey</tt>:
--   
--   <pre>
--   let insertLookup kx x t = insertLookupWithKey (\_ a _ -&gt; a) kx x t
--   insertLookup 5 "x" (fromList ((5,"a") :| [(3,"b")])) == (Just "a", fromList ((3, "b") :| [(5, "x")]))
--   insertLookup 7 "x" (fromList ((5,"a") :| [(3,"b")])) == (Nothing,  fromList ((3, "b") :| [(5, "a"), (7, "x")]))
--   </pre>
insertLookupWithKey :: (Key -> a -> a -> a) -> Key -> a -> NEIntMap a -> (Maybe a, NEIntMap a)

-- | <i>O(log n)</i>. Delete a key and its value from the non-empty map. A
--   potentially empty map (<a>IntMap</a>) is returned, since this might
--   delete the last item in the <a>NEIntMap</a>. When the key is not a
--   member of the map, is equivalent to <a>toMap</a>.
--   
--   <pre>
--   delete 5 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 3 "b"
--   delete 7 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.Singleton [(3, "b"), (5, "a")]
--   </pre>
delete :: Key -> NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. Update a value at a specific key with the result of
--   the provided function. When the key is not a member of the map, the
--   original map is returned.
--   
--   <pre>
--   adjust ("new " ++) 5 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "new a")])
--   adjust ("new " ++) 7 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a")])
--   </pre>
adjust :: (a -> a) -> Key -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Adjust a value at a specific key. When the key is not
--   a member of the map, the original map is returned.
--   
--   <pre>
--   let f key x = (show key) ++ ":new " ++ x
--   adjustWithKey f 5 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "5:new a")])
--   adjustWithKey f 7 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a")])
--   </pre>
adjustWithKey :: (Key -> a -> a) -> Key -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. The expression (<tt><a>update</a> f k map</tt>)
--   updates the value <tt>x</tt> at <tt>k</tt> (if it is in the map). If
--   (<tt>f x</tt>) is <a>Nothing</a>, the element is deleted. If it is
--   (<tt><a>Just</a> y</tt>), the key <tt>k</tt> is bound to the new value
--   <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because we can't know
--   ahead of time if the function returns <a>Nothing</a> and deletes the
--   final item in the <a>NEIntMap</a>.
--   
--   <pre>
--   let f x = if x == "a" then Just "new a" else Nothing
--   update f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "new a")]
--   update f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "a")]
--   update f 3 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "a"
--   </pre>
update :: (a -> Maybe a) -> Key -> NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. The expression (<tt><a>updateWithKey</a> f k
--   map</tt>) updates the value <tt>x</tt> at <tt>k</tt> (if it is in the
--   map). If (<tt>f k x</tt>) is <a>Nothing</a>, the element is deleted.
--   If it is (<tt><a>Just</a> y</tt>), the key <tt>k</tt> is bound to the
--   new value <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because we can't know
--   ahead of time if the function returns <a>Nothing</a> and deletes the
--   final item in the <a>NEIntMap</a>.
--   
--   <pre>
--   let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
--   updateWithKey f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "5:new a")]
--   updateWithKey f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "a")]
--   updateWithKey f 3 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "a"
--   </pre>
updateWithKey :: (Key -> a -> Maybe a) -> Key -> NEIntMap a -> IntMap a

-- | <i>O(min(n,W))</i>. Lookup and update. The function returns original
--   value, if it is updated. This is different behavior than
--   <tt>Data.Map.NonEmpty.updateLookupWithKey</tt>. Returns the original
--   key value if the map entry is deleted.
--   
--   Returns a potentially empty map (<a>IntMap</a>) in the case that we
--   delete the final key of a singleton map.
--   
--   <pre>
--   let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
--   updateLookupWithKey f 5 (fromList ((5,"a") :| [(3,"b")])) == (Just "5:new a", Data.IntMap.fromList ((3, "b") :| [(5, "5:new a")]))
--   updateLookupWithKey f 7 (fromList ((5,"a") :| [(3,"b")])) == (Nothing,  Data.IntMap.fromList ((3, "b") :| [(5, "a")]))
--   updateLookupWithKey f 3 (fromList ((5,"a") :| [(3,"b")])) == (Just "b", Data.IntMap.singleton 5 "a")
--   </pre>
updateLookupWithKey :: (Key -> a -> Maybe a) -> Key -> NEIntMap a -> (Maybe a, IntMap a)

-- | <i>O(log n)</i>. The expression (<tt><a>alter</a> f k map</tt>) alters
--   the value <tt>x</tt> at <tt>k</tt>, or absence thereof. <a>alter</a>
--   can be used to insert, delete, or update a value in a <a>IntMap</a>.
--   In short : <tt>Data.IntMap.lookup k (<a>alter</a> f k m) = f
--   (<a>lookup</a> k m)</tt>.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because we can't know
--   ahead of time if the function returns <a>Nothing</a> and deletes the
--   final item in the <a>NEIntMap</a>.
--   
--   See <a>alterF'</a> for a version that disallows deletion, and so
--   therefore can return <a>NEIntMap</a>.
--   
--   <pre>
--   let f _ = Nothing
--   alter f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "a")]
--   alter f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 3 "b"
--   
--   let f _ = Just "c"
--   alter f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "a"), (7, "c")]
--   alter f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "c")]
--   </pre>
alter :: (Maybe a -> Maybe a) -> Key -> NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. The expression (<tt><a>alterF</a> f k map</tt>)
--   alters the value <tt>x</tt> at <tt>k</tt>, or absence thereof.
--   <a>alterF</a> can be used to inspect, insert, delete, or update a
--   value in a <a>IntMap</a>. In short: <tt>Data.IntMap.lookup k &lt;$&gt;
--   <a>alterF</a> f k m = f (<a>lookup</a> k m)</tt>.
--   
--   Example:
--   
--   <pre>
--   interactiveAlter :: Int -&gt; NEIntMap Int String -&gt; IO (IntMap Int String)
--   interactiveAlter k m = alterF f k m where
--     f Nothing = do
--        putStrLn $ show k ++
--            " was not found in the map. Would you like to add it?"
--        getUserResponse1 :: IO (Maybe String)
--     f (Just old) = do
--        putStrLn $ "The key is currently bound to " ++ show old ++
--            ". Would you like to change or delete it?"
--        getUserResponse2 :: IO (Maybe String)
--   </pre>
--   
--   Like <tt>Data.IntMap.alterF</tt> for <a>IntMap</a>, <a>alterF</a> can
--   be considered to be a unifying generalization of <a>lookup</a> and
--   <a>delete</a>; however, as a constrast, it cannot be used to implement
--   <a>insert</a>, because it must return a <a>IntMap</a> instead of an
--   <a>NEIntMap</a> (because the function might delete the final item in
--   the <a>NEIntMap</a>). When used with trivial functors like
--   <a>Identity</a> and <a>Const</a>, it is often slightly slower than
--   specialized <a>lookup</a> and <a>delete</a>. However, when the functor
--   is non-trivial and key comparison is not particularly cheap, it is the
--   fastest way.
--   
--   See <a>alterF'</a> for a version that disallows deletion, and so
--   therefore can return <a>NEIntMap</a> and be used to implement
--   <a>insert</a>
--   
--   Note on rewrite rules:
--   
--   This module includes GHC rewrite rules to optimize <a>alterF</a> for
--   the <a>Const</a> and <a>Identity</a> functors. In general, these rules
--   improve performance. The sole exception is that when using
--   <a>Identity</a>, deleting a key that is already absent takes longer
--   than it would without the rules. If you expect this to occur a very
--   large fraction of the time, you might consider using a private copy of
--   the <a>Identity</a> type.
--   
--   Note: Unlike <tt>Data.IntMap.alterF</tt> for <a>IntMap</a>,
--   <a>alterF</a> is <i>not</i> a flipped version of the <a>at</a>
--   combinator from <a>Control.Lens.At</a>. However, it match the shape
--   expected from most functions expecting lenses, getters, and setters,
--   so can be thought of as a "psuedo-lens", with virtually the same
--   practical applications as a legitimate lens.
alterF :: Functor f => (Maybe a -> f (Maybe a)) -> Key -> NEIntMap a -> f (IntMap a)

-- | <i>O(log n)</i>. Variant of <a>alter</a> that disallows deletion.
--   Allows us to guarantee that the result is also a non-empty IntMap.
alter' :: (Maybe a -> a) -> Key -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. Variant of <a>alterF</a> that disallows deletion.
--   Allows us to guarantee that the result is also a non-empty IntMap.
--   
--   Like <tt>Data.IntMap.alterF</tt> for <a>IntMap</a>, can be used to
--   generalize and unify <a>lookup</a> and <a>insert</a>. However, because
--   it disallows deletion, it cannot be used to implement <a>delete</a>.
--   
--   See <a>alterF</a> for usage information and caveats.
--   
--   Note: Neither <a>alterF</a> nor <a>alterF'</a> can be considered
--   flipped versions of the <a>at</a> combinator from
--   <a>Control.Lens.At</a>. However, this can match the shape expected
--   from most functions expecting lenses, getters, and setters, so can be
--   thought of as a "psuedo-lens", with virtually the same practical
--   applications as a legitimate lens.
--   
--   <b>WARNING</b>: The rewrite rule for <a>Identity</a> exposes an
--   inconsistency in undefined behavior for <a>Data.IntMap</a>.
--   <tt>Data.IntMap.alterF</tt> will actually <i>maintain</i> the original
--   key in the map when used with <a>Identity</a>; however,
--   <tt>Data.IntMap.insertWith</tt> will <i>replace</i> the orginal key in
--   the map. The rewrite rule for <a>alterF'</a> has chosen to be faithful
--   to <tt>Data.IntMap.insertWith</tt>, and <i>not</i>
--   <tt>Data.IntMap.alterF</tt>, for the sake of a cleaner implementation.
alterF' :: Functor f => (Maybe a -> f a) -> Key -> NEIntMap a -> f (NEIntMap a)

-- | <i>O(log n)</i>. Lookup the value at a key in the map.
--   
--   The function will return the corresponding value as <tt>(<a>Just</a>
--   value)</tt>, or <a>Nothing</a> if the key isn't in the map.
--   
--   An example of using <tt>lookup</tt>:
--   
--   <pre>
--   import Prelude hiding (lookup)
--   import Data.Map.NonEmpty
--   
--   employeeDept = fromList (("John","Sales") :| [("Bob","IT")])
--   deptCountry = fromList (("IT","USA") :| [("Sales","France")])
--   countryCurrency = fromList (("USA", "Dollar") :| [("France", "Euro")])
--   
--   employeeCurrency :: String -&gt; Maybe String
--   employeeCurrency name = do
--       dept &lt;- lookup name employeeDept
--       country &lt;- lookup dept deptCountry
--       lookup country countryCurrency
--   
--   main = do
--       putStrLn $ "John's currency: " ++ (show (employeeCurrency "John"))
--       putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete"))
--   </pre>
--   
--   The output of this program:
--   
--   <pre>
--   John's currency: Just "Euro"
--   Pete's currency: Nothing
--   </pre>
lookup :: Key -> NEIntMap a -> Maybe a

-- | <i>O(log n)</i>. Find the value at a key. Returns <a>Nothing</a> when
--   the element can not be found.
--   
--   <pre>
--   fromList ((5, 'a') :| [(3, 'b')]) !? 1 == Nothing
--   </pre>
--   
--   <pre>
--   fromList ((5, 'a') :| [(3, 'b')]) !? 5 == Just 'a'
--   </pre>
(!?) :: NEIntMap a -> Key -> Maybe a
infixl 9 !?

-- | <i>O(log n)</i>. Find the value at a key. Calls <a>error</a> when the
--   element can not be found.
--   
--   <pre>
--   fromList ((5,'a') :| [(3,'b')]) ! 1    Error: element not in the map
--   fromList ((5,'a') :| [(3,'b')]) ! 5 == 'a'
--   </pre>
(!) :: NEIntMap a -> Key -> a
infixl 9 !

-- | <i>O(log n)</i>. The expression <tt>(<a>findWithDefault</a> def k
--   map)</tt> returns the value at key <tt>k</tt> or returns default value
--   <tt>def</tt> when the key is not in the map.
--   
--   <pre>
--   findWithDefault 'x' 1 (fromList ((5,'a') :| [(3,'b')])) == 'x'
--   findWithDefault 'x' 5 (fromList ((5,'a') :| [(3,'b')])) == 'a'
--   </pre>
findWithDefault :: a -> Key -> NEIntMap a -> a

-- | <i>O(log n)</i>. Is the key a member of the map? See also
--   <a>notMember</a>.
--   
--   <pre>
--   member 5 (fromList ((5,'a') :| [(3,'b')])) == True
--   member 1 (fromList ((5,'a') :| [(3,'b')])) == False
--   </pre>
member :: Key -> NEIntMap a -> Bool

-- | <i>O(log n)</i>. Is the key not a member of the map? See also
--   <a>member</a>.
--   
--   <pre>
--   notMember 5 (fromList ((5,'a') :| [(3,'b')])) == False
--   notMember 1 (fromList ((5,'a') :| [(3,'b')])) == True
--   </pre>
notMember :: Key -> NEIntMap a -> Bool

-- | <i>O(log n)</i>. Find largest key smaller than the given one and
--   return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupLT 3 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   lookupLT 4 (fromList ((3,'a') :| [(5,'b')])) == Just (3, 'a')
--   </pre>
lookupLT :: Key -> NEIntMap a -> Maybe (Key, a)

-- | <i>O(log n)</i>. Find smallest key greater than the given one and
--   return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupGT 4 (fromList ((3,'a') :| [(5,'b')])) == Just (5, 'b')
--   lookupGT 5 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   </pre>
lookupGT :: Key -> NEIntMap a -> Maybe (Key, a)

-- | <i>O(log n)</i>. Find largest key smaller or equal to the given one
--   and return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupLE 2 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   lookupLE 4 (fromList ((3,'a') :| [(5,'b')])) == Just (3, 'a')
--   lookupLE 5 (fromList ((3,'a') :| [(5,'b')])) == Just (5, 'b')
--   </pre>
lookupLE :: Key -> NEIntMap a -> Maybe (Key, a)

-- | <i>O(log n)</i>. Find smallest key greater or equal to the given one
--   and return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupGE 3 (fromList ((3,'a') :| [(5,'b')])) == Just (3, 'a')
--   lookupGE 4 (fromList ((3,'a') :| [(5,'b')])) == Just (5, 'b')
--   lookupGE 6 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   </pre>
lookupGE :: Key -> NEIntMap a -> Maybe (Key, a)

-- | <i>O(1)</i>. The number of elements in the map. Guaranteed to be
--   greater than zero.
--   
--   <pre>
--   size (singleton 1 'a')                          == 1
--   size (fromList ((1,'a') :| [(2,'c'), (3,'b')])) == 3
--   </pre>
size :: NEIntMap a -> Int

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression (<tt><a>union</a>
--   t1 t2</tt>) takes the left-biased union of <tt>t1</tt> and
--   <tt>t2</tt>. It prefers <tt>t1</tt> when duplicate keys are
--   encountered, i.e. (<tt><a>union</a> == <a>unionWith</a>
--   <a>const</a></tt>).
--   
--   <pre>
--   union (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "a"), (7, "C")])
--   </pre>
union :: NEIntMap a -> NEIntMap a -> NEIntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Union with a combining function.
--   
--   <pre>
--   unionWith (++) (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "aA"), (7, "C")])
--   </pre>
unionWith :: (a -> a -> a) -> NEIntMap a -> NEIntMap a -> NEIntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Union with a combining function,
--   given the matching key.
--   
--   <pre>
--   let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value
--   unionWithKey f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "5:a|A"), (7, "C")])
--   </pre>
unionWithKey :: (Key -> a -> a -> a) -> NEIntMap a -> NEIntMap a -> NEIntMap a

-- | The left-biased union of a non-empty list of maps.
--   
--   <pre>
--   unions (fromList ((5, "a") :| [(3, "b")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "A3") :| [(3, "B3")])])
--       == fromList [(3, "b"), (5, "a"), (7, "C")]
--   unions (fromList ((5, "A3") :| [(3, "B3")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "a") :| [(3, "b")])])
--       == fromList ((3, "B3") :| [(5, "A3"), (7, "C")])
--   </pre>
unions :: Foldable1 f => f (NEIntMap a) -> NEIntMap a

-- | The union of a non-empty list of maps, with a combining operation:
--   (<tt><a>unionsWith</a> f == <a>foldl1</a> (<a>unionWith</a> f)</tt>).
--   
--   <pre>
--   unionsWith (++) (fromList ((5, "a") :| [(3, "b")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "A3") :| [(3, "B3")])])
--       == fromList ((3, "bB3") :| [(5, "aAA3"), (7, "C")])
--   </pre>
unionsWith :: Foldable1 f => (a -> a -> a) -> f (NEIntMap a) -> NEIntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Difference of two maps. Return
--   elements of the first map not existing in the second map.
--   
--   Returns a potentially empty map (<a>IntMap</a>), in case the first map
--   is a subset of the second map.
--   
--   <pre>
--   difference (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.IntMap.singleton 3 "b"
--   </pre>
difference :: NEIntMap a -> NEIntMap b -> IntMap a

-- | Same as <a>difference</a>.
(\\) :: NEIntMap a -> NEIntMap b -> IntMap a

-- | <i>O(n+m)</i>. Difference with a combining function. When two equal
--   keys are encountered, the combining function is applied to the values
--   of these keys. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>IntMap</a>), in case the first map
--   is a subset of the second map and the function returns <a>Nothing</a>
--   for every pair.
--   
--   <pre>
--   let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing
--   differenceWith f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(3, "B"), (7, "C")]))
--       == Data.IntMap.singleton 3 "b:B"
--   </pre>
differenceWith :: (a -> b -> Maybe a) -> NEIntMap a -> NEIntMap b -> IntMap a

-- | <i>O(n+m)</i>. Difference with a combining function. When two equal
--   keys are encountered, the combining function is applied to the key and
--   both values. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>IntMap</a>), in case the first map
--   is a subset of the second map and the function returns <a>Nothing</a>
--   for every pair.
--   
--   <pre>
--   let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing
--   differenceWithKey f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(3, "B"), (10, "C")]))
--       == Data.IntMap.singleton 3 "3:b|B"
--   </pre>
differenceWithKey :: (Key -> a -> b -> Maybe a) -> NEIntMap a -> NEIntMap b -> IntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection of two maps. Return
--   data in the first map for the keys existing in both maps.
--   (<tt><a>intersection</a> m1 m2 == <a>intersectionWith</a> <a>const</a>
--   m1 m2</tt>).
--   
--   Returns a potentially empty map (<a>IntMap</a>), in case the two maps
--   share no keys in common.
--   
--   <pre>
--   intersection (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.IntMap.singleton 5 "a"
--   </pre>
intersection :: NEIntMap a -> NEIntMap b -> IntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection with a combining
--   function.
--   
--   Returns a potentially empty map (<a>IntMap</a>), in case the two maps
--   share no keys in common.
--   
--   <pre>
--   intersectionWith (++) (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.IntMap.singleton 5 "aA"
--   </pre>
intersectionWith :: (a -> b -> c) -> NEIntMap a -> NEIntMap b -> IntMap c

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection with a combining
--   function.
--   
--   Returns a potentially empty map (<a>IntMap</a>), in case the two maps
--   share no keys in common.
--   
--   <pre>
--   let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar
--   intersectionWithKey f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.IntMap.singleton 5 "5:a|A"
--   </pre>
intersectionWithKey :: (Key -> a -> b -> c) -> NEIntMap a -> NEIntMap b -> IntMap c

-- | <i>O(n)</i>. IntMap a function over all values in the map.
--   
--   <pre>
--   map (++ "x") (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "bx") :| [(5, "ax")])
--   </pre>
map :: (a -> b) -> NEIntMap a -> NEIntMap b

-- | <i>O(n)</i>. IntMap a function over all values in the map.
--   
--   <pre>
--   let f key x = (show key) ++ ":" ++ x
--   mapWithKey f (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "3:b") :| [(5, "5:a")])
--   </pre>
mapWithKey :: (Key -> a -> b) -> NEIntMap a -> NEIntMap b

-- | <i>O(n)</i>. <tt><a>traverseWithKey1</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse1</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt>
--   
--   That is, behaves exactly like a regular <a>traverse1</a> except that
--   the traversing function also has access to the key associated with a
--   value.
--   
--   <b>WARNING</b>: Differs from <tt>Data.IntMap.traverseWithKey</tt>,
--   which traverses positive items first, then negative items.
--   
--   Is more general than <a>traverseWithKey</a>, since works with all
--   <a>Apply</a>, and not just <a>Applicative</a>.
traverseWithKey1 :: Apply t => (Key -> a -> t b) -> NEIntMap a -> t (NEIntMap b)

-- | <i>O(n)</i>. <tt><a>traverseWithKey</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt> That is, behaves exactly like a regular
--   <a>traverse</a> except that the traversing function also has access to
--   the key associated with a value.
--   
--   <i>Use <a>traverseWithKey1</a></i> whenever possible (if your
--   <a>Applicative</a> also has <a>Apply</a> instance). This version is
--   provided only for types that do not have <a>Apply</a> instance, since
--   <a>Apply</a> is not at the moment (and might not ever be) an official
--   superclass of <a>Applicative</a>.
--   
--   <b>WARNING</b>: Differs from <tt>Data.IntMap.traverseWithKey</tt>,
--   which traverses positive items first, then negative items.
--   
--   <pre>
--   <a>traverseWithKey</a> f = <a>unwrapApplicative</a> . <a>traverseWithKey1</a> (\k -&gt; WrapApplicative . f k)
--   </pre>
traverseWithKey :: Applicative t => (Key -> a -> t b) -> NEIntMap a -> t (NEIntMap b)

-- | <i>O(n)</i>. The function <a>mapAccum</a> threads an accumulating
--   argument through the map in ascending order of keys.
--   
--   <pre>
--   let f a b = (a ++ b, b ++ "X")
--   mapAccum f "Everything: " (fromList ((5,"a") :| [(3,"b")])) == ("Everything: ba", fromList ((3, "bX") :| [(5, "aX")]))
--   </pre>
mapAccum :: (a -> b -> (a, c)) -> a -> NEIntMap b -> (a, NEIntMap c)

-- | <i>O(n)</i>. The function <a>mapAccumWithKey</a> threads an
--   accumulating argument through the map in ascending order of keys.
--   
--   <pre>
--   let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X")
--   mapAccumWithKey f "Everything:" (fromList ((5,"a") :| [(3,"b")])) == ("Everything: 3-b 5-a", fromList ((3, "bX") :| [(5, "aX")]))
--   </pre>
mapAccumWithKey :: (a -> Key -> b -> (a, c)) -> a -> NEIntMap b -> (a, NEIntMap c)

-- | <i>O(n)</i>. The function <a>mapAccumRWithKey</a> threads an
--   accumulating argument through the map in descending order of keys.
mapAccumRWithKey :: (a -> Key -> b -> (a, c)) -> a -> NEIntMap b -> (a, NEIntMap c)

-- | <i>O(n*log n)</i>. <tt><a>mapKeys</a> f s</tt> is the map obtained by
--   applying <tt>f</tt> to each key of <tt>s</tt>.
--   
--   The size of the result may be smaller if <tt>f</tt> maps two or more
--   distinct keys to the same new key. In this case the value at the
--   greatest of the original keys is retained.
--   
--   While the size of the result map may be smaller than the input map,
--   the output map is still guaranteed to be non-empty if the input map is
--   non-empty.
--   
--   <pre>
--   mapKeys (+ 1) (fromList ((5,"a") :| [(3,"b")]))                        == fromList ((4, "b") :| [(6, "a")])
--   mapKeys (\ _ -&gt; 1) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 1 "c"
--   mapKeys (\ _ -&gt; 3) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 3 "c"
--   </pre>
mapKeys :: (Key -> Key) -> NEIntMap a -> NEIntMap a

-- | <i>O(n*log n)</i>. <tt><a>mapKeysWith</a> c f s</tt> is the map
--   obtained by applying <tt>f</tt> to each key of <tt>s</tt>.
--   
--   The size of the result may be smaller if <tt>f</tt> maps two or more
--   distinct keys to the same new key. In this case the associated values
--   will be combined using <tt>c</tt>. The value at the greater of the two
--   original keys is used as the first argument to <tt>c</tt>.
--   
--   While the size of the result map may be smaller than the input map,
--   the output map is still guaranteed to be non-empty if the input map is
--   non-empty.
--   
--   <pre>
--   mapKeysWith (++) (\ _ -&gt; 1) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 1 "cdab"
--   mapKeysWith (++) (\ _ -&gt; 3) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 3 "cdab"
--   </pre>
mapKeysWith :: (a -> a -> a) -> (Key -> Key) -> NEIntMap a -> NEIntMap a

-- | <i>O(n)</i>. <tt><a>mapKeysMonotonic</a> f s == <a>mapKeys</a> f
--   s</tt>, but works only when <tt>f</tt> is strictly monotonic. That is,
--   for any values <tt>x</tt> and <tt>y</tt>, if <tt>x</tt> &lt;
--   <tt>y</tt> then <tt>f x</tt> &lt; <tt>f y</tt>. <i>The precondition is
--   not checked.</i> Semi-formally, we have:
--   
--   <pre>
--   and [x &lt; y ==&gt; f x &lt; f y | x &lt;- ls, y &lt;- ls]
--                       ==&gt; mapKeysMonotonic f s == mapKeys f s
--       where ls = keys s
--   </pre>
--   
--   This means that <tt>f</tt> maps distinct original keys to distinct
--   resulting keys. This function has better performance than
--   <a>mapKeys</a>.
--   
--   While the size of the result map may be smaller than the input map,
--   the output map is still guaranteed to be non-empty if the input map is
--   non-empty.
--   
--   <pre>
--   mapKeysMonotonic (\ k -&gt; k * 2) (fromList ((5,"a") :| [(3,"b")])) == fromList ((6, "b") :| [(10, "a")])
--   valid (mapKeysMonotonic (\ k -&gt; k * 2) (fromList ((5,"a") :| [(3,"b")]))) == True
--   valid (mapKeysMonotonic (\ _ -&gt; 1)     (fromList ((5,"a") :| [(3,"b")]))) == False
--   </pre>
mapKeysMonotonic :: (Key -> Key) -> NEIntMap a -> NEIntMap a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList map = foldr (:) [] map
--   </pre>
--   
--   <pre>
--   let f a len = len + (length a)
--   foldr f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldr :: (a -> b -> b) -> b -> NEIntMap a -> b

-- | <i>O(n)</i>. Fold the values in the map using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList = reverse . foldl (flip (:)) []
--   </pre>
--   
--   <pre>
--   let f len a = len + (length a)
--   foldl f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldl :: (a -> b -> a) -> a -> NEIntMap b -> a

-- | <i>O(n)</i>. A version of <a>foldr</a> that uses the value at the
--   maximal key in the map as the starting value.
--   
--   Note that, unlike <a>foldr1</a> for <a>IntMap</a>, this function is
--   total if the input function is total.
foldr1 :: (a -> a -> a) -> NEIntMap a -> a

-- | <i>O(n)</i>. A version of <a>foldl</a> that uses the value at the
--   minimal key in the map as the starting value.
--   
--   Note that, unlike <a>foldl1</a> for <a>IntMap</a>, this function is
--   total if the input function is total.
foldl1 :: (a -> a -> a) -> NEIntMap a -> a

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   right-associative binary operator, such that <tt><a>foldrWithKey</a> f
--   z == <a>foldr</a> (<a>uncurry</a> f) z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   keysList map = foldrWithKey (\k x ks -&gt; k:ks) [] map
--   </pre>
foldrWithKey :: (Key -> a -> b -> b) -> b -> NEIntMap a -> b

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   left-associative binary operator, such that <tt><a>foldlWithKey</a> f
--   z == <a>foldl</a> (\z' (kx, x) -&gt; f z' kx x) z .
--   <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   keysList = reverse . foldlWithKey (\ks k x -&gt; k:ks) []
--   </pre>
foldlWithKey :: (a -> Key -> b -> a) -> a -> NEIntMap b -> a

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   semigroup, such that
--   
--   <pre>
--   <a>foldMapWithKey</a> f = <a>fold1</a> . <a>mapWithKey</a> f
--   </pre>
--   
--   <b>WARNING</b>: Differs from <tt>Data.IntMap.foldMapWithKey</tt>,
--   which traverses positive items first, then negative items.
--   
--   This can be an asymptotically faster than <a>foldrWithKey</a> or
--   <a>foldlWithKey</a> for some monoids.
foldMapWithKey :: Semigroup m => (Key -> a -> m) -> NEIntMap a -> m

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> NEIntMap a -> b

-- | <i>O(n)</i>. A strict version of <a>foldr1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldr1' :: (a -> a -> a) -> NEIntMap a -> a

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> NEIntMap b -> a

-- | <i>O(n)</i>. A strict version of <a>foldl1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldl1' :: (a -> a -> a) -> NEIntMap a -> a

-- | <i>O(n)</i>. A strict version of <a>foldrWithKey</a>. Each application
--   of the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldrWithKey' :: (Key -> a -> b -> b) -> b -> NEIntMap a -> b

-- | <i>O(n)</i>. A strict version of <a>foldlWithKey</a>. Each application
--   of the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldlWithKey' :: (a -> Key -> b -> a) -> a -> NEIntMap b -> a

-- | <i>O(n)</i>. Return all elements of the map in the ascending order of
--   their keys.
--   
--   <pre>
--   elems (fromList ((5,"a") :| [(3,"b")])) == ("b" :| ["a"])
--   </pre>
elems :: NEIntMap a -> NonEmpty a

-- | <i>O(n)</i>. Return all keys of the map in ascending order.
--   
--   <pre>
--   keys (fromList ((5,"a") :| [(3,"b")])) == (3 :| [5])
--   </pre>
keys :: NEIntMap a -> NonEmpty Key

-- | <i>O(n)</i>. An alias for <a>toAscList</a>. Return all key/value pairs
--   in the map in ascending key order.
--   
--   <pre>
--   assocs (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
assocs :: NEIntMap a -> NonEmpty (Key, a)

-- | <i>O(n)</i>. The non-empty set of all keys of the map.
--   
--   <pre>
--   keysSet (fromList ((5,"a") :| [(3,"b")])) == Data.Set.NonEmpty.fromList (3 :| [5])
--   </pre>
keysSet :: NEIntMap a -> NEIntSet

-- | <i>O(n)</i>. Convert the map to a non-empty list of key/value pairs.
--   
--   <pre>
--   toList (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
toList :: NEIntMap a -> NonEmpty (Key, a)

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in ascending order.
--   
--   <pre>
--   toAscList (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
toAscList :: NEIntMap a -> NonEmpty (Key, a)

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in descending order.
--   
--   <pre>
--   toDescList (fromList ((5,"a") :| [(3,"b")])) == ((5,"a") :| [(3,"b")])
--   </pre>
toDescList :: NEIntMap a -> NonEmpty (Key, a)

-- | <i>O(n)</i>. Filter all values that satisfy the predicate.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because we could
--   potentailly filter out all items in the original <a>NEIntMap</a>.
--   
--   <pre>
--   filter (&gt; "a") (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 3 "b"
--   filter (&gt; "x") (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.empty
--   filter (&lt; "a") (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.empty
--   </pre>
filter :: (a -> Bool) -> NEIntMap a -> IntMap a

-- | <i>O(n)</i>. Filter all keys/values that satisfy the predicate.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because we could
--   potentailly filter out all items in the original <a>NEIntMap</a>.
--   
--   <pre>
--   filterWithKey (\k _ -&gt; k &gt; 4) (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "a"
--   </pre>
filterWithKey :: (Key -> a -> Bool) -> NEIntMap a -> IntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Restrict an <a>NEIntMap</a> to
--   only those keys found in a <a>Set</a>.
--   
--   <pre>
--   m `restrictKeys` s = <a>filterWithKey</a> (k _ -&gt; k <a>`member`</a> s) m
--   m `restrictKeys` s = m <a>`intersection`</a> <a>fromSet</a> (const ()) s
--   </pre>
restrictKeys :: NEIntMap a -> IntSet -> IntMap a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Remove all keys in a <a>Set</a>
--   from an <a>NEIntMap</a>.
--   
--   <pre>
--   m `withoutKeys` s = <a>filterWithKey</a> (k _ -&gt; k <a>`notMember`</a> s) m
--   m `withoutKeys` s = m <a>`difference`</a> <a>fromSet</a> (const ()) s
--   </pre>
withoutKeys :: NEIntMap a -> IntSet -> IntMap a

-- | <i>O(n)</i>. Partition the map according to a predicate.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate was true for all
--   items.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate was false for all
--   items.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (all of the items
--   that were true for the predicate) and <tt>n2</tt> (all of the items
--   that were false for the predicate).</li>
--   </ul>
--   
--   See also <a>split</a>.
--   
--   <pre>
--   partition (&gt; "a") (fromList ((5,"a") :| [(3,"b")])) == These (singleton 3 "b") (singleton 5 "a")
--   partition (&lt; "x") (fromList ((5,"a") :| [(3,"b")])) == This  (fromList ((3, "b") :| [(5, "a")]))
--   partition (&gt; "x") (fromList ((5,"a") :| [(3,"b")])) == That  (fromList ((3, "b") :| [(5, "a")]))
--   </pre>
partition :: (a -> Bool) -> NEIntMap a -> These (NEIntMap a) (NEIntMap a)

-- | <i>O(n)</i>. Partition the map according to a predicate.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate was true for all
--   items, returning the original map.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate was false for all
--   items, returning the original map.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (all of the items
--   that were true for the predicate) and <tt>n2</tt> (all of the items
--   that were false for the predicate).</li>
--   </ul>
--   
--   See also <a>split</a>.
--   
--   <pre>
--   partitionWithKey (\ k _ -&gt; k &gt; 3) (fromList ((5,"a") :| [(3,"b")])) == These (singleton 5 "a") (singleton 3 "b")
--   partitionWithKey (\ k _ -&gt; k &lt; 7) (fromList ((5,"a") :| [(3,"b")])) == This  (fromList ((3, "b") :| [(5, "a")]))
--   partitionWithKey (\ k _ -&gt; k &gt; 7) (fromList ((5,"a") :| [(3,"b")])) == That  (fromList ((3, "b") :| [(5, "a")]))
--   </pre>
partitionWithKey :: (Key -> a -> Bool) -> NEIntMap a -> These (NEIntMap a) (NEIntMap a)

-- | <i>O(n)</i>. Map values and collect the <a>Just</a> results.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because the function
--   could potentially return <a>Nothing</a> on all items in the
--   <a>NEIntMap</a>.
--   
--   <pre>
--   let f x = if x == "a" then Just "new a" else Nothing
--   mapMaybe f (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "new a"
--   </pre>
mapMaybe :: (a -> Maybe b) -> NEIntMap a -> IntMap b

-- | <i>O(n)</i>. Map keys/values and collect the <a>Just</a> results.
--   
--   Returns a potentially empty map (<a>IntMap</a>), because the function
--   could potentially return <a>Nothing</a> on all items in the
--   <a>NEIntMap</a>.
--   
--   <pre>
--   let f k _ = if k &lt; 5 then Just ("key : " ++ (show k)) else Nothing
--   mapMaybeWithKey f (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 3 "key : 3"
--   </pre>
mapMaybeWithKey :: (Key -> a -> Maybe b) -> NEIntMap a -> IntMap b

-- | <i>O(n)</i>. Map values and separate the <a>Left</a> and <a>Right</a>
--   results.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the results were all
--   <a>Left</a>.</li>
--   <li><tt><a>That</a> n2</tt> means that the results were all
--   <a>Right</a>.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (the map where the
--   results were <a>Left</a>) and <tt>n2</tt> (the map where the results
--   were <a>Right</a>)</li>
--   </ul>
--   
--   <pre>
--   let f a = if a &lt; "c" then Left a else Right a
--   mapEither f (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == These (fromList ((3,"b") :| [(5,"a")])) (fromList ((1,"x") :| [(7,"z")]))
--   
--   mapEither (\ a -&gt; Right a) (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == That (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--   </pre>
mapEither :: (a -> Either b c) -> NEIntMap a -> These (NEIntMap b) (NEIntMap c)

-- | <i>O(n)</i>. Map keys/values and separate the <a>Left</a> and
--   <a>Right</a> results.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the results were all
--   <a>Left</a>.</li>
--   <li><tt><a>That</a> n2</tt> means that the results were all
--   <a>Right</a>.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (the map where the
--   results were <a>Left</a>) and <tt>n2</tt> (the map where the results
--   were <a>Right</a>)</li>
--   </ul>
--   
--   <pre>
--   let f k a = if k &lt; 5 then Left (k * 2) else Right (a ++ a)
--   mapEitherWithKey f (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == These (fromList ((1,2) :| [(3,6)])) (fromList ((5,"aa") :| [(7,"zz")]))
--   
--   mapEitherWithKey (\_ a -&gt; Right a) (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == That (fromList ((1,"x") :| [(3,"b"), (5,"a"), (7,"z")]))
--   </pre>
mapEitherWithKey :: (Key -> a -> Either b c) -> NEIntMap a -> These (NEIntMap b) (NEIntMap c)

-- | <i>O(log n)</i>. The expression (<tt><a>split</a> k map</tt>) is
--   potentially a <a>These</a> containing up to two <a>NEIntMap</a>s based
--   on splitting the map into maps containing items before and after the
--   given key <tt>k</tt>. It will never return a map that contains
--   <tt>k</tt> itself.
--   
--   <ul>
--   <li><a>Nothing</a> means that <tt>k</tt> was the only key in the the
--   original map, and so there are no items before or after it.</li>
--   <li><tt><a>Just</a> (<a>This</a> n1)</tt> means <tt>k</tt> was larger
--   than or equal to all items in the map, and <tt>n1</tt> is the entire
--   original map (minus <tt>k</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>That</a> n2)</tt> means <tt>k</tt> was smaller
--   than or equal to all items in the map, and <tt>n2</tt> is the entire
--   original map (minus <tt>k</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>These</a> n1 n2)</tt> gives <tt>n1</tt> (the
--   map of all keys from the original map less than <tt>k</tt>) and
--   <tt>n2</tt> (the map of all keys from the original map greater than
--   <tt>k</tt>)</li>
--   </ul>
--   
--   <pre>
--   split 2 (fromList ((5,"a") :| [(3,"b")])) == Just (That  (fromList ((3,"b") :| [(5,"a")]))  )
--   split 3 (fromList ((5,"a") :| [(3,"b")])) == Just (That  (singleton 5 "a")                  )
--   split 4 (fromList ((5,"a") :| [(3,"b")])) == Just (These (singleton 3 "b") (singleton 5 "a"))
--   split 5 (fromList ((5,"a") :| [(3,"b")])) == Just (This  (singleton 3 "b")                  )
--   split 6 (fromList ((5,"a") :| [(3,"b")])) == Just (This  (fromList ((3,"b") :| [(5,"a")]))  )
--   split 5 (singleton 5 "a")                 == Nothing
--   </pre>
split :: Key -> NEIntMap a -> Maybe (These (NEIntMap a) (NEIntMap a))

-- | <i>O(log n)</i>. The expression (<tt><a>splitLookup</a> k map</tt>)
--   splits a map just like <a>split</a> but also returns <tt><a>lookup</a>
--   k map</tt>, as the first field in the <a>These</a>:
--   
--   <pre>
--   splitLookup 2 (fromList ((5,"a") :| [(3,"b")])) == That      (That  (fromList ((3,"b") :| [(5,"a")])))
--   splitLookup 3 (fromList ((5,"a") :| [(3,"b")])) == These "b" (That  (singleton 5 "a"))
--   splitLookup 4 (fromList ((5,"a") :| [(3,"b")])) == That      (These (singleton 3 "b") (singleton 5 "a"))
--   splitLookup 5 (fromList ((5,"a") :| [(3,"b")])) == These "a" (This  (singleton 3 "b"))
--   splitLookup 6 (fromList ((5,"a") :| [(3,"b")])) == That      (This  (fromList ((3,"b") :| [(5,"a")])))
--   splitLookup 5 (singleton 5 "a")                 == This  "a"
--   </pre>
splitLookup :: Key -> NEIntMap a -> These a (These (NEIntMap a) (NEIntMap a))

-- | <i>O(1)</i>. Decompose a map into pieces based on the structure of the
--   underlying tree. This function is useful for consuming a map in
--   parallel.
--   
--   No guarantee is made as to the sizes of the pieces; an internal, but
--   deterministic process determines this. However, it is guaranteed that
--   the pieces returned will be in ascending order (all elements in the
--   first submap less than all elements in the second, and so on).
--   
--   Note that the current implementation does not return more than four
--   submaps, but you should not depend on this behaviour because it can
--   change in the future without notice.
splitRoot :: NEIntMap a -> NonEmpty (NEIntMap a)

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. This function is defined as
--   (<tt><a>isSubmapOf</a> = <a>isSubmapOfBy</a> (==)</tt>).
isSubmapOf :: Eq a => NEIntMap a -> NEIntMap a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression
--   (<tt><a>isSubmapOfBy</a> f t1 t2</tt>) returns <a>True</a> if all keys
--   in <tt>t1</tt> are in tree <tt>t2</tt>, and when <tt>f</tt> returns
--   <a>True</a> when applied to their respective values. For example, the
--   following expressions are all <a>True</a>:
--   
--   <pre>
--   isSubmapOfBy (==) (singleton 'a' 1) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (&lt;=) (singleton 'a' 1) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (==) (fromList (('a',1) :| [('b',2)])) (fromList (('a',1) :| [('b',2)]))
--   </pre>
--   
--   But the following are all <a>False</a>:
--   
--   <pre>
--   isSubmapOfBy (==) (singleton 'a' 2) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (&lt;)  (singleton 'a' 1) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (==) (fromList (('a',1) :| [('b',2)])) (singleton 'a' 1)
--   </pre>
isSubmapOfBy :: (a -> b -> Bool) -> NEIntMap a -> NEIntMap b -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Is this a proper submap? (ie. a
--   submap but not equal). Defined as (<tt><a>isProperSubmapOf</a> =
--   <a>isProperSubmapOfBy</a> (==)</tt>).
isProperSubmapOf :: Eq a => NEIntMap a -> NEIntMap a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Is this a proper submap? (ie. a
--   submap but not equal). The expression (<tt><a>isProperSubmapOfBy</a> f
--   m1 m2</tt>) returns <a>True</a> when <tt>m1</tt> and <tt>m2</tt> are
--   not equal, all keys in <tt>m1</tt> are in <tt>m2</tt>, and when
--   <tt>f</tt> returns <a>True</a> when applied to their respective
--   values. For example, the following expressions are all <a>True</a>:
--   
--   <pre>
--   isProperSubmapOfBy (==) (singleton 1 1) (fromList ((1,1) :| [(2,2)]))
--   isProperSubmapOfBy (&lt;=) (singleton 1 1) (fromList ((1,1) :| [(2,2)]))
--   </pre>
--   
--   But the following are all <a>False</a>:
--   
--   <pre>
--   isProperSubmapOfBy (==) (fromList ((1,1) :| [(2,2)])) (fromList ((1,1) :| [(2,2)]))
--   isProperSubmapOfBy (==) (fromList ((1,1) :| [(2,2)])) (singleton 1 1))
--   isProperSubmapOfBy (&lt;)  (singleton 1 1)               (fromList ((1,1) :| [(2,2)]))
--   </pre>
isProperSubmapOfBy :: (a -> b -> Bool) -> NEIntMap a -> NEIntMap b -> Bool

-- | <i>O(1)</i>. The minimal key of the map. Note that this is total,
--   making <a>lookupMin</a> obsolete. It is constant-time, so has better
--   asymptotics than <tt>Data.IntMap.lookupMin</tt> and
--   <tt>Data.IntMap.findMin</tt>, as well.
--   
--   <pre>
--   findMin (fromList ((5,"a") :| [(3,"b")])) == (3,"b")
--   </pre>
findMin :: NEIntMap a -> (Key, a)

-- | <i>O(log n)</i>. The maximal key of the map. Note that this is total,
--   making <a>lookupMin</a> obsolete.
--   
--   <pre>
--   findMax (fromList ((5,"a") :| [(3,"b")])) == (5,"a")
--   </pre>
findMax :: NEIntMap a -> (Key, a)

-- | <i>O(1)</i>. Delete the minimal key. Returns a potentially empty map
--   (<a>IntMap</a>), because we might end up deleting the final key in a
--   singleton map. It is constant-time, so has better asymptotics than
--   <a>deleteMin</a>.
--   
--   <pre>
--   deleteMin (fromList ((5,"a") :| [(3,"b"), (7,"c")])) == Data.IntMap.fromList [(5,"a"), (7,"c")]
--   deleteMin (singleton 5 "a") == Data.IntMap.empty
--   </pre>
deleteMin :: NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. Delete the maximal key. Returns a potentially empty
--   map (<a>IntMap</a>), because we might end up deleting the final key in
--   a singleton map.
--   
--   <pre>
--   deleteMax (fromList ((5,"a") :| [(3,"b"), (7,"c")])) == Data.IntMap.fromList [(3,"b"), (5,"a")]
--   deleteMax (singleton 5 "a") == Data.IntMap.empty
--   </pre>
deleteMax :: NEIntMap a -> IntMap a

-- | <i>O(1)</i>. Delete and find the minimal key-value pair. It is
--   constant-time, so has better asymptotics that
--   <tt>Data.IntMap.minView</tt> for <a>IntMap</a>.
--   
--   Note that unlike <tt>Data.IntMap.deleteFindMin</tt> for <a>IntMap</a>,
--   this cannot ever fail, and so is a total function. However, the result
--   <a>IntMap</a> is potentially empty, since the original map might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMin (fromList ((5,"a") :| [(3,"b"), (10,"c")])) == ((3,"b"), Data.IntMap.fromList [(5,"a"), (10,"c")])
--   </pre>
deleteFindMin :: NEIntMap a -> ((Key, a), IntMap a)

-- | <i>O(log n)</i>. Delete and find the minimal key-value pair.
--   
--   Note that unlike <tt>Data.IntMap.deleteFindMax</tt> for <a>IntMap</a>,
--   this cannot ever fail, and so is a total function. However, the result
--   <a>IntMap</a> is potentially empty, since the original map might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMax (fromList ((5,"a") :| [(3,"b"), (10,"c")])) == ((10,"c"), Data.IntMap.fromList [(3,"b"), (5,"a")])
--   </pre>
deleteFindMax :: NEIntMap a -> ((Key, a), IntMap a)

-- | <i>O(1)</i> if delete, <i>O(log n)</i> otherwise. Update the value at
--   the minimal key. Returns a potentially empty map (<a>IntMap</a>),
--   because we might end up deleting the final key in the map if the
--   function returns <a>Nothing</a>. See <a>adjustMin</a> for a version
--   that can guaruntee that we return a non-empty map.
--   
--   <pre>
--   updateMin (\ a -&gt; Just ("X" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "Xb"), (5, "a")]
--   updateMin (\ _ -&gt; Nothing)         (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "a"
--   </pre>
updateMin :: (a -> Maybe a) -> NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. Update the value at the maximal key. Returns a
--   potentially empty map (<a>IntMap</a>), because we might end up
--   deleting the final key in the map if the function returns
--   <a>Nothing</a>. See <a>adjustMax</a> for a version that can guarantee
--   that we return a non-empty map.
--   
--   <pre>
--   updateMax (\ a -&gt; Just ("X" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3, "b"), (5, "Xa")]
--   updateMax (\ _ -&gt; Nothing)         (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 3 "b"
--   </pre>
updateMax :: (a -> Maybe a) -> NEIntMap a -> IntMap a

-- | <i>O(1)</i>. A version of <a>updateMin</a> that disallows deletion,
--   allowing us to guarantee that the result is also non-empty.
adjustMin :: (a -> a) -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. A version of <a>updateMax</a> that disallows
--   deletion, allowing us to guarantee that the result is also non-empty.
adjustMax :: (a -> a) -> NEIntMap a -> NEIntMap a

-- | <i>O(1)</i> if delete, <i>O(log n)</i> otherwise. Update the value at
--   the minimal key. Returns a potentially empty map (<a>IntMap</a>),
--   because we might end up deleting the final key in the map if the
--   function returns <a>Nothing</a>. See <a>adjustMinWithKey</a> for a
--   version that guaruntees a non-empty map.
--   
--   <pre>
--   updateMinWithKey (\ k a -&gt; Just ((show k) ++ ":" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3,"3:b"), (5,"a")]
--   updateMinWithKey (\ _ _ -&gt; Nothing)                     (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "a"
--   </pre>
updateMinWithKey :: (Key -> a -> Maybe a) -> NEIntMap a -> IntMap a

-- | <i>O(log n)</i>. Update the value at the maximal key. Returns a
--   potentially empty map (<a>IntMap</a>), because we might end up
--   deleting the final key in the map if the function returns
--   <a>Nothing</a>. See <a>adjustMaxWithKey</a> for a version that
--   guaruntees a non-empty map.
--   
--   <pre>
--   updateMinWithKey (\ k a -&gt; Just ((show k) ++ ":" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.fromList [(3,"3:b"), (5,"a")]
--   updateMinWithKey (\ _ _ -&gt; Nothing)                     (fromList ((5,"a") :| [(3,"b")])) == Data.IntMap.singleton 5 "a"
--   </pre>
updateMaxWithKey :: (Key -> a -> Maybe a) -> NEIntMap a -> IntMap a

-- | <i>O(1)</i>. A version of <a>adjustMaxWithKey</a> that disallows
--   deletion, allowing us to guarantee that the result is also non-empty.
--   Note that it also is able to have better asymptotics than
--   <a>updateMinWithKey</a> in general.
adjustMinWithKey :: (Key -> a -> a) -> NEIntMap a -> NEIntMap a

-- | <i>O(log n)</i>. A version of <a>updateMaxWithKey</a> that disallows
--   deletion, allowing us to guarantee that the result is also non-empty.
adjustMaxWithKey :: (Key -> a -> a) -> NEIntMap a -> NEIntMap a

-- | <i>O(1)</i>. Retrieves the value associated with minimal key of the
--   map, and the map stripped of that element. It is constant-time, so has
--   better asymptotics than <tt>Data.IntMap.minView</tt> for
--   <a>IntMap</a>.
--   
--   Note that unlike <tt>Data.IntMap.minView</tt> for <a>IntMap</a>, this
--   cannot ever fail, so doesn't need to return in a <a>Maybe</a>.
--   However, the result <a>IntMap</a> is potentially empty, since the
--   original map might have contained just a single item.
--   
--   <pre>
--   minView (fromList ((5,"a") :| [(3,"b")])) == ("b", Data.IntMap.singleton 5 "a")
--   </pre>
minView :: NEIntMap a -> (a, IntMap a)

-- | <i>O(log n)</i>. Retrieves the value associated with maximal key of
--   the map, and the map stripped of that element.
--   
--   Note that unlike <tt>Data.IntMap.maxView</tt> from <a>IntMap</a>, this
--   cannot ever fail, so doesn't need to return in a <a>Maybe</a>.
--   However, the result <a>IntMap</a> is potentially empty, since the
--   original map might have contained just a single item.
--   
--   <pre>
--   maxView (fromList ((5,"a") :| [(3,"b")])) == ("a", Data.IntMap.singleton 3 "b")
--   </pre>
maxView :: NEIntMap a -> (a, IntMap a)

-- | <i>O(n)</i>. Test if the internal map structure is valid.
valid :: NEIntMap a -> Bool


-- | Unsafe internal-use functions used in the implementation of
--   <a>Data.Map.NonEmpty</a>. These functions can potentially be used to
--   break the abstraction of <a>NEMap</a> and produce unsound maps, so be
--   wary!
module Data.Map.NonEmpty.Internal

-- | A non-empty (by construction) map from keys <tt>k</tt> to values
--   <tt>a</tt>. At least one key-value pair exists in an <tt><a>NEMap</a>
--   k v</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NEMap</a> can safely operate on it
--   with the assumption that it has at least one key-value pair.
--   
--   Functions that <i>return</i> an <a>NEMap</a> provide an assurance that
--   the result has at least one key-value pair.
--   
--   <a>Data.Map.NonEmpty</a> re-exports the API of <a>Data.Map</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output maps are both
--   non-empty (like <a>insert</a>) return <a>NEMap</a>, but functions that
--   might potentially return an empty map (like <a>delete</a>) return a
--   <a>Map</a> instead.
--   
--   You can directly construct an <a>NEMap</a> with the API from
--   <a>Data.Map.NonEmpty</a>; it's more or less the same as constructing a
--   normal <a>Map</a>, except you don't have access to <a>empty</a>. There
--   are also a few ways to construct an <a>NEMap</a> from a <a>Map</a>:
--   
--   <ol>
--   <li>The <a>nonEmptyMap</a> smart constructor will convert a
--   <tt><a>Map</a> k a</tt> into a <tt><a>Maybe</a> (<a>NEMap</a> k
--   a)</tt>, returning <a>Nothing</a> if the original <a>Map</a> was
--   empty.</li>
--   <li>You can use the <a>insertMap</a> family of functions to insert a
--   value into a <a>Map</a> to create a guaranteed <a>NEMap</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>Map</a> to reveal it as either containing a
--   <a>NEMap</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>Map</a> and treating it as if it were an
--   <a>NEMap</a>.</li>
--   </ol>
--   
--   You can convert an <a>NEMap</a> into a <a>Map</a> with <a>toMap</a> or
--   <a>IsNonEmpty</a>, essentially "obscuring" the non-empty property from
--   the type.
data NEMap k a
NEMap :: !k -> a -> !Map k a -> NEMap k a

-- | invariant: must be smaller than smallest key in map
[nemK0] :: NEMap k a -> !k
[nemV0] :: NEMap k a -> a
[nemMap] :: NEMap k a -> !Map k a

-- | <i>O(1)</i>. A map with a single element.
--   
--   <pre>
--   singleton 1 'a'        == fromList ((1, 'a') :| [])
--   size (singleton 1 'a') == 1
--   </pre>
singleton :: k -> a -> NEMap k a

-- | <i>O(log n)</i>. Smart constructor for an <a>NEMap</a> from a
--   <a>Map</a>. Returns <a>Nothing</a> if the <a>Map</a> was originally
--   actually empty, and <tt><a>Just</a> n</tt> with an <a>NEMap</a>, if
--   the <a>Map</a> was not empty.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>Map</a> being an <a>NEMap</a>.
--   
--   <pre>
--   nonEmptyMap (Data.Map.fromList [(3,"a"), (5,"b")]) == Just (fromList ((3,"a") :| [(5,"b")]))
--   </pre>
nonEmptyMap :: Map k a -> Maybe (NEMap k a)

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>Map</a> as if it were an <a>NEMap</a>. <tt><a>withNonEmpty</a> def
--   f</tt> will take a <a>Map</a>. If map is empty, it will evaluate to
--   <tt>def</tt>. Otherwise, a non-empty map <a>NEMap</a> will be fed to
--   the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptyMap</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NEMap k a -> r) -> Map k a -> r

-- | <i>O(n*log n)</i>. Build a non-empty map from a non-empty list of
--   key/value pairs. See also <a>fromAscList</a>. If the list contains
--   more than one value for the same key, the last value for the key is
--   retained.
--   
--   <pre>
--   fromList ((5,"a") :| [(3,"b"), (5, "c")]) == fromList ((5,"c") :| [(3,"b")])
--   fromList ((5,"c") :| [(3,"b"), (5, "a")]) == fromList ((5,"a") :| [(3,"b")])
--   </pre>
fromList :: Ord k => NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Convert the map to a non-empty list of key/value pairs.
--   
--   <pre>
--   toList (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
toList :: NEMap k a -> NonEmpty (k, a)

-- | <i>O(n)</i>. Map a function over all values in the map.
--   
--   <pre>
--   map (++ "x") (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "bx") :| [(5, "ax")])
--   </pre>
map :: (a -> b) -> NEMap k a -> NEMap k b

-- | <i>O(log n)</i>. Insert with a function, combining new value and old
--   value. <tt><a>insertWith</a> f key value mp</tt> will insert the pair
--   (key, value) into <tt>mp</tt> if key does not exist in the map. If the
--   key does exist, the function will insert the pair <tt>(key, f
--   new_value old_value)</tt>.
--   
--   See <a>insertMapWith</a> for a version where the first argument is a
--   <a>Map</a>.
--   
--   <pre>
--   insertWith (++) 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "xxxa")])
--   insertWith (++) 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   </pre>
insertWith :: Ord k => (a -> a -> a) -> k -> a -> NEMap k a -> NEMap k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression (<tt><a>union</a>
--   t1 t2</tt>) takes the left-biased union of <tt>t1</tt> and
--   <tt>t2</tt>. It prefers <tt>t1</tt> when duplicate keys are
--   encountered, i.e. (<tt><a>union</a> == <a>unionWith</a>
--   <a>const</a></tt>).
--   
--   <pre>
--   union (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "a"), (7, "C")])
--   </pre>
union :: Ord k => NEMap k a -> NEMap k a -> NEMap k a

-- | The left-biased union of a non-empty list of maps.
--   
--   <pre>
--   unions (fromList ((5, "a") :| [(3, "b")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "A3") :| [(3, "B3")])])
--       == fromList [(3, "b"), (5, "a"), (7, "C")]
--   unions (fromList ((5, "A3") :| [(3, "B3")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "a") :| [(3, "b")])])
--       == fromList ((3, "B3") :| [(5, "A3"), (7, "C")])
--   </pre>
unions :: (Foldable1 f, Ord k) => f (NEMap k a) -> NEMap k a

-- | <i>O(n)</i>. Return all elements of the map in the ascending order of
--   their keys.
--   
--   <pre>
--   elems (fromList ((5,"a") :| [(3,"b")])) == ("b" :| ["a"])
--   </pre>
elems :: NEMap k a -> NonEmpty a

-- | <i>O(1)</i>. The number of elements in the map. Guaranteed to be
--   greater than zero.
--   
--   <pre>
--   size (singleton 1 'a')                          == 1
--   size (fromList ((1,'a') :| [(2,'c'), (3,'b')])) == 3
--   </pre>
size :: NEMap k a -> Int

-- | <i>O(log n)</i>. Convert a non-empty map back into a normal
--   possibly-empty map, for usage with functions that expect <a>Map</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the map in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toMap (fromList ((3,"a") :| [(5,"b")])) == Data.Map.fromList [(3,"a"), (5,"b")]
--   </pre>
toMap :: NEMap k a -> Map k a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList map = foldr (:) [] map
--   </pre>
--   
--   <pre>
--   let f a len = len + (length a)
--   foldr f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldr :: (a -> b -> b) -> b -> NEMap k a -> b

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> NEMap k a -> b

-- | <i>O(n)</i>. A version of <a>foldr</a> that uses the value at the
--   maximal key in the map as the starting value.
--   
--   Note that, unlike <a>foldr1</a> for <a>Map</a>, this function is total
--   if the input function is total.
foldr1 :: (a -> a -> a) -> NEMap k a -> a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList = reverse . foldl (flip (:)) []
--   </pre>
--   
--   <pre>
--   let f len a = len + (length a)
--   foldl f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldl :: (a -> b -> a) -> a -> NEMap k b -> a

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> NEMap k b -> a

-- | <i>O(n)</i>. A version of <a>foldl</a> that uses the value at the
--   minimal key in the map as the starting value.
--   
--   Note that, unlike <a>foldl1</a> for <a>Map</a>, this function is total
--   if the input function is total.
foldl1 :: (a -> a -> a) -> NEMap k a -> a

-- | <i>O(n)</i>. <tt><a>traverseWithKey</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt> That is, behaves exactly like a regular
--   <a>traverse</a> except that the traversing function also has access to
--   the key associated with a value.
--   
--   <i>Use <a>traverseWithKey1</a></i> whenever possible (if your
--   <a>Applicative</a> also has <a>Apply</a> instance). This version is
--   provided only for types that do not have <a>Apply</a> instance, since
--   <a>Apply</a> is not at the moment (and might not ever be) an official
--   superclass of <a>Applicative</a>.
--   
--   <pre>
--   <a>traverseWithKey</a> f = <a>unwrapApplicative</a> . <a>traverseWithKey1</a> (\k -&gt; WrapApplicative . f k)
--   </pre>
traverseWithKey :: Applicative t => (k -> a -> t b) -> NEMap k a -> t (NEMap k b)

-- | <i>O(n)</i>. <tt><a>traverseWithKey1</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse1</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt>
--   
--   That is, behaves exactly like a regular <a>traverse1</a> except that
--   the traversing function also has access to the key associated with a
--   value.
--   
--   Is more general than <a>traverseWithKey</a>, since works with all
--   <a>Apply</a>, and not just <a>Applicative</a>.
traverseWithKey1 :: Apply t => (k -> a -> t b) -> NEMap k a -> t (NEMap k b)

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   semigroup, such that
--   
--   <pre>
--   <a>foldMapWithKey</a> f = <a>fold1</a> . <a>mapWithKey</a> f
--   </pre>
--   
--   This can be an asymptotically faster than <a>foldrWithKey</a> or
--   <a>foldlWithKey</a> for some monoids.
foldMapWithKey :: Semigroup m => (k -> a -> m) -> NEMap k a -> m

-- | <i>O(log n)</i>. Insert new key and value into a map where keys are
--   <i>strictly greater than</i> the new key. That is, the new key must be
--   <i>strictly less than</i> all keys present in the <a>Map</a>. /The
--   precondition is not checked./
--   
--   While this has the same asymptotics as <tt>Data.Map.insert</tt>, it
--   saves a constant factor for key comparison (so may be helpful if
--   comparison is expensive) and also does not require an <a>Ord</a>
--   instance for the key type.
insertMinMap :: k -> a -> Map k a -> Map k a

-- | <i>O(log n)</i>. Insert new key and value into a map where keys are
--   <i>strictly less than</i> the new key. That is, the new key must be
--   <i>strictly greater than</i> all keys present in the <a>Map</a>. /The
--   precondition is not checked./
--   
--   While this has the same asymptotics as <tt>Data.Map.insert</tt>, it
--   saves a constant factor for key comparison (so may be helpful if
--   comparison is expensive) and also does not require an <a>Ord</a>
--   instance for the key type.
insertMaxMap :: k -> a -> Map k a -> Map k a

-- | <i>O(n)</i>. Test if the internal map structure is valid.
valid :: Ord k => NEMap k a -> Bool
instance (GHC.Classes.Eq k, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Map.NonEmpty.Internal.NEMap k a)
instance (GHC.Classes.Ord k, GHC.Classes.Ord a) => GHC.Classes.Ord (Data.Map.NonEmpty.Internal.NEMap k a)
instance Data.Functor.Classes.Eq2 Data.Map.NonEmpty.Internal.NEMap
instance GHC.Classes.Eq k => Data.Functor.Classes.Eq1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Functor.Classes.Ord2 Data.Map.NonEmpty.Internal.NEMap
instance GHC.Classes.Ord k => Data.Functor.Classes.Ord1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Functor.Classes.Show2 Data.Map.NonEmpty.Internal.NEMap
instance GHC.Show.Show k => Data.Functor.Classes.Show1 (Data.Map.NonEmpty.Internal.NEMap k)
instance (GHC.Classes.Ord k, GHC.Read.Read k) => Data.Functor.Classes.Read1 (Data.Map.NonEmpty.Internal.NEMap k)
instance (GHC.Classes.Ord k, GHC.Read.Read k, GHC.Read.Read e) => GHC.Read.Read (Data.Map.NonEmpty.Internal.NEMap k e)
instance (GHC.Show.Show k, GHC.Show.Show a) => GHC.Show.Show (Data.Map.NonEmpty.Internal.NEMap k a)
instance (Control.DeepSeq.NFData k, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Data.Map.NonEmpty.Internal.NEMap k a)
instance (Data.Data.Data k, Data.Data.Data a, GHC.Classes.Ord k) => Data.Data.Data (Data.Map.NonEmpty.Internal.NEMap k a)
instance (Data.Aeson.Types.ToJSON.ToJSONKey k, Data.Aeson.Types.ToJSON.ToJSON a) => Data.Aeson.Types.ToJSON.ToJSON (Data.Map.NonEmpty.Internal.NEMap k a)
instance (Data.Aeson.Types.FromJSON.FromJSONKey k, GHC.Classes.Ord k, Data.Aeson.Types.FromJSON.FromJSON a) => Data.Aeson.Types.FromJSON.FromJSON (Data.Map.NonEmpty.Internal.NEMap k a)
instance GHC.Classes.Ord k => GHC.Base.Semigroup (Data.Map.NonEmpty.Internal.NEMap k a)
instance GHC.Base.Functor (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Foldable.Foldable (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Traversable.Traversable (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Semigroup.Foldable.Class.Foldable1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Semigroup.Traversable.Class.Traversable1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Control.Comonad.Comonad (Data.Map.NonEmpty.Internal.NEMap k)


-- | Unsafe internal-use functions used in the implementation of
--   <a>Data.Sequence.NonEmpty</a>. These functions can potentially be used
--   to break the abstraction of <a>NESeq</a> and produce unsound
--   sequences, so be wary!
module Data.Sequence.NonEmpty.Internal

-- | A general-purpose non-empty (by construction) finite sequence type.
--   
--   Non-emptiness means that:
--   
--   <ul>
--   <li>Functions that <i>take</i> an <a>NESeq</a> can safely operate on
--   it with the assumption that it has at least value.</li>
--   <li>Functions that <i>return</i> an <a>NESeq</a> provide an assurance
--   that the result has at least one value.</li>
--   </ul>
--   
--   <a>Data.Sequence.NonEmpty</a> re-exports the API of
--   <a>Data.Sequence</a>, faithfully reproducing asymptotics, typeclass
--   constraints, and semantics. Functions that ensure that input and
--   output maps are both non-empty (like <a>&lt;|</a>) return
--   <a>NESeq</a>, but functions that might potentially return an empty map
--   (like <a>tail</a>) return a <a>Seq</a> instead.
--   
--   You can directly construct an <a>NESeq</a> with the API from
--   <a>Data.Sequence.NonEmpty</a>; it's more or less the same as
--   constructing a normal <a>Seq</a>, except you don't have access to
--   <a>empty</a>. There are also a few ways to construct an <a>NESeq</a>
--   from a <a>Seq</a>:
--   
--   <ol>
--   <li>The <a>nonEmptySeq</a> smart constructor will convert a
--   <tt><a>Seq</a> a</tt> into a <tt><a>Maybe</a> (<a>NESeq</a> a)</tt>,
--   returning <a>Nothing</a> if the original <a>Seq</a> was empty.</li>
--   <li>You can use <a>:&lt;||</a>, <a>:||&gt;</a>, and <a>insertSeqAt</a>
--   to insert a value into a <a>Seq</a> to create a guaranteed
--   <a>NESeq</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>Seq</a> to reveal it as either containing a
--   <a>NESeq</a> or an empty sequence.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>Seq</a> and treating it as if it were an
--   <a>NESeq</a>.</li>
--   </ol>
--   
--   You can convert an <a>NESeq</a> into a <a>Seq</a> with <a>toSeq</a> or
--   <a>IsNonEmpty</a>, essentially "obscuring" the non-empty property from
--   the type.
data NESeq a
NESeq :: a -> !Seq a -> NESeq a
[nesHead] :: NESeq a -> a
[nesTail] :: NESeq a -> !Seq a
infixr 5 `NESeq`
infixr 5 `NESeq`

-- | <i>O(1)</i>. An abstract constructor for an <a>NESeq</a> that consists
--   of a "head" <tt>a</tt> and a "tail" <tt><a>Seq</a> a</tt>. Similar to
--   <a>:|</a> for <a>NonEmpty</a>.
--   
--   Can be used to match on the head and tail of an <a>NESeq</a>, and also
--   used to <i>construct</i> an <a>NESeq</a> by consing an item to the
--   beginnong of a <a>Seq</a>, ensuring that the result is non-empty.
pattern (:<||) :: a -> Seq a -> NESeq a
infixr 5 :<||

-- | <i>O(1)</i>. An abstract constructor for an <a>NESeq</a> that consists
--   of a "init" <tt><a>Seq</a> a</tt> and a "last" <tt>a</tt>. Similar to
--   <a>:|</a> for <a>NonEmpty</a>, but at the end of the list instead of
--   at the beginning.
--   
--   Can be used to match on the init and last of an <a>NESeq</a>, and also
--   used to <i>construct</i> an <a>NESeq</a> by snocing an item to the end
--   of a <a>Seq</a>, ensuring that the result is non-empty.
pattern (:||>) :: Seq a -> a -> NESeq a
infixl 5 :||>

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>Seq</a> as if it were an <a>NESeq</a>. <tt><a>withNonEmpty</a> def
--   f</tt> will take a <a>Seq</a>. If map is empty, it will evaluate to
--   <tt>def</tt>. Otherwise, a non-empty map <a>NESeq</a> will be fed to
--   the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptySeq</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NESeq a -> r) -> Seq a -> r

-- | <i>O(1)</i>. Convert a non-empty sequence back into a normal
--   possibly-empty sequence, for usage with functions that expect
--   <a>Seq</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the map in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptySeq</a> and <tt><a>maybe</a> <a>empty</a> <a>toSeq</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
toSeq :: NESeq a -> Seq a

-- | &lt;math&gt;. A singleton sequence.
singleton :: a -> NESeq a

-- | &lt;math&gt;. The number of elements in the sequence.
length :: NESeq a -> Int

-- | &lt;math&gt;. Create a sequence from a finite list of elements. There
--   is a function <a>toNonEmpty</a> in the opposite direction for all
--   instances of the <a>Foldable1</a> class, including <a>NESeq</a>.
fromList :: NonEmpty a -> NESeq a

-- | &lt;math&gt;. Convert a given sequence length and a function
--   representing that sequence into a sequence.
fromFunction :: Int -> (Int -> a) -> NESeq a

-- | &lt;math&gt;. <tt>replicate n x</tt> is a sequence consisting of
--   <tt>n</tt> copies of <tt>x</tt>. Is only defined when <tt>n</tt> is
--   positive.
replicate :: Int -> a -> NESeq a

-- | &lt;math&gt;. The element at the specified position, counting from 0.
--   The argument should thus be a non-negative integer less than the size
--   of the sequence. If the position is out of range, <a>index</a> fails
--   with an error.
--   
--   <pre>
--   xs `index` i = toList xs !! i
--   </pre>
--   
--   Caution: <a>index</a> necessarily delays retrieving the requested
--   element until the result is forced. It can therefore lead to a space
--   leak if the result is stored, unforced, in another structure. To
--   retrieve an element immediately without forcing it, use <a>lookup</a>
--   or <tt>(!?)</tt>.
index :: NESeq a -> Int -> a

-- | &lt;math&gt;. Add an element to the left end of a non-empty sequence.
--   Mnemonic: a triangle with the single element at the pointy end.
(<|) :: a -> NESeq a -> NESeq a
infixr 5 <|

-- | &lt;math&gt;. Concatenate two non-empty sequences.
(><) :: NESeq a -> NESeq a -> NESeq a
infixr 5 ><

-- | &lt;math&gt;. Concatenate a non-empty sequence with a potentially
--   empty sequence (<a>Seq</a>), to produce a guaranteed non-empty
--   sequence. Mnemonic: like <a>&gt;&lt;</a>, but a pipe for the
--   guarunteed non-empty side.
(|><) :: NESeq a -> Seq a -> NESeq a
infixr 5 |><

-- | Defined here but hidden; intended for use with RULES pragma.
map :: (a -> b) -> NESeq a -> NESeq b

-- | <i>O(n)</i>. A generalization of <a>foldMap1</a>,
--   <a>foldMapWithIndex</a> takes a folding function that also depends on
--   the element's index, and applies it to every element in the sequence.
foldMapWithIndex :: Semigroup m => (Int -> a -> m) -> NESeq a -> m

-- | <i>O(n)</i>. <a>traverseWithIndex1</a> is a version of
--   <a>traverse1</a> that also offers access to the index of each element.
traverseWithIndex1 :: Apply f => (Int -> a -> f b) -> NESeq a -> f (NESeq b)

-- | &lt;math&gt;. Returns a sequence of all non-empty suffixes of this
--   sequence, longest first. For example,
--   
--   <pre>
--   tails (fromList (1:|[2,3])) = fromList (fromList (1:|[2,3]) :| [fromList (2:|[3]), fromList (3:|[])])
--   </pre>
--   
--   Evaluating the &lt;math&gt;th suffix takes &lt;math&gt;, but
--   evaluating every suffix in the sequence takes &lt;math&gt; due to
--   sharing.
tails :: NESeq a -> NESeq (NESeq a)

-- | &lt;math&gt;. <a>zip</a> takes two sequences and returns a sequence of
--   corresponding pairs. If one input is short, excess elements are
--   discarded from the right end of the longer sequence.
zip :: NESeq a -> NESeq b -> NESeq (a, b)

-- | &lt;math&gt;. <a>zipWith</a> generalizes <a>zip</a> by zipping with
--   the function given as the first argument, instead of a tupling
--   function. For example, <tt>zipWith (+)</tt> is applied to two
--   sequences to take the sequence of corresponding sums.
zipWith :: (a -> b -> c) -> NESeq a -> NESeq b -> NESeq c

-- | Unzip a sequence of pairs.
--   
--   <pre>
--   unzip ps = ps <a>`seq`</a> (<a>fmap</a> <a>fst</a> ps) (<a>fmap</a> <a>snd</a> ps)
--   </pre>
--   
--   Example:
--   
--   <pre>
--   unzip $ fromList ((1,"a") :| [(2,"b"), (3,"c")]) =
--     (fromList (1:|[2,3]), fromList ("a":|["b","c"]))
--   </pre>
--   
--   See the note about efficiency at <a>unzipWith</a>.
unzip :: NESeq (a, b) -> (NESeq a, NESeq b)

-- | CPP for new functions not in old containers
--   ---------------------------------------------
--   
--   Compatibility layer for <a>sortOn</a>.
sortOnSeq :: Ord b => (a -> b) -> Seq a -> Seq a

-- | Compatibility layer for <a>unstableSortOn</a>.
unstableSortOnSeq :: Ord b => (a -> b) -> Seq a -> Seq a

-- | Compatibility layer for <a>unzip</a>.
unzipSeq :: Seq (a, b) -> (Seq a, Seq b)

-- | Compatibility layer for <a>unzipWith</a>.
unzipWithSeq :: (a -> (b, c)) -> Seq a -> (Seq b, Seq c)
instance Data.Traversable.Traversable Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Show.Show a => GHC.Show.Show (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Functor.Classes.Show1 Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Classes.Read1 Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Classes.Eq1 Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Classes.Ord1 Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Data.Data a => Data.Data.Data (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Base.Semigroup (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Base.Functor Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Bind.Class.Apply Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Base.Applicative Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Alt.Alt Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Bind.Class.Bind Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Base.Monad Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Extend.Extend Data.Sequence.NonEmpty.Internal.NESeq
instance Control.Comonad.Comonad Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Foldable.Foldable Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Semigroup.Foldable.Class.Foldable1 Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Semigroup.Traversable.Class.Traversable1 Data.Sequence.NonEmpty.Internal.NESeq
instance Control.Monad.Zip.MonadZip Data.Sequence.NonEmpty.Internal.NESeq
instance Control.Monad.Fix.MonadFix Data.Sequence.NonEmpty.Internal.NESeq
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Sequence.NonEmpty.Internal.NESeq a)


-- | <h1>Non-Empty Finite Sequences</h1>
--   
--   | An <tt><a>NESeq</a> a</tt> is a non-empty (but finite) sequence of
--   values of type <tt>a</tt>. Generally has the same interface as
--   <a>NonEmpty</a>. This is a non-empty version of <a>Seq</a> from
--   <a>Data.Sequence</a>.
--   
--   The main differences between this type and <a>NonEmpty</a> are:
--   
--   <ul>
--   <li>You cannot have infinite <a>NESeq</a>s</li>
--   <li>You have constant-time consing from either end, and constant-time
--   unconsing as well (through <a>&lt;|</a>, <a>|&gt;</a>, <a>:&lt;||</a>,
--   and <a>:||&gt;</a>)</li>
--   <li>Concatenation (<a>&gt;&lt;</a>, <a>|&gt;&lt;</a>,
--   <a>&gt;&lt;|</a>) is logarithmic-time.</li>
--   <li>You have logarithmic-time indexing and updating at a given
--   index.</li>
--   </ul>
--   
--   While asymptotics are often better than for <a>NonEmpty</a>, there is
--   a decent constant factor involved in most operations.
--   
--   See documentation for <a>NESeq</a> for information on how to convert
--   and manipulate such non-empty sequences
--   
--   This module essentially re-imports the API of
--   <a>Data.Sequence.Lazy</a> and its <a>Seq</a> type, along with
--   semantics and asymptotics.
--   
--   Because <a>NESeq</a> is implemented using <a>Seq</a>, all of the
--   caveats of using <a>Seq</a> apply.
--   
--   All functions take non-empty sequences as inputs. In situations where
--   their results can be guarunteed to also be non-empty, they also return
--   non-empty maps. In situations where their results could potentially be
--   empty, <a>Seq</a> is returned instead.
--   
--   Some functions (like <a>spanl</a>, <a>spanr</a>, <a>breakl</a>,
--   <a>breakr</a>, <a>partition</a>, <a>splitAt</a>) have modified return
--   types to account for possible configurations of non-emptiness.
--   
--   Some functions (<a>head</a>, <a>last</a>, <a>tail</a>, <a>init</a>)
--   are provided because they are total for non-empty sequences.
--   
--   This module is intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> and <a>Data.Sequence</a> functions:
--   
--   <pre>
--   import qualified Data.Sequence.NonEmpty as NESeq
--   </pre>
module Data.Sequence.NonEmpty

-- | A general-purpose non-empty (by construction) finite sequence type.
--   
--   Non-emptiness means that:
--   
--   <ul>
--   <li>Functions that <i>take</i> an <a>NESeq</a> can safely operate on
--   it with the assumption that it has at least value.</li>
--   <li>Functions that <i>return</i> an <a>NESeq</a> provide an assurance
--   that the result has at least one value.</li>
--   </ul>
--   
--   <a>Data.Sequence.NonEmpty</a> re-exports the API of
--   <a>Data.Sequence</a>, faithfully reproducing asymptotics, typeclass
--   constraints, and semantics. Functions that ensure that input and
--   output maps are both non-empty (like <a>&lt;|</a>) return
--   <a>NESeq</a>, but functions that might potentially return an empty map
--   (like <a>tail</a>) return a <a>Seq</a> instead.
--   
--   You can directly construct an <a>NESeq</a> with the API from
--   <a>Data.Sequence.NonEmpty</a>; it's more or less the same as
--   constructing a normal <a>Seq</a>, except you don't have access to
--   <a>empty</a>. There are also a few ways to construct an <a>NESeq</a>
--   from a <a>Seq</a>:
--   
--   <ol>
--   <li>The <a>nonEmptySeq</a> smart constructor will convert a
--   <tt><a>Seq</a> a</tt> into a <tt><a>Maybe</a> (<a>NESeq</a> a)</tt>,
--   returning <a>Nothing</a> if the original <a>Seq</a> was empty.</li>
--   <li>You can use <a>:&lt;||</a>, <a>:||&gt;</a>, and <a>insertSeqAt</a>
--   to insert a value into a <a>Seq</a> to create a guaranteed
--   <a>NESeq</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>Seq</a> to reveal it as either containing a
--   <a>NESeq</a> or an empty sequence.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>Seq</a> and treating it as if it were an
--   <a>NESeq</a>.</li>
--   </ol>
--   
--   You can convert an <a>NESeq</a> into a <a>Seq</a> with <a>toSeq</a> or
--   <a>IsNonEmpty</a>, essentially "obscuring" the non-empty property from
--   the type.
data NESeq a

-- | <i>O(1)</i>. An abstract constructor for an <a>NESeq</a> that consists
--   of a "head" <tt>a</tt> and a "tail" <tt><a>Seq</a> a</tt>. Similar to
--   <a>:|</a> for <a>NonEmpty</a>.
--   
--   Can be used to match on the head and tail of an <a>NESeq</a>, and also
--   used to <i>construct</i> an <a>NESeq</a> by consing an item to the
--   beginnong of a <a>Seq</a>, ensuring that the result is non-empty.
pattern (:<||) :: a -> Seq a -> NESeq a

-- | <i>O(1)</i>. An abstract constructor for an <a>NESeq</a> that consists
--   of a "init" <tt><a>Seq</a> a</tt> and a "last" <tt>a</tt>. Similar to
--   <a>:|</a> for <a>NonEmpty</a>, but at the end of the list instead of
--   at the beginning.
--   
--   Can be used to match on the init and last of an <a>NESeq</a>, and also
--   used to <i>construct</i> an <a>NESeq</a> by snocing an item to the end
--   of a <a>Seq</a>, ensuring that the result is non-empty.
pattern (:||>) :: Seq a -> a -> NESeq a
infixr 5 `NESeq`
infixr 5 :<||
infixl 5 :||>

-- | <i>O(1)</i>. The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow
--   you to treat a <a>Seq</a> as if it were either a <tt><a>IsNonEmpty</a>
--   n</tt> (where <tt>n</tt> is a <a>NESeq</a>) or an <a>IsEmpty</a>.
--   
--   For example, you can pattern match on a <a>Seq</a>:
--   
--   <pre>
--   safeHead :: <a>Seq</a> Int -&gt; Int
--   safeHead (<a>IsNonEmpty</a> (x :&lt;|| _))  = x  -- here, user provided a non-empty sequence, and <tt>n</tt> is the <a>NESeq</a>
--   safeHead <a>IsEmpty</a>                  = 0  -- here the user provided an empty sequence
--   </pre>
--   
--   Matching on <tt><a>IsNonEmpty</a> n</tt> means that the original
--   <a>Seq</a> was <i>not</i> empty, and you have a verified-non-empty
--   <a>NESeq</a> <tt>n</tt> to use.
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsNonEmpty</a> to
--   convert a <a>NESeq</a> back into a <a>Seq</a>, obscuring its
--   non-emptiness (see <a>toSeq</a>).
pattern IsNonEmpty :: NESeq a -> Seq a

-- | <i>O(1)</i>. The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow
--   you to treat a <a>Seq</a> as if it were either a <tt><a>IsNonEmpty</a>
--   n</tt> (where <tt>n</tt> is a <a>NESeq</a>) or an <a>IsEmpty</a>.
--   
--   Matching on <a>IsEmpty</a> means that the original <a>Seq</a> was
--   empty.
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsEmpty</a> as an
--   expression, and it will be interpreted as <a>empty</a>.
--   
--   See <a>IsNonEmpty</a> for more information.
pattern IsEmpty :: Seq a

-- | <i>O(1)</i>. Smart constructor for an <a>NESeq</a> from a <a>Seq</a>.
--   Returns <a>Nothing</a> if the <a>Seq</a> was originally actually
--   empty, and <tt><a>Just</a> n</tt> with an <a>NESeq</a>, if the
--   <a>Seq</a> was not empty.
--   
--   <a>nonEmptySeq</a> and <tt><a>maybe</a> <a>empty</a> <a>toSeq</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>Seq</a> being an <a>NESeq</a>.
--   
--   <pre>
--   nonEmptySeq (Data.Sequence.fromList [1,2,3]) == Just (fromList (1) :| [2,3])
--   </pre>
nonEmptySeq :: Seq a -> Maybe (NESeq a)

-- | <i>O(1)</i>. Convert a non-empty sequence back into a normal
--   possibly-empty sequence, for usage with functions that expect
--   <a>Seq</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the map in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptySeq</a> and <tt><a>maybe</a> <a>empty</a> <a>toSeq</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
toSeq :: NESeq a -> Seq a

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>Seq</a> as if it were an <a>NESeq</a>. <tt><a>withNonEmpty</a> def
--   f</tt> will take a <a>Seq</a>. If map is empty, it will evaluate to
--   <tt>def</tt>. Otherwise, a non-empty map <a>NESeq</a> will be fed to
--   the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptySeq</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NESeq a -> r) -> Seq a -> r

-- | <i>O(1)</i>. Unsafe version of <a>nonEmptySeq</a>. Coerces a
--   <a>Seq</a> into an <a>NESeq</a>, but is undefined (throws a runtime
--   exception when evaluation is attempted) for an empty <a>Seq</a>.
unsafeFromSeq :: Seq a -> NESeq a

-- | Turn a <a>Seq</a> into a guarantted non-empty <a>NESeq</a> by adding
--   an element at a given index.
--   
--   <pre>
--   insertSeqAt 1 0 (Data.Sequence.fromList [1,2,3]) == fromList (1 :| [0,2,3])
--   </pre>
insertSeqAt :: Int -> a -> Seq a -> NESeq a

-- | &lt;math&gt;. A singleton sequence.
singleton :: a -> NESeq a

-- | &lt;math&gt;. Add an element to the left end of a non-empty sequence.
--   Mnemonic: a triangle with the single element at the pointy end.
(<|) :: a -> NESeq a -> NESeq a
infixr 5 <|

-- | &lt;math&gt;. Add an element to the right end of a non-empty sequence.
--   Mnemonic: a triangle with the single element at the pointy end.
(|>) :: NESeq a -> a -> NESeq a
infixl 5 |>

-- | &lt;math&gt;. Concatenate two non-empty sequences.
(><) :: NESeq a -> NESeq a -> NESeq a
infixr 5 ><

-- | &lt;math&gt;. Concatenate a non-empty sequence with a potentially
--   empty sequence (<a>Seq</a>), to produce a guaranteed non-empty
--   sequence. Mnemonic: like <a>&gt;&lt;</a>, but a pipe for the
--   guarunteed non-empty side.
(|><) :: NESeq a -> Seq a -> NESeq a
infixr 5 |><

-- | &lt;math&gt;. Concatenate a non-empty sequence with a potentially
--   empty sequence (<a>Seq</a>), to produce a guaranteed non-empty
--   sequence. Mnemonic: like <a>&gt;&lt;</a>, but a pipe for the
--   guarunteed non-empty side.
(><|) :: Seq a -> NESeq a -> NESeq a
infixr 5 ><|

-- | &lt;math&gt;. Create a sequence from a finite list of elements. There
--   is a function <a>toNonEmpty</a> in the opposite direction for all
--   instances of the <a>Foldable1</a> class, including <a>NESeq</a>.
fromList :: NonEmpty a -> NESeq a

-- | &lt;math&gt;. Convert a given sequence length and a function
--   representing that sequence into a sequence.
fromFunction :: Int -> (Int -> a) -> NESeq a

-- | &lt;math&gt;. <tt>replicate n x</tt> is a sequence consisting of
--   <tt>n</tt> copies of <tt>x</tt>. Is only defined when <tt>n</tt> is
--   positive.
replicate :: Int -> a -> NESeq a

-- | <a>replicateA</a> is an <a>Applicative</a> version of
--   <a>replicate</a>, and makes ( O(log n) ) calls to <a>liftA2</a> and
--   <a>pure</a>. Is only defined when <tt>n</tt> is positive.
--   
--   <pre>
--   replicateA n x = sequenceA (replicate n x)
--   </pre>
--   
--   Is a more restrictive version of <a>replicateA1</a>.
--   <a>replicateA1</a> should be preferred whenever possible.
replicateA :: Applicative f => Int -> f a -> f (NESeq a)

-- | <a>replicateA</a> is an <a>Apply</a> version of <a>replicate</a>, and
--   makes ( O(log n) ) calls to <a>&lt;.&gt;</a>. Is only defined when
--   <tt>n</tt> is positive.
--   
--   <pre>
--   replicateA1 n x = sequence1 (replicate n x)
--   </pre>
replicateA1 :: Apply f => Int -> f a -> f (NESeq a)

-- | An alias of <a>replicateA</a>.
replicateM :: Applicative m => Int -> m a -> m (NESeq a)

-- | <i>O(</i>log<i> k)</i>. <tt><a>cycleTaking</a> k xs</tt> forms a
--   sequence of length <tt>k</tt> by repeatedly concatenating <tt>xs</tt>
--   with itself. Is only defined when <tt>k</tt> is positive.
--   
--   <pre>
--   cycleTaking k = fromList . fromJust . nonEmpty . take k . cycle . toList
--   </pre>
cycleTaking :: Int -> NESeq a -> NESeq a

-- | &lt;math&gt;. Constructs a sequence by repeated application of a
--   function to a seed value. Is only defined if given a positive value.
--   
--   <pre>
--   iterateN n f x = fromList (fromJust (nonEmpty ((Prelude.take n (Prelude.iterate f x)))))
--   </pre>
iterateN :: Int -> (a -> a) -> a -> NESeq a

-- | Builds a sequence from a seed value. Takes time linear in the number
--   of generated elements. <i>WARNING:</i> If the number of generated
--   elements is infinite, this method will not terminate.
unfoldr :: (b -> (a, Maybe b)) -> b -> NESeq a

-- | <tt><a>unfoldl</a> f x</tt> is equivalent to <tt><a>reverse</a>
--   (<a>unfoldr</a> (<a>fmap</a> swap . f) x)</tt>.
unfoldl :: (b -> (Maybe b, a)) -> b -> NESeq a

-- | <i>O(1)</i>. Retrieve the left-most item in a non-empty sequence. Note
--   that this function is total.
head :: NESeq a -> a

-- | <i>O(1)</i>. Delete the left-most item in a non-empty sequence.
--   Returns a potentially empty sequence (<a>Seq</a>) in the case that the
--   original <a>NESeq</a> contained only a single element. Note that this
--   function is total.
tail :: NESeq a -> Seq a

-- | <i>O(1)</i>. Retrieve the right-most item in a non-empty sequence.
--   Note that this function is total.
last :: NESeq a -> a

-- | <i>O(1)</i>. Delete the right-most item in a non-empty sequence.
--   Returns a potentially empty sequence (<a>Seq</a>) in the case that the
--   original <a>NESeq</a> contained only a single element. Note that this
--   function is total.
init :: NESeq a -> Seq a

-- | &lt;math&gt;. The number of elements in the sequence.
length :: NESeq a -> Int

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a sequence of
--   reduced values from the left:
--   
--   <pre>
--   scanl f z (fromList [x1, x2, ...]) = fromList [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
scanl :: (a -> b -> a) -> a -> NESeq b -> NESeq a

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument:
--   
--   <pre>
--   scanl1 f (fromList [x1, x2, ...]) = fromList [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: (a -> a -> a) -> NESeq a -> NESeq a

-- | <a>scanr</a> is the right-to-left dual of <a>scanl</a>.
scanr :: (a -> b -> b) -> b -> NESeq a -> NESeq b

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: (a -> a -> a) -> NESeq a -> NESeq a

-- | &lt;math&gt;. Returns a sequence of all non-empty suffixes of this
--   sequence, longest first. For example,
--   
--   <pre>
--   tails (fromList (1:|[2,3])) = fromList (fromList (1:|[2,3]) :| [fromList (2:|[3]), fromList (3:|[])])
--   </pre>
--   
--   Evaluating the &lt;math&gt;th suffix takes &lt;math&gt;, but
--   evaluating every suffix in the sequence takes &lt;math&gt; due to
--   sharing.
tails :: NESeq a -> NESeq (NESeq a)

-- | &lt;math&gt;. Returns a sequence of all non-empty prefixes of this
--   sequence, shortest first. For example,
--   
--   <pre>
--   tails (fromList (1:|[2,3])) = fromList (fromList (1:|[]) :| [fromList (1:|[2]), fromList (1:|[2,3]))
--   </pre>
--   
--   Evaluating the &lt;math&gt;th prefix takes &lt;math&gt;, but
--   evaluating every prefix in the sequence takes &lt;math&gt; due to
--   sharing.
inits :: NESeq a -> NESeq (NESeq a)

-- | &lt;math&gt;. <tt>chunksOf c xs</tt> splits <tt>xs</tt> into chunks of
--   size <tt>c&gt;0</tt>. If <tt>c</tt> does not divide the length of
--   <tt>xs</tt> evenly, then the last element of the result will be short.
--   Is only defined if <tt>c</tt> is a positive number.
--   
--   Side note: the given performance bound is missing some messy terms
--   that only really affect edge cases. Performance degrades smoothly from
--   &lt;math&gt; (for &lt;math&gt;) to &lt;math&gt; (for &lt;math&gt;).
--   The true bound is more like &lt;math&gt;
chunksOf :: Int -> NESeq a -> NESeq (NESeq a)

-- | &lt;math&gt; where &lt;math&gt; is the prefix length.
--   <a>takeWhileL</a>, applied to a predicate <tt>p</tt> and a sequence
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
--   
--   Returns a possibly empty sequence (<a>Seq</a>) in the case that the
--   predicate fails on the first item.
takeWhileL :: (a -> Bool) -> NESeq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the suffix length.
--   <a>takeWhileR</a>, applied to a predicate <tt>p</tt> and a sequence
--   <tt>xs</tt>, returns the longest suffix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
--   
--   Returns a possibly empty sequence (<a>Seq</a>) in the case that the
--   predicate fails on the first item.
--   
--   <tt><a>takeWhileR</a> p xs</tt> is equivalent to <tt><a>reverse</a>
--   (<a>takeWhileL</a> p (<a>reverse</a> xs))</tt>.
takeWhileR :: (a -> Bool) -> NESeq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the prefix length.
--   <tt><a>dropWhileL</a> p xs</tt> returns the suffix remaining after
--   <tt><a>takeWhileL</a> p xs</tt>.
--   
--   Returns a possibly empty sequence (<a>Seq</a>) in the case that the
--   predicate passes for all items.
dropWhileL :: (a -> Bool) -> NESeq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the suffix length.
--   <tt><a>dropWhileR</a> p xs</tt> returns the prefix remaining after
--   <tt><a>takeWhileR</a> p xs</tt>.
--   
--   Returns a possibly empty sequence (<a>Seq</a>) in the case that the
--   predicate passes for all items.
--   
--   <tt><a>dropWhileR</a> p xs</tt> is equivalent to <tt><a>reverse</a>
--   (<a>dropWhileL</a> p (<a>reverse</a> xs))</tt>.
dropWhileR :: (a -> Bool) -> NESeq a -> Seq a

-- | &lt;math&gt; where &lt;math&gt; is the prefix length. <a>spanl</a>,
--   applied to a predicate <tt>p</tt> and a sequence <tt>xs</tt>, returns
--   a <a>These</a> based on the point where the predicate fails:
--   
--   <ul>
--   <li><tt><a>This</a> ys</tt> means that the predicate was true for all
--   items, and <tt>ys</tt> is the entire original sequence.</li>
--   <li><tt><a>That</a> zs</tt> means that the predicate failed on the
--   first item, and <tt>zs</tt> is the entire original sequence.</li>
--   <li><tt><a>These</a> ys zs</tt> gives <tt>ys</tt> (the prefix of
--   elements that satisfy the predicae) and <tt>zs</tt> (the remainder of
--   the sequence)</li>
--   </ul>
spanl :: (a -> Bool) -> NESeq a -> These (NESeq a) (NESeq a)

-- | &lt;math&gt; where &lt;math&gt; is the suffix length. <a>spanr</a>,
--   applied to a predicate <tt>p</tt> and a sequence <tt>xs</tt>, returns
--   a <a>These</a> based on the point where the predicate fails:
--   
--   <ul>
--   <li><tt><a>This</a> ys</tt> means that the predicate was true for all
--   items, and <tt>ys</tt> is the entire original sequence.</li>
--   <li><tt><a>That</a> zs</tt> means that the predicate failed on the
--   first item, and <tt>zs</tt> is the entire original sequence.</li>
--   <li><tt><a>These</a> ys zs</tt> gives <tt>ys</tt> (the suffix of
--   elements that satisfy the predicae) and <tt>zs</tt> (the remainder of
--   the sequence, before the suffix)</li>
--   </ul>
spanr :: (a -> Bool) -> NESeq a -> These (NESeq a) (NESeq a)

-- | &lt;math&gt; where &lt;math&gt; is the breakpoint index.
--   
--   <tt><a>breakl</a> p</tt> is <tt><a>spanl</a> (not . p)</tt>.
breakl :: (a -> Bool) -> NESeq a -> These (NESeq a) (NESeq a)

-- | &lt;math&gt; where &lt;math&gt; is the breakpoint index.
--   
--   <tt><a>breakr</a> p</tt> is <tt><a>spanr</a> (not . p)</tt>.
breakr :: (a -> Bool) -> NESeq a -> These (NESeq a) (NESeq a)

-- | &lt;math&gt;. The <a>partition</a> function takes a predicate
--   <tt>p</tt> and a sequence <tt>xs</tt> and returns sequences of those
--   elements which do and do not satisfy the predicate, as a <a>These</a>:
--   
--   <ul>
--   <li><tt><a>This</a> ys</tt> means that the predicate was true for all
--   items, and <tt>ys</tt> is the entire original sequence.</li>
--   <li><tt><a>That</a> zs</tt> means that the predicate failed on the
--   first item, and <tt>zs</tt> is the entire original sequence.</li>
--   <li><tt><a>These</a> ys zs</tt> gives <tt>ys</tt> (the sequence of
--   elements for which the predicate was true) and <tt>zs</tt> (the
--   sequence of elements for which the predicate was false).</li>
--   </ul>
partition :: (a -> Bool) -> NESeq a -> These (NESeq a) (NESeq a)

-- | &lt;math&gt;. The <a>filter</a> function takes a predicate <tt>p</tt>
--   and a sequence <tt>xs</tt> and returns a sequence of those elements
--   which satisfy the predicate.
--   
--   Returns a potentially empty sequence (<a>Seq</a>) in the case that the
--   predicate fails for all items in the sequence.
filter :: (a -> Bool) -> NESeq a -> Seq a

-- | &lt;math&gt;. <a>sort</a> sorts the specified <a>NESeq</a> by the
--   natural ordering of its elements. The sort is stable. If stability is
--   not required, <a>unstableSort</a> can be slightly faster.
sort :: Ord a => NESeq a -> NESeq a

-- | &lt;math&gt;. <a>sortBy</a> sorts the specified <a>NESeq</a> according
--   to the specified comparator. The sort is stable. If stability is not
--   required, <a>unstableSortBy</a> can be slightly faster.
sortBy :: (a -> a -> Ordering) -> NESeq a -> NESeq a

-- | &lt;math&gt;. <a>sortOn</a> sorts the specified <a>NESeq</a> by
--   comparing the results of a key function applied to each element.
--   <tt><a>sortOn</a> f</tt> is equivalent to <tt><a>sortBy</a>
--   (<a>compare</a> <a>`on`</a> f)</tt>, but has the performance advantage
--   of only evaluating <tt>f</tt> once for each element in the input list.
--   This is called the decorate-sort-undecorate paradigm, or Schwartzian
--   transform.
--   
--   An example of using <a>sortOn</a> might be to sort a <a>NESeq</a> of
--   strings according to their length:
--   
--   <pre>
--   sortOn length (fromList ("alligator" :| ["monkey", "zebra"])) == fromList ("zebra" :| ["monkey", "alligator"])
--   </pre>
--   
--   If, instead, <a>sortBy</a> had been used, <a>length</a> would be
--   evaluated on every comparison, giving &lt;math&gt; evaluations, rather
--   than &lt;math&gt;.
--   
--   If <tt>f</tt> is very cheap (for example a record selector, or
--   <a>fst</a>), <tt><a>sortBy</a> (<a>compare</a> <a>`on`</a> f)</tt>
--   will be faster than <tt><a>sortOn</a> f</tt>.
sortOn :: Ord b => (a -> b) -> NESeq a -> NESeq a

-- | &lt;math&gt;. <a>unstableSort</a> sorts the specified <a>NESeq</a> by
--   the natural ordering of its elements, but the sort is not stable. This
--   algorithm is frequently faster and uses less memory than <a>sort</a>.
unstableSort :: Ord a => NESeq a -> NESeq a

-- | &lt;math&gt;. A generalization of <a>unstableSort</a>,
--   <a>unstableSortBy</a> takes an arbitrary comparator and sorts the
--   specified sequence. The sort is not stable. This algorithm is
--   frequently faster and uses less memory than <a>sortBy</a>.
unstableSortBy :: (a -> a -> Ordering) -> NESeq a -> NESeq a

-- | &lt;math&gt;. <a>unstableSortOn</a> sorts the specified <a>NESeq</a>
--   by comparing the results of a key function applied to each element.
--   <tt><a>unstableSortOn</a> f</tt> is equivalent to
--   <tt><a>unstableSortBy</a> (<a>compare</a> <a>`on`</a> f)</tt>, but has
--   the performance advantage of only evaluating <tt>f</tt> once for each
--   element in the input list. This is called the decorate-sort-undecorate
--   paradigm, or Schwartzian transform.
--   
--   An example of using <a>unstableSortOn</a> might be to sort a
--   <a>NESeq</a> of strings according to their length.
--   
--   <pre>
--   unstableSortOn length (fromList ("alligator" :| ["monkey", "zebra"])) == fromList ("zebra" :| ["monkey", "alligator]")
--   </pre>
--   
--   If, instead, <a>unstableSortBy</a> had been used, <a>length</a> would
--   be evaluated on every comparison, giving &lt;math&gt; evaluations,
--   rather than &lt;math&gt;.
--   
--   If <tt>f</tt> is very cheap (for example a record selector, or
--   <a>fst</a>), <tt><a>unstableSortBy</a> (<a>compare</a> <a>`on`</a>
--   f)</tt> will be faster than <tt><a>unstableSortOn</a> f</tt>.
unstableSortOn :: Ord b => (a -> b) -> NESeq a -> NESeq a

-- | &lt;math&gt;. The element at the specified position, counting from 0.
--   If the specified position is negative or at least the length of the
--   sequence, <a>lookup</a> returns <a>Nothing</a>.
--   
--   Unlike <a>index</a>, this can be used to retrieve an element without
--   forcing it.
lookup :: Int -> NESeq a -> Maybe a

-- | &lt;math&gt;. A flipped, infix version of <a>lookup</a>.
(!?) :: NESeq a -> Int -> Maybe a

-- | &lt;math&gt;. The element at the specified position, counting from 0.
--   The argument should thus be a non-negative integer less than the size
--   of the sequence. If the position is out of range, <a>index</a> fails
--   with an error.
--   
--   <pre>
--   xs `index` i = toList xs !! i
--   </pre>
--   
--   Caution: <a>index</a> necessarily delays retrieving the requested
--   element until the result is forced. It can therefore lead to a space
--   leak if the result is stored, unforced, in another structure. To
--   retrieve an element immediately without forcing it, use <a>lookup</a>
--   or <tt>(!?)</tt>.
index :: NESeq a -> Int -> a

-- | &lt;math&gt;. Update the element at the specified position. If the
--   position is out of range, the original sequence is returned.
--   <a>adjust</a> can lead to poor performance and even memory leaks,
--   because it does not force the new value before installing it in the
--   sequence. <a>adjust'</a> should usually be preferred.
adjust :: (a -> a) -> Int -> NESeq a -> NESeq a

-- | &lt;math&gt;. Update the element at the specified position. If the
--   position is out of range, the original sequence is returned. The new
--   value is forced before it is installed in the sequence.
--   
--   <pre>
--   adjust' f i xs =
--    case xs !? i of
--      Nothing -&gt; xs
--      Just x -&gt; let !x' = f x
--                in update i x' xs
--   </pre>
adjust' :: (a -> a) -> Int -> NESeq a -> NESeq a

-- | &lt;math&gt;. Replace the element at the specified position. If the
--   position is out of range, the original sequence is returned.
update :: Int -> a -> NESeq a -> NESeq a

-- | &lt;math&gt;. The first <tt>i</tt> elements of a sequence. If
--   <tt>i</tt> is negative, <tt><a>take</a> i s</tt> yields the empty
--   sequence. If the sequence contains fewer than <tt>i</tt> elements, the
--   whole sequence is returned.
take :: Int -> NESeq a -> Seq a

-- | &lt;math&gt;. Elements of a sequence after the first <tt>i</tt>. If
--   <tt>i</tt> is negative, <tt><a>drop</a> i s</tt> yields the whole
--   sequence. If the sequence contains fewer than <tt>i</tt> elements, the
--   empty sequence is returned.
drop :: Int -> NESeq a -> Seq a

-- | &lt;math&gt;. <tt><a>insertAt</a> i x xs</tt> inserts <tt>x</tt> into
--   <tt>xs</tt> at the index <tt>i</tt>, shifting the rest of the sequence
--   over.
--   
--   <pre>
--   insertAt 2 x (fromList (a:|[b,c,d])) = fromList (a:|[b,x,c,d])
--   insertAt 4 x (fromList (a:|[b,c,d])) = insertAt 10 x (fromList (a:|[b,c,d]))
--                                        = fromList (a:|[b,c,d,x])
--   </pre>
--   
--   <pre>
--   insertAt i x xs = take i xs &gt;&lt; singleton x &gt;&lt; drop i xs
--   </pre>
insertAt :: Int -> a -> NESeq a -> NESeq a

-- | &lt;math&gt;. Delete the element of a sequence at a given index.
--   Return the original sequence if the index is out of range.
--   
--   <pre>
--   deleteAt 2 (a:|[b,c,d]) = a:|[b,d]
--   deleteAt 4 (a:|[b,c,d]) = deleteAt (-1) (a:|[b,c,d]) = a:|[b,c,d]
--   </pre>
deleteAt :: Int -> NESeq a -> Seq a

-- | &lt;math&gt;. Split a sequence at a given position.
--   
--   <ul>
--   <li><tt><a>This</a> ys</tt> means that the given position was longer
--   than the length of the list, and <tt>ys</tt> is the entire original
--   system.</li>
--   <li><tt><a>That</a> zs</tt> means that the given position was zero or
--   smaller, and so <tt>zs</tt> is the entire original sequence.</li>
--   <li><tt><a>These</a> ys zs</tt> gives <tt>ys</tt> (the sequence of
--   elements before the given position, <tt>take n xs</tt>) and
--   <tt>zs</tt> (the sequence of elements after the given position,
--   <tt>drop n xs</tt>).</li>
--   </ul>
splitAt :: Int -> NESeq a -> These (NESeq a) (NESeq a)

-- | <a>elemIndexL</a> finds the leftmost index of the specified element,
--   if it is present, and otherwise <a>Nothing</a>.
elemIndexL :: Eq a => a -> NESeq a -> Maybe Int

-- | <a>elemIndicesL</a> finds the indices of the specified element, from
--   left to right (i.e. in ascending order).
elemIndicesL :: Eq a => a -> NESeq a -> [Int]

-- | <a>elemIndexR</a> finds the rightmost index of the specified element,
--   if it is present, and otherwise <a>Nothing</a>.
elemIndexR :: Eq a => a -> NESeq a -> Maybe Int

-- | <a>elemIndicesR</a> finds the indices of the specified element, from
--   right to left (i.e. in descending order).
elemIndicesR :: Eq a => a -> NESeq a -> [Int]

-- | <tt><a>findIndexL</a> p xs</tt> finds the index of the leftmost
--   element that satisfies <tt>p</tt>, if any exist.
findIndexL :: (a -> Bool) -> NESeq a -> Maybe Int

-- | <tt><a>findIndicesL</a> p</tt> finds all indices of elements that
--   satisfy <tt>p</tt>, in ascending order.
findIndicesL :: (a -> Bool) -> NESeq a -> [Int]

-- | <tt><a>findIndexR</a> p xs</tt> finds the index of the rightmost
--   element that satisfies <tt>p</tt>, if any exist.
findIndexR :: (a -> Bool) -> NESeq a -> Maybe Int

-- | <tt><a>findIndicesR</a> p</tt> finds all indices of elements that
--   satisfy <tt>p</tt>, in descending order.
findIndicesR :: (a -> Bool) -> NESeq a -> [Int]

-- | <i>O(n)</i>. A generalization of <a>foldMap1</a>,
--   <a>foldMapWithIndex</a> takes a folding function that also depends on
--   the element's index, and applies it to every element in the sequence.
foldMapWithIndex :: Semigroup m => (Int -> a -> m) -> NESeq a -> m

-- | <a>foldlWithIndex</a> is a version of <a>foldl</a> that also provides
--   access to the index of each element.
foldlWithIndex :: (b -> Int -> a -> b) -> b -> NESeq a -> b

-- | <a>foldrWithIndex</a> is a version of <a>foldr</a> that also provides
--   access to the index of each element.
foldrWithIndex :: (Int -> a -> b -> b) -> b -> NESeq a -> b

-- | A generalization of <a>fmap</a>, <a>mapWithIndex</a> takes a mapping
--   function that also depends on the element's index, and applies it to
--   every element in the sequence.
mapWithIndex :: (Int -> a -> b) -> NESeq a -> NESeq b

-- | <a>traverseWithIndex</a> is a version of <a>traverse</a> that also
--   offers access to the index of each element.
--   
--   Is a more restrictive version of <a>traverseWithIndex1</a>;
--   <a>traverseWithIndex1</a> should be used whenever possible.
traverseWithIndex :: Applicative f => (Int -> a -> f b) -> NESeq a -> f (NESeq b)

-- | <i>O(n)</i>. <a>traverseWithIndex1</a> is a version of
--   <a>traverse1</a> that also offers access to the index of each element.
traverseWithIndex1 :: Apply f => (Int -> a -> f b) -> NESeq a -> f (NESeq b)

-- | &lt;math&gt;. The reverse of a sequence.
reverse :: NESeq a -> NESeq a

-- | &lt;math&gt;. Intersperse an element between the elements of a
--   sequence.
--   
--   <pre>
--   intersperse a empty = empty
--   intersperse a (singleton x) = singleton x
--   intersperse a (fromList [x,y]) = fromList [x,a,y]
--   intersperse a (fromList [x,y,z]) = fromList [x,a,y,a,z]
--   </pre>
intersperse :: a -> NESeq a -> NESeq a

-- | &lt;math&gt;. <a>zip</a> takes two sequences and returns a sequence of
--   corresponding pairs. If one input is short, excess elements are
--   discarded from the right end of the longer sequence.
zip :: NESeq a -> NESeq b -> NESeq (a, b)

-- | &lt;math&gt;. <a>zipWith</a> generalizes <a>zip</a> by zipping with
--   the function given as the first argument, instead of a tupling
--   function. For example, <tt>zipWith (+)</tt> is applied to two
--   sequences to take the sequence of corresponding sums.
zipWith :: (a -> b -> c) -> NESeq a -> NESeq b -> NESeq c

-- | &lt;math&gt;. <a>zip3</a> takes three sequences and returns a sequence
--   of triples, analogous to <a>zip</a>.
zip3 :: NESeq a -> NESeq b -> NESeq c -> NESeq (a, b, c)

-- | &lt;math&gt;. <a>zipWith3</a> takes a function which combines three
--   elements, as well as three sequences and returns a sequence of their
--   point-wise combinations, analogous to <a>zipWith</a>.
zipWith3 :: (a -> b -> c -> d) -> NESeq a -> NESeq b -> NESeq c -> NESeq d

-- | &lt;math&gt;. <a>zip4</a> takes four sequences and returns a sequence
--   of quadruples, analogous to <a>zip</a>.
zip4 :: NESeq a -> NESeq b -> NESeq c -> NESeq d -> NESeq (a, b, c, d)

-- | &lt;math&gt;. <a>zipWith4</a> takes a function which combines four
--   elements, as well as four sequences and returns a sequence of their
--   point-wise combinations, analogous to <a>zipWith</a>.
zipWith4 :: (a -> b -> c -> d -> e) -> NESeq a -> NESeq b -> NESeq c -> NESeq d -> NESeq e

-- | Unzip a sequence of pairs.
--   
--   <pre>
--   unzip ps = ps <a>`seq`</a> (<a>fmap</a> <a>fst</a> ps) (<a>fmap</a> <a>snd</a> ps)
--   </pre>
--   
--   Example:
--   
--   <pre>
--   unzip $ fromList ((1,"a") :| [(2,"b"), (3,"c")]) =
--     (fromList (1:|[2,3]), fromList ("a":|["b","c"]))
--   </pre>
--   
--   See the note about efficiency at <a>unzipWith</a>.
unzip :: NESeq (a, b) -> (NESeq a, NESeq b)

-- | &lt;math&gt;. Unzip a sequence using a function to divide elements.
--   
--   <pre>
--   unzipWith f xs == <a>unzip</a> (<a>fmap</a> f xs)
--   </pre>
--   
--   Efficiency note:
--   
--   <tt>unzipWith</tt> produces its two results in lockstep. If you
--   calculate <tt> unzipWith f xs </tt> and fully force <i>either</i> of
--   the results, then the entire structure of the <i>other</i> one will be
--   built as well. This behavior allows the garbage collector to collect
--   each calculated pair component as soon as it dies, without having to
--   wait for its mate to die. If you do not need this behavior, you may be
--   better off simply calculating the sequence of pairs and using
--   <a>fmap</a> to extract each component sequence.
unzipWith :: (a -> (b, c)) -> NESeq a -> (NESeq b, NESeq c)


-- | Unsafe internal-use functions used in the implementation of
--   <a>Data.Set.NonEmpty</a>. These functions can potentially be used to
--   break the abstraction of <a>NESet</a> and produce unsound sets, so be
--   wary!
module Data.Set.NonEmpty.Internal

-- | A non-empty (by construction) set of values <tt>a</tt>. At least one
--   value exists in an <tt><a>NESet</a> a</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NESet</a> can safely operate on it
--   with the assumption that it has at least one item.
--   
--   Functions that <i>return</i> an <a>NESet</a> provide an assurance that
--   the result has at least one item.
--   
--   <a>Data.Set.NonEmpty</a> re-exports the API of <a>Data.Set</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output sets are both
--   non-empty (like <a>insert</a>) return <a>NESet</a>, but functions that
--   might potentially return an empty map (like <a>delete</a>) return a
--   <a>Set</a> instead.
--   
--   You can directly construct an <a>NESet</a> with the API from
--   <a>Data.Set.NonEmpty</a>; it's more or less the same as constructing a
--   normal <a>Set</a>, except you don't have access to <a>empty</a>. There
--   are also a few ways to construct an <a>NESet</a> from a <a>Set</a>:
--   
--   <ol>
--   <li>The <a>nonEmptySet</a> smart constructor will convert a
--   <tt><a>Set</a> a</tt> into a <tt><a>Maybe</a> (<a>NESet</a> a)</tt>,
--   returning <a>Nothing</a> if the original <a>Set</a> was empty.</li>
--   <li>You can use the <a>insertSet</a> family of functions to insert a
--   value into a <a>Set</a> to create a guaranteed <a>NESet</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>Set</a> to reveal it as either containing a
--   <a>NESet</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>Set</a> and treating it as if it were an
--   <a>NESet</a>.</li>
--   </ol>
--   
--   You can convert an <a>NESet</a> into a <a>Set</a> with <a>toSet</a> or
--   <a>IsNonEmpty</a>, essentially "obscuring" the non-empty property from
--   the type.
data NESet a
NESet :: !a -> !Set a -> NESet a

-- | invariant: must be smaller than smallest value in set
[nesV0] :: NESet a -> !a
[nesSet] :: NESet a -> !Set a

-- | <i>O(log n)</i>. Smart constructor for an <a>NESet</a> from a
--   <a>Set</a>. Returns <a>Nothing</a> if the <a>Set</a> was originally
--   actually empty, and <tt><a>Just</a> n</tt> with an <a>NESet</a>, if
--   the <a>Set</a> was not empty.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>Set</a> being an <a>NESet</a>.
--   
--   <pre>
--   nonEmptySet (Data.Set.fromList [3,5]) == Just (fromList (3:|[5]))
--   </pre>
nonEmptySet :: Set a -> Maybe (NESet a)

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>Set</a> as if it were an <a>NESet</a>. <tt><a>withNonEmpty</a> def
--   f</tt> will take a <a>Set</a>. If set is empty, it will evaluate to
--   <tt>def</tt>. Otherwise, a non-empty set <a>NESet</a> will be fed to
--   the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptySet</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NESet a -> r) -> Set a -> r

-- | <i>O(log n)</i>. Convert a non-empty set back into a normal
--   possibly-empty map, for usage with functions that expect <a>Set</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the set in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toSet (fromList ((3,"a") :| [(5,"b")])) == Data.Set.fromList [(3,"a"), (5,"b")]
--   </pre>
toSet :: NESet a -> Set a

-- | <i>O(1)</i>. Create a singleton set.
singleton :: a -> NESet a

-- | <i>O(n*log n)</i>. Create a set from a list of elements.
fromList :: Ord a => NonEmpty a -> NESet a

-- | <i>O(n)</i>. Convert the set to a non-empty list of elements.
toList :: NESet a -> NonEmpty a

-- | <i>O(1)</i>. The number of elements in the set. Guaranteed to be
--   greater than zero.
size :: NESet a -> Int

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The union of two sets, preferring
--   the first set when equal elements are encountered.
union :: Ord a => NESet a -> NESet a -> NESet a

-- | The union of a non-empty list of sets
unions :: (Foldable1 f, Ord a) => f (NESet a) -> NESet a

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   elemsList set = foldr (:) [] set
--   </pre>
foldr :: (a -> b -> b) -> b -> NESet a -> b

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   descElemsList set = foldl (flip (:)) [] set
--   </pre>
foldl :: (a -> b -> a) -> a -> NESet b -> a

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> NESet a -> b

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> NESet b -> a

-- | Used for <a>cartesianProduct</a>
newtype MergeNESet a
MergeNESet :: NESet a -> MergeNESet a
[getMergeNESet] :: MergeNESet a -> NESet a

-- | Unsafely merge two disjoint sets. Only legal if all items in the first
--   set are less than all items in the second set
merge :: NESet a -> NESet a -> NESet a

-- | <i>O(n)</i>. Test if the internal set structure is valid.
valid :: Ord a => NESet a -> Bool

-- | <i>O(log n)</i>. Insert new value into a set where values are
--   <i>strictly greater than</i> the new values That is, the new value
--   must be <i>strictly less than</i> all values present in the
--   <a>Set</a>. /The precondition is not checked./
--   
--   While this has the same asymptotics as <tt>Data.Set.insert</tt>, it
--   saves a constant factor for value comparison (so may be helpful if
--   comparison is expensive) and also does not require an <a>Ord</a>
--   instance for the value type.
insertMinSet :: a -> Set a -> Set a

-- | <i>O(log n)</i>. Insert new value into a set where values are
--   /strictly less than<i> the new value. That is, the new value must be
--   </i>strictly greater than<i> all values present in the <a>Set</a>.
--   </i>The precondition is not checked./
--   
--   While this has the same asymptotics as <tt>Data.Set.insert</tt>, it
--   saves a constant factor for value comparison (so may be helpful if
--   comparison is expensive) and also does not require an <a>Ord</a>
--   instance for the value type.
insertMaxSet :: a -> Set a -> Set a

-- | CPP for new functions not in old containers
--   ---------------------------------------------
--   
--   Comptability layer for <a>disjoint</a>.
disjointSet :: Ord a => Set a -> Set a -> Bool

-- | Comptability layer for <a>powerSet</a>.
powerSetSet :: Set a -> Set (Set a)

-- | Comptability layer for <a>disjointUnion</a>.
disjointUnionSet :: Set a -> Set b -> Set (Either a b)

-- | Comptability layer for <a>cartesianProduct</a>.
cartesianProductSet :: Set a -> Set b -> Set (a, b)
instance GHC.Base.Semigroup (Data.Set.NonEmpty.Internal.MergeNESet a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Set.NonEmpty.Internal.NESet a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Set.NonEmpty.Internal.NESet a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Set.NonEmpty.Internal.NESet a)
instance (GHC.Read.Read a, GHC.Classes.Ord a) => GHC.Read.Read (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Functor.Classes.Eq1 Data.Set.NonEmpty.Internal.NESet
instance Data.Functor.Classes.Ord1 Data.Set.NonEmpty.Internal.NESet
instance Data.Functor.Classes.Show1 Data.Set.NonEmpty.Internal.NESet
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Set.NonEmpty.Internal.NESet a)
instance (Data.Data.Data a, GHC.Classes.Ord a) => Data.Data.Data (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Data.Set.NonEmpty.Internal.NESet a)
instance (Data.Aeson.Types.FromJSON.FromJSON a, GHC.Classes.Ord a) => Data.Aeson.Types.FromJSON.FromJSON (Data.Set.NonEmpty.Internal.NESet a)
instance GHC.Classes.Ord a => GHC.Base.Semigroup (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Foldable.Foldable Data.Set.NonEmpty.Internal.NESet
instance Data.Semigroup.Foldable.Class.Foldable1 Data.Set.NonEmpty.Internal.NESet


-- | <h1>Non-Empty Finite Sets</h1>
--   
--   The <tt><a>NESet</a> e</tt> type represents a non-empty set of
--   elements of type <tt>e</tt>. Most operations require that <tt>e</tt>
--   be an instance of the <a>Ord</a> class. A <a>NESet</a> is strict in
--   its elements.
--   
--   See documentation for <a>NESet</a> for information on how to convert
--   and manipulate such non-empty set.
--   
--   This module essentially re-imports the API of <a>Data.Set</a> and its
--   <a>Set</a> type, along with semantics and asymptotics. In most
--   situations, asymptotics are different only by a constant factor. In
--   some situations, asmyptotics are even better (constant-time instead of
--   log-time). All typeclass constraints are identical to their
--   <a>Data.Set</a> counterparts.
--   
--   Because <a>NESet</a> is implemented using <a>Set</a>, all of the
--   caveats of using <a>Set</a> apply (such as the limitation of the
--   maximum size of sets).
--   
--   All functions take non-empty sets as inputs. In situations where their
--   results can be guarunteed to also be non-empty, they also return
--   non-empty sets. In situations where their results could potentially be
--   empty, <a>Set</a> is returned instead.
--   
--   Some functions (<a>partition</a>, <a>spanAntitone</a>, <a>split</a>)
--   have modified return types to account for possible configurations of
--   non-emptiness.
--   
--   This module is intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> and <a>Data.Set</a> functions:
--   
--   <pre>
--   import qualified Data.Set.NonEmpty as NES
--   </pre>
module Data.Set.NonEmpty

-- | A non-empty (by construction) set of values <tt>a</tt>. At least one
--   value exists in an <tt><a>NESet</a> a</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NESet</a> can safely operate on it
--   with the assumption that it has at least one item.
--   
--   Functions that <i>return</i> an <a>NESet</a> provide an assurance that
--   the result has at least one item.
--   
--   <a>Data.Set.NonEmpty</a> re-exports the API of <a>Data.Set</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output sets are both
--   non-empty (like <a>insert</a>) return <a>NESet</a>, but functions that
--   might potentially return an empty map (like <a>delete</a>) return a
--   <a>Set</a> instead.
--   
--   You can directly construct an <a>NESet</a> with the API from
--   <a>Data.Set.NonEmpty</a>; it's more or less the same as constructing a
--   normal <a>Set</a>, except you don't have access to <a>empty</a>. There
--   are also a few ways to construct an <a>NESet</a> from a <a>Set</a>:
--   
--   <ol>
--   <li>The <a>nonEmptySet</a> smart constructor will convert a
--   <tt><a>Set</a> a</tt> into a <tt><a>Maybe</a> (<a>NESet</a> a)</tt>,
--   returning <a>Nothing</a> if the original <a>Set</a> was empty.</li>
--   <li>You can use the <a>insertSet</a> family of functions to insert a
--   value into a <a>Set</a> to create a guaranteed <a>NESet</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>Set</a> to reveal it as either containing a
--   <a>NESet</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>Set</a> and treating it as if it were an
--   <a>NESet</a>.</li>
--   </ol>
--   
--   You can convert an <a>NESet</a> into a <a>Set</a> with <a>toSet</a> or
--   <a>IsNonEmpty</a>, essentially "obscuring" the non-empty property from
--   the type.
data NESet a

-- | <i>O(1)</i> match, <i>O(log n)</i> usage of contents. The
--   <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow you to treat a
--   <a>Set</a> as if it were either a <tt><a>IsNonEmpty</a> n</tt> (where
--   <tt>n</tt> is a <a>NESet</a>) or an <a>IsEmpty</a>.
--   
--   For example, you can pattern match on a <a>Set</a>:
--   
--   <pre>
--   myFunc :: <a>Set</a> X -&gt; Y
--   myFunc (<a>IsNonEmpty</a> n) =  -- here, the user provided a non-empty set, and <tt>n</tt> is the <a>NESet</a>
--   myFunc <a>IsEmpty</a>        =  -- here, the user provided an empty set
--   </pre>
--   
--   Matching on <tt><a>IsNonEmpty</a> n</tt> means that the original
--   <a>Set</a> was <i>not</i> empty, and you have a verified-non-empty
--   <a>NESet</a> <tt>n</tt> to use.
--   
--   Note that patching on this pattern is <i>O(1)</i>. However, using the
--   contents requires a <i>O(log n)</i> cost that is deferred until after
--   the pattern is matched on (and is not incurred at all if the contents
--   are never used).
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsNonEmpty</a> to
--   convert a <a>NESet</a> back into a <a>Set</a>, obscuring its
--   non-emptiness (see <a>toSet</a>).
pattern IsNonEmpty :: NESet a -> Set a

-- | <i>O(1)</i>. The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow
--   you to treat a <a>Set</a> as if it were either a <tt><a>IsNonEmpty</a>
--   n</tt> (where <tt>n</tt> is a <a>NESet</a>) or an <a>IsEmpty</a>.
--   
--   Matching on <a>IsEmpty</a> means that the original <a>Set</a> was
--   empty.
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsEmpty</a> as an
--   expression, and it will be interpreted as <a>empty</a>.
--   
--   See <a>IsNonEmpty</a> for more information.
pattern IsEmpty :: Set a

-- | <i>O(log n)</i>. Smart constructor for an <a>NESet</a> from a
--   <a>Set</a>. Returns <a>Nothing</a> if the <a>Set</a> was originally
--   actually empty, and <tt><a>Just</a> n</tt> with an <a>NESet</a>, if
--   the <a>Set</a> was not empty.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>Set</a> being an <a>NESet</a>.
--   
--   <pre>
--   nonEmptySet (Data.Set.fromList [3,5]) == Just (fromList (3:|[5]))
--   </pre>
nonEmptySet :: Set a -> Maybe (NESet a)

-- | <i>O(log n)</i>. Convert a non-empty set back into a normal
--   possibly-empty map, for usage with functions that expect <a>Set</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the set in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptySet</a> and <tt><a>maybe</a> <a>empty</a> <a>toSet</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toSet (fromList ((3,"a") :| [(5,"b")])) == Data.Set.fromList [(3,"a"), (5,"b")]
--   </pre>
toSet :: NESet a -> Set a

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>Set</a> as if it were an <a>NESet</a>. <tt><a>withNonEmpty</a> def
--   f</tt> will take a <a>Set</a>. If set is empty, it will evaluate to
--   <tt>def</tt>. Otherwise, a non-empty set <a>NESet</a> will be fed to
--   the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptySet</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NESet a -> r) -> Set a -> r

-- | <i>O(log n)</i>. Convert a <a>Set</a> into an <a>NESet</a> by adding a
--   value. Because of this, we know that the set must have at least one
--   element, and so therefore cannot be empty.
--   
--   See <a>insertSetMin</a> for a version that is constant-time if the new
--   value is <i>strictly smaller than</i> all values in the original set
--   
--   <pre>
--   insertSet 4 (Data.Set.fromList [5, 3]) == fromList (3 :| [4, 5])
--   insertSet 4 Data.Set.empty == singleton 4 "c"
--   </pre>
insertSet :: Ord a => a -> Set a -> NESet a

-- | <i>O(1)</i> Convert a <a>Set</a> into an <a>NESet</a> by adding a
--   value where the value is <i>strictly less than</i> all values in the
--   input set The values in the original map must all be <i>strictly
--   greater than</i> the new value. <i>The precondition is not
--   checked.</i>
--   
--   <pre>
--   insertSetMin 2 (Data.Set.fromList [5, 3]) == fromList (2 :| [3, 5])
--   valid (insertSetMin 2 (Data.Set.fromList [5, 3])) == True
--   valid (insertSetMin 7 (Data.Set.fromList [5, 3])) == False
--   valid (insertSetMin 3 (Data.Set.fromList [5, 3])) == False
--   </pre>
insertSetMin :: a -> Set a -> NESet a

-- | <i>O(log n)</i> Convert a <a>Set</a> into an <a>NESet</a> by adding a
--   value where the value is <i>strictly less than</i> all values in the
--   input set The values in the original map must all be <i>strictly
--   greater than</i> the new value. <i>The precondition is not
--   checked.</i>
--   
--   While this has the same asymptotics as <a>insertSet</a>, it saves a
--   constant factor for key comparison (so may be helpful if comparison is
--   expensive) and also does not require an <a>Ord</a> instance for the
--   key type.
--   
--   <pre>
--   insertSetMin 7 (Data.Set.fromList [5, 3]) == fromList (3 :| [5, 7])
--   valid (insertSetMin 7 (Data.Set.fromList [5, 3])) == True
--   valid (insertSetMin 2 (Data.Set.fromList [5, 3])) == False
--   valid (insertSetMin 5 (Data.Set.fromList [5, 3])) == False
--   </pre>
insertSetMax :: a -> Set a -> NESet a

-- | <i>O(log n)</i>. Unsafe version of <a>nonEmptySet</a>. Coerces a
--   <a>Set</a> into an <a>NESet</a>, but is undefined (throws a runtime
--   exception when evaluation is attempted) for an empty <a>Set</a>.
unsafeFromSet :: Set a -> NESet a

-- | <i>O(1)</i>. Create a singleton set.
singleton :: a -> NESet a

-- | <i>O(n*log n)</i>. Create a set from a list of elements.
fromList :: Ord a => NonEmpty a -> NESet a

-- | <i>O(n)</i>. Build a set from an ascending list in linear time. /The
--   precondition (input list is ascending) is not checked./
fromAscList :: Eq a => NonEmpty a -> NESet a

-- | <i>O(n)</i>. Build a set from a descending list in linear time. <i>The
--   precondition (input list is descending) is not checked.</i>
fromDescList :: Eq a => NonEmpty a -> NESet a

-- | <i>O(n)</i>. Build a set from an ascending list of distinct elements
--   in linear time. <i>The precondition (input list is strictly ascending)
--   is not checked.</i>
fromDistinctAscList :: NonEmpty a -> NESet a

-- | <i>O(n)</i>. Build a set from a descending list of distinct elements
--   in linear time. <i>The precondition (input list is strictly
--   descending) is not checked.</i>
fromDistinctDescList :: NonEmpty a -> NESet a

-- | Calculate the power set of a non-empty: the set of all its (non-empty)
--   subsets.
--   
--   <pre>
--   t <a>`member`</a> powerSet s == t <a>`isSubsetOf`</a> s
--   </pre>
--   
--   Example:
--   
--   <pre>
--   powerSet (fromList (1 :| [2,3])) =
--     fromList (singleton 1 :| [ singleton 2
--                              , singleton 3
--                              , fromList (1 :| [2])
--                              , fromList (1 :| [3])
--                              , fromList (2 :| [3])
--                              , fromList (1 :| [2,3])
--                              ]
--              )
--   </pre>
--   
--   We know that the result is non-empty because the result will always at
--   least contain the original set.
powerSet :: forall a. () => NESet a -> NESet (NESet a)

-- | <i>O(log n)</i>. Insert an element in a set. If the set already
--   contains an element equal to the given value, it is replaced with the
--   new value.
insert :: Ord a => a -> NESet a -> NESet a

-- | <i>O(log n)</i>. Delete an element from a set.
delete :: Ord a => a -> NESet a -> Set a

-- | <i>O(log n)</i>. Is the element in the set?
member :: Ord a => a -> NESet a -> Bool

-- | <i>O(log n)</i>. Is the element not in the set?
notMember :: Ord a => a -> NESet a -> Bool

-- | <i>O(log n)</i>. Find largest element smaller than the given one.
--   
--   <pre>
--   lookupLT 3 (fromList (3 :| [5])) == Nothing
--   lookupLT 5 (fromList (3 :| [5])) == Just 3
--   </pre>
lookupLT :: Ord a => a -> NESet a -> Maybe a

-- | <i>O(log n)</i>. Find smallest element greater than the given one.
--   
--   <pre>
--   lookupLT 4 (fromList (3 :| [5])) == Just 5
--   lookupLT 5 (fromList (3 :| [5])) == Nothing
--   </pre>
lookupGT :: Ord a => a -> NESet a -> Maybe a

-- | <i>O(log n)</i>. Find largest element smaller or equal to the given
--   one.
--   
--   <pre>
--   lookupLT 2 (fromList (3 :| [5])) == Nothing
--   lookupLT 4 (fromList (3 :| [5])) == Just 3
--   lookupLT 5 (fromList (3 :| [5])) == Just 5
--   </pre>
lookupLE :: Ord a => a -> NESet a -> Maybe a

-- | <i>O(log n)</i>. Find smallest element greater or equal to the given
--   one.
--   
--   <pre>
--   lookupLT 3 (fromList (3 :| [5])) == Just 3
--   lookupLT 4 (fromList (3 :| [5])) == Just 5
--   lookupLT 6 (fromList (3 :| [5])) == Nothing
--   </pre>
lookupGE :: Ord a => a -> NESet a -> Maybe a

-- | <i>O(1)</i>. The number of elements in the set. Guaranteed to be
--   greater than zero.
size :: NESet a -> Int

-- | <i>O(n+m)</i>. Is this a subset? <tt>(s1 `isSubsetOf` s2)</tt> tells
--   whether <tt>s1</tt> is a subset of <tt>s2</tt>.
isSubsetOf :: Ord a => NESet a -> NESet a -> Bool

-- | <i>O(n+m)</i>. Is this a proper subset? (ie. a subset but not equal).
isProperSubsetOf :: Ord a => NESet a -> NESet a -> Bool

-- | <i>O(n+m)</i>. Check whether two sets are disjoint (i.e. their
--   intersection is empty).
--   
--   <pre>
--   disjoint (fromList (2:|[4,6]))   (fromList (1:|[3]))     == True
--   disjoint (fromList (2:|[4,6,8])) (fromList (2:|[3,5,7])) == False
--   disjoint (fromList (1:|[2]))     (fromList (1:|[2,3,4])) == False
--   </pre>
disjoint :: Ord a => NESet a -> NESet a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The union of two sets, preferring
--   the first set when equal elements are encountered.
union :: Ord a => NESet a -> NESet a -> NESet a

-- | The union of a non-empty list of sets
unions :: (Foldable1 f, Ord a) => f (NESet a) -> NESet a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Difference of two sets.
--   
--   Returns a potentially empty set (<a>Set</a>) because the first set
--   might be a subset of the second set, and therefore have all of its
--   elements removed.
difference :: Ord a => NESet a -> NESet a -> Set a

-- | Same as <a>difference</a>.
(\\) :: Ord a => NESet a -> NESet a -> Set a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The intersection of two sets.
--   
--   Returns a potentially empty set (<a>Set</a>), because the two sets
--   might have an empty intersection.
--   
--   Elements of the result come from the first set, so for example
--   
--   <pre>
--   import qualified Data.Set.NonEmpty as NES
--   data AB = A | B deriving Show
--   instance Ord AB where compare _ _ = EQ
--   instance Eq AB where _ == _ = True
--   main = print (NES.singleton A `NES.intersection` NES.singleton B,
--                 NES.singleton B `NES.intersection` NES.singleton A)
--   </pre>
--   
--   prints <tt>(fromList (A:|[]),fromList (B:|[]))</tt>.
intersection :: Ord a => NESet a -> NESet a -> Set a

-- | Calculate the Cartesian product of two sets.
--   
--   <pre>
--   cartesianProduct xs ys = fromList $ liftA2 (,) (toList xs) (toList ys)
--   </pre>
--   
--   Example:
--   
--   <pre>
--   cartesianProduct (fromList (1:|[2])) (fromList ('a':|['b'])) =
--     fromList ((1,'a') :| [(1,'b'), (2,'a'), (2,'b')])
--   </pre>
cartesianProduct :: NESet a -> NESet b -> NESet (a, b)

-- | Calculate the disjoint union of two sets.
--   
--   <pre>
--   disjointUnion xs ys = map Left xs <a>`union`</a> map Right ys
--   </pre>
--   
--   Example:
--   
--   <pre>
--   disjointUnion (fromList (1:|[2])) (fromList ("hi":|["bye"])) =
--     fromList (Left 1 :| [Left 2, Right "hi", Right "bye"])
--   </pre>
disjointUnion :: NESet a -> NESet b -> NESet (Either a b)

-- | <i>O(n)</i>. Filter all elements that satisfy the predicate.
--   
--   Returns a potentially empty set (<a>Set</a>) because the predicate
--   might filter out all items in the original non-empty set.
filter :: (a -> Bool) -> NESet a -> Set a

-- | <i>O(log n)</i>. Take while a predicate on the elements holds. The
--   user is responsible for ensuring that for all elements <tt>j</tt> and
--   <tt>k</tt> in the set, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See
--   note at <a>spanAntitone</a>.
--   
--   Returns a potentially empty set (<a>Set</a>) because the predicate
--   might fail on the first input.
--   
--   <pre>
--   takeWhileAntitone p = Data.Set.fromDistinctAscList . Data.List.NonEmpty.takeWhile p . <a>toList</a>
--   takeWhileAntitone p = <a>filter</a> p
--   </pre>
takeWhileAntitone :: (a -> Bool) -> NESet a -> Set a

-- | <i>O(log n)</i>. Drop while a predicate on the elements holds. The
--   user is responsible for ensuring that for all elements <tt>j</tt> and
--   <tt>k</tt> in the set, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See
--   note at <a>spanAntitone</a>.
--   
--   Returns a potentially empty set (<a>Set</a>) because the predicate
--   might be true for all items.
--   
--   <pre>
--   dropWhileAntitone p = Data.Set.fromDistinctAscList . Data.List.NonEmpty.dropWhile p . <a>toList</a>
--   dropWhileAntitone p = <a>filter</a> (not . p)
--   </pre>
dropWhileAntitone :: (a -> Bool) -> NESet a -> Set a

-- | <i>O(log n)</i>. Divide a set at the point where a predicate on the
--   elements stops holding. The user is responsible for ensuring that for
--   all elements <tt>j</tt> and <tt>k</tt> in the set, <tt>j &lt; k ==&gt;
--   p j &gt;= p k</tt>.
--   
--   Returns a <a>These</a> with potentially two non-empty sets:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate never failed for
--   any item, returning the original set</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate failed for the
--   first item, returning the original set</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (the set up to the
--   point where the predicate stops holding) and <tt>n2</tt> (the set
--   starting from the point where the predicate stops holding)</li>
--   </ul>
--   
--   <pre>
--   spanAntitone p xs = partition p xs
--   </pre>
--   
--   Note: if <tt>p</tt> is not actually antitone, then
--   <tt>spanAntitone</tt> will split the set at some <i>unspecified</i>
--   point where the predicate switches from holding to not holding (where
--   the predicate is seen to hold before the first element and to fail
--   after the last element).
spanAntitone :: (a -> Bool) -> NESet a -> These (NESet a) (NESet a)

-- | <i>O(n)</i>. Partition the map according to a predicate.
--   
--   Returns a <a>These</a> with potentially two non-empty sets:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate was true for all
--   items.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate was false for all
--   items.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (all of the items
--   that were true for the predicate) and <tt>n2</tt> (all of the items
--   that were false for the predicate).</li>
--   </ul>
--   
--   See also <a>split</a>.
--   
--   <pre>
--   partition (&gt; 3) (fromList (5 :| [3])) == These (singleton 5) (singleton 3)
--   partition (&lt; 7) (fromList (5 :| [3])) == This  (fromList (3 :| [5]))
--   partition (&gt; 7) (fromList (5 :| [3])) == That  (fromList (3 :| [5]))
--   </pre>
partition :: (a -> Bool) -> NESet a -> These (NESet a) (NESet a)

-- | <i>O(log n)</i>. The expression (<tt><a>split</a> x set</tt>) is
--   potentially a <a>These</a> containing up to two <a>NESet</a>s based on
--   splitting the set into sets containing items before and after the
--   value <tt>x</tt>. It will never return a set that contains <tt>x</tt>
--   itself.
--   
--   <ul>
--   <li><a>Nothing</a> means that <tt>x</tt> was the only value in the the
--   original set, and so there are no items before or after it.</li>
--   <li><tt><a>Just</a> (<a>This</a> n1)</tt> means <tt>x</tt> was larger
--   than or equal to all items in the set, and <tt>n1</tt> is the entire
--   original set (minus <tt>x</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>That</a> n2)</tt> means <tt>x</tt> was smaller
--   than or equal to all items in the set, and <tt>n2</tt> is the entire
--   original set (minus <tt>x</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>These</a> n1 n2)</tt> gives <tt>n1</tt> (the
--   set of all values from the original set less than <tt>x</tt>) and
--   <tt>n2</tt> (the set of all values from the original set greater than
--   <tt>x</tt>).</li>
--   </ul>
--   
--   <pre>
--   split 2 (fromList (5 :| [3])) == Just (That  (fromList (3 :| [5]))      )
--   split 3 (fromList (5 :| [3])) == Just (That  (singleton 5)              )
--   split 4 (fromList (5 :| [3])) == Just (These (singleton 3) (singleton 5))
--   split 5 (fromList (5 :| [3])) == Just (This  (singleton 3)              )
--   split 6 (fromList (5 :| [3])) == Just (This  (fromList (3 :| [5]))      )
--   split 5 (singleton 5)         == Nothing
--   </pre>
split :: Ord a => a -> NESet a -> Maybe (These (NESet a) (NESet a))

-- | <i>O(log n)</i>. The expression (<tt><a>splitMember</a> x set</tt>)
--   splits a set just like <a>split</a> but also returns <tt><a>member</a>
--   x set</tt> (whether or not <tt>x</tt> was in <tt>set</tt>)
--   
--   <pre>
--   splitMember 2 (fromList (5 :| [3])) == (False, Just (That  (fromList (3 :| [5)]))))
--   splitMember 3 (fromList (5 :| [3])) == (True , Just (That  (singleton 5)))
--   splitMember 4 (fromList (5 :| [3])) == (False, Just (These (singleton 3) (singleton 5)))
--   splitMember 5 (fromList (5 :| [3])) == (True , Just (This  (singleton 3))
--   splitMember 6 (fromList (5 :| [3])) == (False, Just (This  (fromList (3 :| [5])))
--   splitMember 5 (singleton 5)         == (True , Nothing)
--   </pre>
splitMember :: Ord a => a -> NESet a -> (Bool, Maybe (These (NESet a) (NESet a)))

-- | <i>O(1)</i>. Decompose a set into pieces based on the structure of the
--   underlying tree. This function is useful for consuming a set in
--   parallel.
--   
--   No guarantee is made as to the sizes of the pieces; an internal, but
--   deterministic process determines this. However, it is guaranteed that
--   the pieces returned will be in ascending order (all elements in the
--   first subset less than all elements in the second, and so on).
--   
--   Note that the current implementation does not return more than four
--   subsets, but you should not depend on this behaviour because it can
--   change in the future without notice.
splitRoot :: NESet a -> NonEmpty (NESet a)

-- | <i>O(log n)</i>. Lookup the <i>index</i> of an element, which is its
--   zero-based index in the sorted sequence of elements. The index is a
--   number from <i>0</i> up to, but not including, the <a>size</a> of the
--   set.
--   
--   <pre>
--   isJust   (lookupIndex 2 (fromList (5:|[3]))) == False
--   fromJust (lookupIndex 3 (fromList (5:|[3]))) == 0
--   fromJust (lookupIndex 5 (fromList (5:|[3]))) == 1
--   isJust   (lookupIndex 6 (fromList (5:|[3]))) == False
--   </pre>
lookupIndex :: Ord a => a -> NESet a -> Maybe Int

-- | <i>O(log n)</i>. Return the <i>index</i> of an element, which is its
--   zero-based index in the sorted sequence of elements. The index is a
--   number from <i>0</i> up to, but not including, the <a>size</a> of the
--   set. Calls <a>error</a> when the element is not a <a>member</a> of the
--   set.
--   
--   <pre>
--   findIndex 2 (fromList (5:|[3]))    Error: element is not in the set
--   findIndex 3 (fromList (5:|[3])) == 0
--   findIndex 5 (fromList (5:|[3])) == 1
--   findIndex 6 (fromList (5:|[3]))    Error: element is not in the set
--   </pre>
findIndex :: Ord a => a -> NESet a -> Int

-- | <i>O(log n)</i>. Retrieve an element by its <i>index</i>, i.e. by its
--   zero-based index in the sorted sequence of elements. If the
--   <i>index</i> is out of range (less than zero, greater or equal to
--   <a>size</a> of the set), <a>error</a> is called.
--   
--   <pre>
--   elemAt 0 (fromList (5:|[3])) == 3
--   elemAt 1 (fromList (5:|[3])) == 5
--   elemAt 2 (fromList (5:|[3]))    Error: index out of range
--   </pre>
elemAt :: Int -> NESet a -> a

-- | <i>O(log n)</i>. Delete the element at <i>index</i>, i.e. by its
--   zero-based index in the sorted sequence of elements. If the
--   <i>index</i> is out of range (less than zero, greater or equal to
--   <a>size</a> of the set), <a>error</a> is called.
--   
--   Returns a potentially empty set (<a>Set</a>), because this could
--   potentailly delete the final element in a singleton set.
--   
--   <pre>
--   deleteAt 0    (fromList (5:|[3])) == singleton 5
--   deleteAt 1    (fromList (5:|[3])) == singleton 3
--   deleteAt 2    (fromList (5:|[3]))    Error: index out of range
--   deleteAt (-1) (fromList (5:|[3]))    Error: index out of range
--   </pre>
deleteAt :: Int -> NESet a -> Set a

-- | Take a given number of elements in order, beginning with the smallest
--   ones.
--   
--   Returns a potentailly empty set (<a>Set</a>), which can only happen
--   when calling <tt>take 0</tt>.
--   
--   <pre>
--   take n = Data.Set.fromDistinctAscList . Data.List.NonEmpty.take n . <a>toAscList</a>
--   </pre>
take :: Int -> NESet a -> Set a

-- | Drop a given number of elements in order, beginning with the smallest
--   ones.
--   
--   Returns a potentailly empty set (<a>Set</a>), in the case that
--   <a>drop</a> is called with a number equal to or greater the number of
--   items in the set, and we drop every item.
--   
--   <pre>
--   drop n = Data.Set.fromDistinctAscList . Data.List.NonEmpty.drop n . <a>toAscList</a>
--   </pre>
drop :: Int -> NESet a -> Set a

-- | <i>O(log n)</i>. Split a set at a particular index <tt>i</tt>.
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that there are less than <tt>i</tt>
--   items in the set, and <tt>n1</tt> is the original set.</li>
--   <li><tt><a>That</a> n2</tt> means <tt>i</tt> was 0; we dropped 0
--   items, so <tt>n2</tt> is the original set.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (taking <tt>i</tt>
--   items from the original set) and <tt>n2</tt> (dropping <tt>i</tt>
--   items from the original set))</li>
--   </ul>
splitAt :: Int -> NESet a -> These (NESet a) (NESet a)

-- | <i>O(n*log n)</i>. <tt><a>map</a> f s</tt> is the set obtained by
--   applying <tt>f</tt> to each element of <tt>s</tt>.
--   
--   It's worth noting that the size of the result may be smaller if, for
--   some <tt>(x,y)</tt>, <tt>x /= y &amp;&amp; f x == f y</tt>
map :: Ord b => (a -> b) -> NESet a -> NESet b

-- | <i>O(n)</i>. <tt><a>mapMonotonic</a> f s == <a>map</a> f s</tt>, but
--   works only when <tt>f</tt> is strictly increasing. <i>The precondition
--   is not checked.</i> Semi-formally, we have:
--   
--   <pre>
--   and [x &lt; y ==&gt; f x &lt; f y | x &lt;- ls, y &lt;- ls]
--                       ==&gt; mapMonotonic f s == map f s
--       where ls = Data.Foldable.toList s
--   </pre>
mapMonotonic :: (a -> b) -> NESet a -> NESet b

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   elemsList set = foldr (:) [] set
--   </pre>
foldr :: (a -> b -> b) -> b -> NESet a -> b

-- | <i>O(n)</i>. Fold the elements in the set using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   descElemsList set = foldl (flip (:)) [] set
--   </pre>
foldl :: (a -> b -> a) -> a -> NESet b -> a

-- | A variant of <a>foldr</a> that has no base case, and thus may only be
--   applied to non-empty structures.
--   
--   <pre>
--   <a>foldr1</a> f = <a>foldr1</a> f . <a>toList</a>
--   </pre>
foldr1 :: Foldable t => (a -> a -> a) -> t a -> a

-- | A variant of <a>foldl</a> that has no base case, and thus may only be
--   applied to non-empty structures.
--   
--   <pre>
--   <a>foldl1</a> f = <a>foldl1</a> f . <a>toList</a>
--   </pre>
foldl1 :: Foldable t => (a -> a -> a) -> t a -> a

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> NESet a -> b

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> NESet b -> a

-- | <i>O(n)</i>. A strict version of <a>foldr1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldr1' :: (a -> a -> a) -> NESet a -> a

-- | <i>O(n)</i>. A strict version of <a>foldl1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldl1' :: (a -> a -> a) -> NESet a -> a

-- | <i>O(1)</i>. The minimal element of a set. Note that this is total,
--   making <a>lookupMin</a> obsolete. It is constant-time, so has better
--   asymptotics than <tt>Data.Set.lookupMin</tt> and
--   <tt>Data.Map.findMin</tt> as well.
--   
--   <pre>
--   findMin (fromList (5 :| [3])) == 3
--   </pre>
findMin :: NESet a -> a

-- | <i>O(log n)</i>. The maximal key of a set Note that this is total,
--   making <a>lookupMin</a> obsolete.
--   
--   <pre>
--   findMax (fromList (5 :| [3])) == 5
--   </pre>
findMax :: NESet a -> a

-- | <i>O(1)</i>. Delete the minimal element. Returns a potentially empty
--   set (<a>Set</a>), because we might delete the final item in a
--   singleton set. It is constant-time, so has better asymptotics than
--   <tt>Data.Set.deleteMin</tt>.
--   
--   <pre>
--   deleteMin (fromList (5 :| [3, 7])) == Data.Set.fromList [5, 7]
--   deleteMin (singleton 5) == Data.Set.empty
--   </pre>
deleteMin :: NESet a -> Set a

-- | <i>O(log n)</i>. Delete the maximal element. Returns a potentially
--   empty set (<a>Set</a>), because we might delete the final item in a
--   singleton set.
--   
--   <pre>
--   deleteMax (fromList (5 :| [3, 7])) == Data.Set.fromList [3, 5]
--   deleteMax (singleton 5) == Data.Set.empty
--   </pre>
deleteMax :: NESet a -> Set a

-- | <i>O(1)</i>. Delete and find the minimal element. It is constant-time,
--   so has better asymptotics that <tt>Data.Set.minView</tt> for
--   <a>Set</a>.
--   
--   Note that unlike <tt>Data.Set.deleteFindMin</tt> for <a>Set</a>, this
--   cannot ever fail, and so is a total function. However, the result
--   <a>Set</a> is potentially empty, since the original set might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMin (fromList (5 :| [3, 10])) == (3, Data.Set.fromList [5, 10])
--   </pre>
deleteFindMin :: NESet a -> (a, Set a)

-- | <i>O(log n)</i>. Delete and find the minimal element.
--   
--   Note that unlike <tt>Data.Set.deleteFindMax</tt> for <a>Set</a>, this
--   cannot ever fail, and so is a total function. However, the result
--   <a>Set</a> is potentially empty, since the original set might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMax (fromList (5 :| [3, 10])) == (10, Data.Set.fromList [3, 5])
--   </pre>
deleteFindMax :: NESet a -> (a, Set a)

-- | <i>O(n)</i>. An alias of <a>toAscList</a>. The elements of a set in
--   ascending order.
elems :: NESet a -> NonEmpty a

-- | <i>O(n)</i>. Convert the set to a non-empty list of elements.
toList :: NESet a -> NonEmpty a

-- | <i>O(n)</i>. Convert the set to an ascending non-empty list of
--   elements.
toAscList :: NESet a -> NonEmpty a

-- | <i>O(n)</i>. Convert the set to a descending non-empty list of
--   elements.
toDescList :: NESet a -> NonEmpty a

-- | <i>O(n)</i>. Test if the internal set structure is valid.
valid :: Ord a => NESet a -> Bool


-- | <h1>Non-Empty Finite Maps (lazy interface)</h1>
--   
--   The <tt><a>NEMap</a> k v</tt> type represents a non-empty finite map
--   (sometimes called a dictionary) from keys of type <tt>k</tt> to values
--   of type <tt>v</tt>. An <a>NEMap</a> is strict in its keys but lazy in
--   its values.
--   
--   See documentation for <a>NEMap</a> for information on how to convert
--   and manipulate such non-empty maps.
--   
--   This module essentially re-imports the API of <a>Data.Map.Lazy</a> and
--   its <a>Map</a> type, along with semantics and asymptotics. In most
--   situations, asymptotics are different only by a constant factor. In
--   some situations, asmyptotics are even better (constant-time instead of
--   log-time). All typeclass constraints are identical to their
--   <a>Data.Map</a> counterparts.
--   
--   Because <a>NEMap</a> is implemented using <a>Map</a>, all of the
--   caveats of using <a>Map</a> apply (such as the limitation of the
--   maximum size of maps).
--   
--   All functions take non-empty maps as inputs. In situations where their
--   results can be guarunteed to also be non-empty, they also return
--   non-empty maps. In situations where their results could potentially be
--   empty, <a>Map</a> is returned instead.
--   
--   Some variants of functions (like <a>alter'</a>, <a>alterF'</a>,
--   <a>adjustAt</a>, <a>adjustMin</a>, <a>adjustMax</a>,
--   <a>adjustMinWithKey</a>, <a>adjustMaxWithKey</a>) are provided in a
--   way restructured to preserve guaruntees of non-empty maps being
--   returned.
--   
--   Some functions (like <a>mapEither</a>, <a>partition</a>,
--   <a>spanAntitone</a>, <a>split</a>) have modified return types to
--   account for possible configurations of non-emptiness.
--   
--   This module is intended to be imported qualified, to avoid name
--   clashes with <a>Prelude</a> and <a>Data.Map</a> functions:
--   
--   <pre>
--   import qualified Data.Map.NonEmpty as NEM
--   </pre>
--   
--   At the moment, this package does not provide a variant strict on
--   values for these functions, like <i>containers</i> does. This is a
--   planned future implementation (PR's are appreciated). For now, you can
--   simulate a strict interface by manually forcing values before
--   returning results.
module Data.Map.NonEmpty

-- | A non-empty (by construction) map from keys <tt>k</tt> to values
--   <tt>a</tt>. At least one key-value pair exists in an <tt><a>NEMap</a>
--   k v</tt> at all times.
--   
--   Functions that <i>take</i> an <a>NEMap</a> can safely operate on it
--   with the assumption that it has at least one key-value pair.
--   
--   Functions that <i>return</i> an <a>NEMap</a> provide an assurance that
--   the result has at least one key-value pair.
--   
--   <a>Data.Map.NonEmpty</a> re-exports the API of <a>Data.Map</a>,
--   faithfully reproducing asymptotics, typeclass constraints, and
--   semantics. Functions that ensure that input and output maps are both
--   non-empty (like <a>insert</a>) return <a>NEMap</a>, but functions that
--   might potentially return an empty map (like <a>delete</a>) return a
--   <a>Map</a> instead.
--   
--   You can directly construct an <a>NEMap</a> with the API from
--   <a>Data.Map.NonEmpty</a>; it's more or less the same as constructing a
--   normal <a>Map</a>, except you don't have access to <a>empty</a>. There
--   are also a few ways to construct an <a>NEMap</a> from a <a>Map</a>:
--   
--   <ol>
--   <li>The <a>nonEmptyMap</a> smart constructor will convert a
--   <tt><a>Map</a> k a</tt> into a <tt><a>Maybe</a> (<a>NEMap</a> k
--   a)</tt>, returning <a>Nothing</a> if the original <a>Map</a> was
--   empty.</li>
--   <li>You can use the <a>insertMap</a> family of functions to insert a
--   value into a <a>Map</a> to create a guaranteed <a>NEMap</a>.</li>
--   <li>You can use the <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns to
--   "pattern match" on a <a>Map</a> to reveal it as either containing a
--   <a>NEMap</a> or an empty map.</li>
--   <li><a>withNonEmpty</a> offers a continuation-based interface for
--   deconstructing a <a>Map</a> and treating it as if it were an
--   <a>NEMap</a>.</li>
--   </ol>
--   
--   You can convert an <a>NEMap</a> into a <a>Map</a> with <a>toMap</a> or
--   <a>IsNonEmpty</a>, essentially "obscuring" the non-empty property from
--   the type.
data NEMap k a

-- | <i>O(1)</i> match, <i>O(log n)</i> usage of contents. The
--   <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow you to treat a
--   <a>Map</a> as if it were either a <tt><a>IsNonEmpty</a> n</tt> (where
--   <tt>n</tt> is a <a>NEMap</a>) or an <a>IsEmpty</a>.
--   
--   For example, you can pattern match on a <a>Map</a>:
--   
--   <pre>
--   myFunc :: <a>Map</a> K X -&gt; Y
--   myFunc (<a>IsNonEmpty</a> n) =  -- here, the user provided a non-empty map, and <tt>n</tt> is the <a>NEMap</a>
--   myFunc <a>IsEmpty</a>        =  -- here, the user provided an empty map.
--   </pre>
--   
--   Matching on <tt><a>IsNonEmpty</a> n</tt> means that the original
--   <a>Map</a> was <i>not</i> empty, and you have a verified-non-empty
--   <a>NEMap</a> <tt>n</tt> to use.
--   
--   Note that patching on this pattern is <i>O(1)</i>. However, using the
--   contents requires a <i>O(log n)</i> cost that is deferred until after
--   the pattern is matched on (and is not incurred at all if the contents
--   are never used).
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsNonEmpty</a> to
--   convert a <a>NEMap</a> back into a <a>Map</a>, obscuring its
--   non-emptiness (see <a>toMap</a>).
pattern IsNonEmpty :: NEMap k a -> Map k a

-- | <i>O(1)</i>. The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow
--   you to treat a <a>Map</a> as if it were either a <tt><a>IsNonEmpty</a>
--   n</tt> (where <tt>n</tt> is a <a>NEMap</a>) or an <a>IsEmpty</a>.
--   
--   Matching on <a>IsEmpty</a> means that the original <a>Map</a> was
--   empty.
--   
--   A case statement handling both <a>IsNonEmpty</a> and <a>IsEmpty</a>
--   provides complete coverage.
--   
--   This is a bidirectional pattern, so you can use <a>IsEmpty</a> as an
--   expression, and it will be interpreted as <a>empty</a>.
--   
--   See <a>IsNonEmpty</a> for more information.
pattern IsEmpty :: Map k a

-- | <i>O(log n)</i>. Smart constructor for an <a>NEMap</a> from a
--   <a>Map</a>. Returns <a>Nothing</a> if the <a>Map</a> was originally
--   actually empty, and <tt><a>Just</a> n</tt> with an <a>NEMap</a>, if
--   the <a>Map</a> was not empty.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   See <a>IsNonEmpty</a> for a pattern synonym that lets you "match on"
--   the possiblity of a <a>Map</a> being an <a>NEMap</a>.
--   
--   <pre>
--   nonEmptyMap (Data.Map.fromList [(3,"a"), (5,"b")]) == Just (fromList ((3,"a") :| [(5,"b")]))
--   </pre>
nonEmptyMap :: Map k a -> Maybe (NEMap k a)

-- | <i>O(log n)</i>. Convert a non-empty map back into a normal
--   possibly-empty map, for usage with functions that expect <a>Map</a>.
--   
--   Can be thought of as "obscuring" the non-emptiness of the map in its
--   type. See the <a>IsNotEmpty</a> pattern.
--   
--   <a>nonEmptyMap</a> and <tt><a>maybe</a> <a>empty</a> <a>toMap</a></tt>
--   form an isomorphism: they are perfect structure-preserving inverses of
--   eachother.
--   
--   <pre>
--   toMap (fromList ((3,"a") :| [(5,"b")])) == Data.Map.fromList [(3,"a"), (5,"b")]
--   </pre>
toMap :: NEMap k a -> Map k a

-- | <i>O(log n)</i>. A general continuation-based way to consume a
--   <a>Map</a> as if it were an <a>NEMap</a>. <tt><a>withNonEmpty</a> def
--   f</tt> will take a <a>Map</a>. If map is empty, it will evaluate to
--   <tt>def</tt>. Otherwise, a non-empty map <a>NEMap</a> will be fed to
--   the function <tt>f</tt> instead.
--   
--   <pre>
--   <a>nonEmptyMap</a> == <a>withNonEmpty</a> <a>Nothing</a> <a>Just</a>
--   </pre>
withNonEmpty :: r -> (NEMap k a -> r) -> Map k a -> r

-- | <i>O(log n)</i>. Convert a <a>Map</a> into an <a>NEMap</a> by adding a
--   key-value pair. Because of this, we know that the map must have at
--   least one element, and so therefore cannot be empty. If key is already
--   present, will overwrite the original value.
--   
--   See <a>insertMapMin</a> for a version that is constant-time if the new
--   key is <i>strictly smaller than</i> all keys in the original map.
--   
--   <pre>
--   insertMap 4 "c" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(4,"c"), (5,"a")])
--   insertMap 4 "c" Data.Map.empty == singleton 4 "c"
--   </pre>
insertMap :: Ord k => k -> a -> Map k a -> NEMap k a

-- | <i>O(log n)</i>. Convert a <a>Map</a> into an <a>NEMap</a> by adding a
--   key-value pair. Because of this, we know that the map must have at
--   least one element, and so therefore cannot be empty. Uses a combining
--   function with the new value as the first argument if the key is
--   already present.
--   
--   <pre>
--   insertMapWith (++) 4 "c" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(4,"c"), (5,"a")])
--   insertMapWith (++) 5 "c" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(5,"ca")])
--   </pre>
insertMapWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> NEMap k a

-- | <i>O(log n)</i>. Convert a <a>Map</a> into an <a>NEMap</a> by adding a
--   key-value pair. Because of this, we know that the map must have at
--   least one element, and so therefore cannot be empty. Uses a combining
--   function with the key and new value as the first and second arguments
--   if the key is already present.
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertWithKey f 5 "xxx" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((3, "b") :| [(5, "5:xxx|a")])
--   insertWithKey f 7 "xxx" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   insertWithKey f 5 "xxx" Data.Map.empty                         == singleton 5 "xxx"
--   </pre>
insertMapWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> NEMap k a

-- | <i>O(1)</i> Convert a <a>Map</a> into an <a>NEMap</a> by adding a
--   key-value pair where the key is <i>strictly less than</i> all keys in
--   the input map. The keys in the original map must all be <i>strictly
--   greater than</i> the new key. <i>The precondition is not checked.</i>
--   
--   <pre>
--   insertMapMin 2 "c" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((2,"c") :| [(3,"b"), (5,"a")])
--   valid (insertMapMin 2 "c" (Data.Map.fromList [(5,"a"), (3,"b")])) == True
--   valid (insertMapMin 7 "c" (Data.Map.fromList [(5,"a"), (3,"b")])) == False
--   valid (insertMapMin 3 "c" (Data.Map.fromList [(5,"a"), (3,"b")])) == False
--   </pre>
insertMapMin :: k -> a -> Map k a -> NEMap k a

-- | <i>O(log n)</i> Convert a <a>Map</a> into an <a>NEMap</a> by adding a
--   key-value pair where the key is <i>strictly greater than</i> all keys
--   in the input map. The keys in the original map must all be <i>strictly
--   less than</i> the new key. <i>The precondition is not checked.</i>
--   
--   While this has the same asymptotics as <a>insertMap</a>, it saves a
--   constant factor for key comparison (so may be helpful if comparison is
--   expensive) and also does not require an <a>Ord</a> instance for the
--   key type.
--   
--   <pre>
--   insertMap 7 "c" (Data.Map.fromList [(5,"a"), (3,"b")]) == fromList ((3,"b") :| [(5,"a"), (7,"c")])
--   valid (insertMap 7 "c" (Data.Map.fromList [(5,"a"), (3,"b")])) == True
--   valid (insertMap 2 "c" (Data.Map.fromList [(5,"a"), (3,"b")])) == False
--   valid (insertMap 5 "c" (Data.Map.fromList [(5,"a"), (3,"b")])) == False
--   </pre>
insertMapMax :: k -> a -> Map k a -> NEMap k a

-- | <i>O(log n)</i>. Unsafe version of <a>nonEmptyMap</a>. Coerces a
--   <a>Map</a> into an <a>NEMap</a>, but is undefined (throws a runtime
--   exception when evaluation is attempted) for an empty <a>Map</a>.
unsafeFromMap :: Map k a -> NEMap k a

-- | <i>O(1)</i>. A map with a single element.
--   
--   <pre>
--   singleton 1 'a'        == fromList ((1, 'a') :| [])
--   size (singleton 1 'a') == 1
--   </pre>
singleton :: k -> a -> NEMap k a

-- | <i>O(n)</i>. Build a non-empty map from a non-empty set of keys and a
--   function which for each key computes its value.
--   
--   <pre>
--   fromSet (\k -&gt; replicate k 'a') (Data.Set.NonEmpty.fromList (3 :| [5])) == fromList ((5,"aaaaa") :| [(3,"aaa")])
--   </pre>
fromSet :: (k -> a) -> NESet k -> NEMap k a

-- | <i>O(n*log n)</i>. Build a non-empty map from a non-empty list of
--   key/value pairs. See also <a>fromAscList</a>. If the list contains
--   more than one value for the same key, the last value for the key is
--   retained.
--   
--   <pre>
--   fromList ((5,"a") :| [(3,"b"), (5, "c")]) == fromList ((5,"c") :| [(3,"b")])
--   fromList ((5,"c") :| [(3,"b"), (5, "a")]) == fromList ((5,"a") :| [(3,"b")])
--   </pre>
fromList :: Ord k => NonEmpty (k, a) -> NEMap k a

-- | <i>O(n*log n)</i>. Build a map from a non-empty list of key/value
--   pairs with a combining function. See also <a>fromAscListWith</a>.
--   
--   <pre>
--   fromListWith (++) ((5,"a") :| [(5,"b"), (3,"b"), (3,"a"), (5,"a")]) == fromList ((3, "ab") :| [(5, "aba")])
--   </pre>
fromListWith :: Ord k => (a -> a -> a) -> NonEmpty (k, a) -> NEMap k a

-- | <i>O(n*log n)</i>. Build a map from a non-empty list of key/value
--   pairs with a combining function. See also <a>fromAscListWithKey</a>.
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ a1 ++ a2
--   fromListWithKey f ((5,"a") :| [(5,"b"), (3,"b"), (3,"a"), (5,"a")]) == fromList ((3, "3ab") :| [(5, "5a5ba")])
--   </pre>
fromListWithKey :: Ord k => (k -> a -> a -> a) -> NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list in linear
--   time. <i>The precondition (input list is ascending) is not
--   checked.</i>
--   
--   <pre>
--   fromAscList ((3,"b") :| [(5,"a")])          == fromList ((3, "b") :| [(5, "a")])
--   fromAscList ((3,"b") :| [(5,"a"), (5,"b")]) == fromList ((3, "b") :| [(5, "b")])
--   valid (fromAscList ((3,"b") :| [(5,"a"), (5,"b")])) == True
--   valid (fromAscList ((5,"a") :| [(3,"b"), (5,"b")])) == False
--   </pre>
fromAscList :: Eq k => NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list in linear
--   time with a combining function for equal keys. /The precondition
--   (input list is ascending) is not checked./
--   
--   <pre>
--   fromAscListWith (++) ((3,"b") :| [(5,"a"), (5,"b")]) == fromList ((3, "b") :| [(5, "ba")])
--   valid (fromAscListWith (++) ((3,"b") :| [(5,"a"), (5,"b"))]) == True
--   valid (fromAscListWith (++) ((5,"a") :| [(3,"b"), (5,"b"))]) == False
--   </pre>
fromAscListWith :: Eq k => (a -> a -> a) -> NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list in linear
--   time with a combining function for equal keys. /The precondition
--   (input list is ascending) is not checked./
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
--   fromAscListWithKey f ((3,"b") :| [(5,"a"), (5,"b"), (5,"b")]) == fromList ((3, "b") :| [(5, "5:b5:ba")])
--   valid (fromAscListWithKey f ((3,"b") :| [(5,"a"), (5,"b"), (5,"b")])) == True
--   valid (fromAscListWithKey f ((5,"a") :| [(3,"b"), (5,"b"), (5,"b")])) == False
--   </pre>
fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from an ascending non-empty list of distinct
--   elements in linear time. <i>The precondition is not checked.</i>
--   
--   <pre>
--   fromDistinctAscList ((3,"b") :| [(5,"a")]) == fromList ((3, "b") :| [(5, "a")])
--   valid (fromDistinctAscList ((3,"b") :| [(5,"a")]))          == True
--   valid (fromDistinctAscList ((3,"b") :| [(5,"a"), (5,"b")])) == False
--   </pre>
fromDistinctAscList :: NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from a descending non-empty list in linear
--   time. <i>The precondition (input list is descending) is not
--   checked.</i>
--   
--   <pre>
--   fromDescList ((5,"a") :| [(3,"b")])          == fromList ((3, "b") :| [(5, "a")])
--   fromDescList ((5,"a") :| [(5,"b"), (3,"b")]) == fromList ((3, "b") :| [(5, "b")])
--   valid (fromDescList ((5,"a") :| [(5,"b"), (3,"b")])) == True
--   valid (fromDescList ((5,"a") :| [(3,"b"), (5,"b")])) == False
--   </pre>
fromDescList :: Eq k => NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from a descending non-empty list in linear
--   time with a combining function for equal keys. /The precondition
--   (input list is descending) is not checked./
--   
--   <pre>
--   fromDescListWith (++) ((5,"a") :| [(5,"b"), (3,"b")]) == fromList ((3, "b") :| [(5, "ba")])
--   valid (fromDescListWith (++) ((5,"a") :| [(5,"b"), (3,"b")])) == True
--   valid (fromDescListWith (++) ((5,"a") :| [(3,"b"), (5,"b")])) == False
--   </pre>
fromDescListWith :: Eq k => (a -> a -> a) -> NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from a descending non-empty list in linear
--   time with a combining function for equal keys. /The precondition
--   (input list is descending) is not checked./
--   
--   <pre>
--   let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
--   fromDescListWithKey f ((5,"a") :| [(5,"b"), (5,"b"), (3,"b")]) == fromList ((3, "b") :| [(5, "5:b5:ba")])
--   valid (fromDescListWithKey f ((5,"a") :| [(5,"b"), (5,"b"), (3,"b")])) == True
--   valid (fromDescListWithKey f ((5,"a") :| [(3,"b"), (5,"b"), (5,"b")])) == False
--   </pre>
fromDescListWithKey :: Eq k => (k -> a -> a -> a) -> NonEmpty (k, a) -> NEMap k a

-- | <i>O(n)</i>. Build a map from a descending list of distinct elements
--   in linear time. <i>The precondition is not checked.</i>
--   
--   <pre>
--   fromDistinctDescList ((5,"a") :| [(3,"b")]) == fromList ((3, "b") :| [(5, "a")])
--   valid (fromDistinctDescList ((5,"a") :| [(3,"b")]))          == True
--   valid (fromDistinctDescList ((5,"a") :| [(5,"b"), (3,"b")])) == False
--   </pre>
fromDistinctDescList :: NonEmpty (k, a) -> NEMap k a

-- | <i>O(log n)</i>. Insert a new key and value in the map. If the key is
--   already present in the map, the associated value is replaced with the
--   supplied value. <a>insert</a> is equivalent to <tt><a>insertWith</a>
--   <a>const</a></tt>.
--   
--   See <a>insertMap</a> for a version where the first argument is a
--   <a>Map</a>.
--   
--   <pre>
--   insert 5 'x' (fromList ((5,'a') :| [(3,'b')])) == fromList ((3, 'b') :| [(5, 'x')])
--   insert 7 'x' (fromList ((5,'a') :| [(3,'b')])) == fromList ((3, 'b') :| [(5, 'a'), (7, 'x')])
--   </pre>
insert :: Ord k => k -> a -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. Insert with a function, combining new value and old
--   value. <tt><a>insertWith</a> f key value mp</tt> will insert the pair
--   (key, value) into <tt>mp</tt> if key does not exist in the map. If the
--   key does exist, the function will insert the pair <tt>(key, f
--   new_value old_value)</tt>.
--   
--   See <a>insertMapWith</a> for a version where the first argument is a
--   <a>Map</a>.
--   
--   <pre>
--   insertWith (++) 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "xxxa")])
--   insertWith (++) 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   </pre>
insertWith :: Ord k => (a -> a -> a) -> k -> a -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. Insert with a function, combining key, new value and
--   old value. <tt><a>insertWithKey</a> f key value mp</tt> will insert
--   the pair (key, value) into <tt>mp</tt> if key does not exist in the
--   map. If the key does exist, the function will insert the pair
--   <tt>(key,f key new_value old_value)</tt>. Note that the key passed to
--   f is the same key passed to <a>insertWithKey</a>.
--   
--   See <a>insertMapWithKey</a> for a version where the first argument is
--   a <a>Map</a>.
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertWithKey f 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "5:xxx|a")])
--   insertWithKey f 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a"), (7, "xxx")])
--   </pre>
insertWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. Combines insert operation with old value retrieval.
--   The expression (<tt><a>insertLookupWithKey</a> f k x map</tt>) is a
--   pair where the first element is equal to (<tt><a>lookup</a> k
--   map</tt>) and the second element equal to (<tt><a>insertWithKey</a> f
--   k x map</tt>).
--   
--   <pre>
--   let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
--   insertLookupWithKey f 5 "xxx" (fromList ((5,"a") :| [(3,"b")])) == (Just "a", fromList ((3, "b") :| [(5, "5:xxx|a")]))
--   insertLookupWithKey f 7 "xxx" (fromList ((5,"a") :| [(3,"b")])) == (Nothing,  fromList ((3, "b") :| [(5, "a"), (7, "xxx")]))
--   </pre>
--   
--   This is how to define <tt>insertLookup</tt> using
--   <tt>insertLookupWithKey</tt>:
--   
--   <pre>
--   let insertLookup kx x t = insertLookupWithKey (\_ a _ -&gt; a) kx x t
--   insertLookup 5 "x" (fromList ((5,"a") :| [(3,"b")])) == (Just "a", fromList ((3, "b") :| [(5, "x")]))
--   insertLookup 7 "x" (fromList ((5,"a") :| [(3,"b")])) == (Nothing,  fromList ((3, "b") :| [(5, "a"), (7, "x")]))
--   </pre>
insertLookupWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> NEMap k a -> (Maybe a, NEMap k a)

-- | <i>O(log n)</i>. Delete a key and its value from the non-empty map. A
--   potentially empty map (<a>Map</a>) is returned, since this might
--   delete the last item in the <a>NEMap</a>. When the key is not a member
--   of the map, is equivalent to <a>toMap</a>.
--   
--   <pre>
--   delete 5 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "b"
--   delete 7 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.Singleton [(3, "b"), (5, "a")]
--   </pre>
delete :: Ord k => k -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Update a value at a specific key with the result of
--   the provided function. When the key is not a member of the map, the
--   original map is returned.
--   
--   <pre>
--   adjust ("new " ++) 5 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "new a")])
--   adjust ("new " ++) 7 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a")])
--   </pre>
adjust :: Ord k => (a -> a) -> k -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. Adjust a value at a specific key. When the key is not
--   a member of the map, the original map is returned.
--   
--   <pre>
--   let f key x = (show key) ++ ":new " ++ x
--   adjustWithKey f 5 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "5:new a")])
--   adjustWithKey f 7 (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "b") :| [(5, "a")])
--   </pre>
adjustWithKey :: Ord k => (k -> a -> a) -> k -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. The expression (<tt><a>update</a> f k map</tt>)
--   updates the value <tt>x</tt> at <tt>k</tt> (if it is in the map). If
--   (<tt>f x</tt>) is <a>Nothing</a>, the element is deleted. If it is
--   (<tt><a>Just</a> y</tt>), the key <tt>k</tt> is bound to the new value
--   <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>Map</a>), because we can't know
--   ahead of time if the function returns <a>Nothing</a> and deletes the
--   final item in the <a>NEMap</a>.
--   
--   <pre>
--   let f x = if x == "a" then Just "new a" else Nothing
--   update f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "new a")]
--   update f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "a")]
--   update f 3 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   </pre>
update :: Ord k => (a -> Maybe a) -> k -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. The expression (<tt><a>updateWithKey</a> f k
--   map</tt>) updates the value <tt>x</tt> at <tt>k</tt> (if it is in the
--   map). If (<tt>f k x</tt>) is <a>Nothing</a>, the element is deleted.
--   If it is (<tt><a>Just</a> y</tt>), the key <tt>k</tt> is bound to the
--   new value <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>Map</a>), because we can't know
--   ahead of time if the function returns <a>Nothing</a> and deletes the
--   final item in the <a>NEMap</a>.
--   
--   <pre>
--   let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
--   updateWithKey f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "5:new a")]
--   updateWithKey f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "a")]
--   updateWithKey f 3 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   </pre>
updateWithKey :: Ord k => (k -> a -> Maybe a) -> k -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Lookup and update. See also <a>updateWithKey</a>. The
--   function returns changed value, if it is updated. Returns the original
--   key value if the map entry is deleted.
--   
--   Returns a potentially empty map (<a>Map</a>) in the case that we
--   delete the final key of a singleton map.
--   
--   <pre>
--   let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
--   updateLookupWithKey f 5 (fromList ((5,"a") :| [(3,"b")])) == (Just "5:new a", Data.Map.fromList ((3, "b") :| [(5, "5:new a")]))
--   updateLookupWithKey f 7 (fromList ((5,"a") :| [(3,"b")])) == (Nothing,  Data.Map.fromList ((3, "b") :| [(5, "a")]))
--   updateLookupWithKey f 3 (fromList ((5,"a") :| [(3,"b")])) == (Just "b", Data.Map.singleton 5 "a")
--   </pre>
updateLookupWithKey :: Ord k => (k -> a -> Maybe a) -> k -> NEMap k a -> (Maybe a, Map k a)

-- | <i>O(log n)</i>. The expression (<tt><a>alter</a> f k map</tt>) alters
--   the value <tt>x</tt> at <tt>k</tt>, or absence thereof. <a>alter</a>
--   can be used to insert, delete, or update a value in a <a>Map</a>. In
--   short : <tt>Data.Map.lookup k (<a>alter</a> f k m) = f (<a>lookup</a>
--   k m)</tt>.
--   
--   Returns a potentially empty map (<a>Map</a>), because we can't know
--   ahead of time if the function returns <a>Nothing</a> and deletes the
--   final item in the <a>NEMap</a>.
--   
--   See <a>alterF'</a> for a version that disallows deletion, and so
--   therefore can return <a>NEMap</a>.
--   
--   <pre>
--   let f _ = Nothing
--   alter f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "a")]
--   alter f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "b"
--   
--   let f _ = Just "c"
--   alter f 7 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "a"), (7, "c")]
--   alter f 5 (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "c")]
--   </pre>
alter :: Ord k => (Maybe a -> Maybe a) -> k -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. The expression (<tt><a>alterF</a> f k map</tt>)
--   alters the value <tt>x</tt> at <tt>k</tt>, or absence thereof.
--   <a>alterF</a> can be used to inspect, insert, delete, or update a
--   value in a <a>Map</a>. In short: <tt>Data.Map.lookup k &lt;$&gt;
--   <a>alterF</a> f k m = f (<a>lookup</a> k m)</tt>.
--   
--   Example:
--   
--   <pre>
--   interactiveAlter :: Int -&gt; NEMap Int String -&gt; IO (Map Int String)
--   interactiveAlter k m = alterF f k m where
--     f Nothing = do
--        putStrLn $ show k ++
--            " was not found in the map. Would you like to add it?"
--        getUserResponse1 :: IO (Maybe String)
--     f (Just old) = do
--        putStrLn $ "The key is currently bound to " ++ show old ++
--            ". Would you like to change or delete it?"
--        getUserResponse2 :: IO (Maybe String)
--   </pre>
--   
--   Like <tt>Data.Map.alterF</tt> for <a>Map</a>, <a>alterF</a> can be
--   considered to be a unifying generalization of <a>lookup</a> and
--   <a>delete</a>; however, as a constrast, it cannot be used to implement
--   <a>insert</a>, because it must return a <a>Map</a> instead of an
--   <a>NEMap</a> (because the function might delete the final item in the
--   <a>NEMap</a>). When used with trivial functors like <a>Identity</a>
--   and <a>Const</a>, it is often slightly slower than specialized
--   <a>lookup</a> and <a>delete</a>. However, when the functor is
--   non-trivial and key comparison is not particularly cheap, it is the
--   fastest way.
--   
--   See <a>alterF'</a> for a version that disallows deletion, and so
--   therefore can return <a>NEMap</a> and be used to implement
--   <a>insert</a>
--   
--   Note on rewrite rules:
--   
--   This module includes GHC rewrite rules to optimize <a>alterF</a> for
--   the <a>Const</a> and <a>Identity</a> functors. In general, these rules
--   improve performance. The sole exception is that when using
--   <a>Identity</a>, deleting a key that is already absent takes longer
--   than it would without the rules. If you expect this to occur a very
--   large fraction of the time, you might consider using a private copy of
--   the <a>Identity</a> type.
--   
--   Note: Unlike <tt>Data.Map.alterF</tt> for <a>Map</a>, <a>alterF</a> is
--   <i>not</i> a flipped version of the <a>at</a> combinator from
--   <a>Control.Lens.At</a>. However, it match the shape expected from most
--   functions expecting lenses, getters, and setters, so can be thought of
--   as a "psuedo-lens", with virtually the same practical applications as
--   a legitimate lens.
alterF :: (Ord k, Functor f) => (Maybe a -> f (Maybe a)) -> k -> NEMap k a -> f (Map k a)

-- | <i>O(log n)</i>. Variant of <a>alter</a> that disallows deletion.
--   Allows us to guarantee that the result is also a non-empty Map.
alter' :: Ord k => (Maybe a -> a) -> k -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. Variant of <a>alterF</a> that disallows deletion.
--   Allows us to guarantee that the result is also a non-empty Map.
--   
--   Like <tt>Data.Map.alterF</tt> for <a>Map</a>, can be used to
--   generalize and unify <a>lookup</a> and <a>insert</a>. However, because
--   it disallows deletion, it cannot be used to implement <a>delete</a>.
--   
--   See <a>alterF</a> for usage information and caveats.
--   
--   Note: Neither <a>alterF</a> nor <a>alterF'</a> can be considered
--   flipped versions of the <a>at</a> combinator from
--   <a>Control.Lens.At</a>. However, this can match the shape expected
--   from most functions expecting lenses, getters, and setters, so can be
--   thought of as a "psuedo-lens", with virtually the same practical
--   applications as a legitimate lens.
--   
--   <b>WARNING</b>: The rewrite rule for <a>Identity</a> exposes an
--   inconsistency in undefined behavior for <a>Data.Map</a>.
--   <tt>Data.Map.alterF</tt> will actually <i>maintain</i> the original
--   key in the map when used with <a>Identity</a>; however,
--   <tt>Data.Map.insertWith</tt> will <i>replace</i> the orginal key in
--   the map. The rewrite rule for <a>alterF'</a> has chosen to be faithful
--   to <tt>Data.Map.insertWith</tt>, and <i>not</i>
--   <tt>Data.Map.alterF</tt>, for the sake of a cleaner implementation.
alterF' :: (Ord k, Functor f) => (Maybe a -> f a) -> k -> NEMap k a -> f (NEMap k a)

-- | <i>O(log n)</i>. Lookup the value at a key in the map.
--   
--   The function will return the corresponding value as <tt>(<a>Just</a>
--   value)</tt>, or <a>Nothing</a> if the key isn't in the map.
--   
--   An example of using <tt>lookup</tt>:
--   
--   <pre>
--   import Prelude hiding (lookup)
--   import Data.Map.NonEmpty
--   
--   employeeDept = fromList (("John","Sales") :| [("Bob","IT")])
--   deptCountry = fromList (("IT","USA") :| [("Sales","France")])
--   countryCurrency = fromList (("USA", "Dollar") :| [("France", "Euro")])
--   
--   employeeCurrency :: String -&gt; Maybe String
--   employeeCurrency name = do
--       dept &lt;- lookup name employeeDept
--       country &lt;- lookup dept deptCountry
--       lookup country countryCurrency
--   
--   main = do
--       putStrLn $ "John's currency: " ++ (show (employeeCurrency "John"))
--       putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete"))
--   </pre>
--   
--   The output of this program:
--   
--   <pre>
--   John's currency: Just "Euro"
--   Pete's currency: Nothing
--   </pre>
lookup :: Ord k => k -> NEMap k a -> Maybe a

-- | <i>O(log n)</i>. Find the value at a key. Returns <a>Nothing</a> when
--   the element can not be found.
--   
--   <pre>
--   fromList ((5, 'a') :| [(3, 'b')]) !? 1 == Nothing
--   </pre>
--   
--   <pre>
--   fromList ((5, 'a') :| [(3, 'b')]) !? 5 == Just 'a'
--   </pre>
(!?) :: Ord k => NEMap k a -> k -> Maybe a
infixl 9 !?

-- | <i>O(log n)</i>. Find the value at a key. Calls <a>error</a> when the
--   element can not be found.
--   
--   <pre>
--   fromList ((5,'a') :| [(3,'b')]) ! 1    Error: element not in the map
--   fromList ((5,'a') :| [(3,'b')]) ! 5 == 'a'
--   </pre>
(!) :: Ord k => NEMap k a -> k -> a
infixl 9 !

-- | <i>O(log n)</i>. The expression <tt>(<a>findWithDefault</a> def k
--   map)</tt> returns the value at key <tt>k</tt> or returns default value
--   <tt>def</tt> when the key is not in the map.
--   
--   <pre>
--   findWithDefault 'x' 1 (fromList ((5,'a') :| [(3,'b')])) == 'x'
--   findWithDefault 'x' 5 (fromList ((5,'a') :| [(3,'b')])) == 'a'
--   </pre>
findWithDefault :: Ord k => a -> k -> NEMap k a -> a

-- | <i>O(log n)</i>. Is the key a member of the map? See also
--   <a>notMember</a>.
--   
--   <pre>
--   member 5 (fromList ((5,'a') :| [(3,'b')])) == True
--   member 1 (fromList ((5,'a') :| [(3,'b')])) == False
--   </pre>
member :: Ord k => k -> NEMap k a -> Bool

-- | <i>O(log n)</i>. Is the key not a member of the map? See also
--   <a>member</a>.
--   
--   <pre>
--   notMember 5 (fromList ((5,'a') :| [(3,'b')])) == False
--   notMember 1 (fromList ((5,'a') :| [(3,'b')])) == True
--   </pre>
notMember :: Ord k => k -> NEMap k a -> Bool

-- | <i>O(log n)</i>. Find largest key smaller than the given one and
--   return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupLT 3 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   lookupLT 4 (fromList ((3,'a') :| [(5,'b')])) == Just (3, 'a')
--   </pre>
lookupLT :: Ord k => k -> NEMap k a -> Maybe (k, a)

-- | <i>O(log n)</i>. Find smallest key greater than the given one and
--   return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupGT 4 (fromList ((3,'a') :| [(5,'b')])) == Just (5, 'b')
--   lookupGT 5 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   </pre>
lookupGT :: Ord k => k -> NEMap k a -> Maybe (k, a)

-- | <i>O(log n)</i>. Find largest key smaller or equal to the given one
--   and return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupLE 2 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   lookupLE 4 (fromList ((3,'a') :| [(5,'b')])) == Just (3, 'a')
--   lookupLE 5 (fromList ((3,'a') :| [(5,'b')])) == Just (5, 'b')
--   </pre>
lookupLE :: Ord k => k -> NEMap k a -> Maybe (k, a)

-- | <i>O(log n)</i>. Find smallest key greater or equal to the given one
--   and return the corresponding (key, value) pair.
--   
--   <pre>
--   lookupGE 3 (fromList ((3,'a') :| [(5,'b')])) == Just (3, 'a')
--   lookupGE 4 (fromList ((3,'a') :| [(5,'b')])) == Just (5, 'b')
--   lookupGE 6 (fromList ((3,'a') :| [(5,'b')])) == Nothing
--   </pre>
lookupGE :: Ord k => k -> NEMap k a -> Maybe (k, a)

-- | Special property of non-empty maps: The type of non-empty maps over
--   uninhabited keys is itself uninhabited.
--   
--   This property also exists for <i>values</i> inside a non-empty
--   container (like for <a>NESet</a>, <tt>NESeq</tt>, and
--   <tt>NEIntMap</tt>); this can be witnessed using the function
--   <tt><a>absurd</a> . <tt>fold1</tt></tt>.
absurdNEMap :: NEMap Void a -> b

-- | <i>O(1)</i>. The number of elements in the map. Guaranteed to be
--   greater than zero.
--   
--   <pre>
--   size (singleton 1 'a')                          == 1
--   size (fromList ((1,'a') :| [(2,'c'), (3,'b')])) == 3
--   </pre>
size :: NEMap k a -> Int

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression (<tt><a>union</a>
--   t1 t2</tt>) takes the left-biased union of <tt>t1</tt> and
--   <tt>t2</tt>. It prefers <tt>t1</tt> when duplicate keys are
--   encountered, i.e. (<tt><a>union</a> == <a>unionWith</a>
--   <a>const</a></tt>).
--   
--   <pre>
--   union (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "a"), (7, "C")])
--   </pre>
union :: Ord k => NEMap k a -> NEMap k a -> NEMap k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Union with a combining function.
--   
--   <pre>
--   unionWith (++) (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "aA"), (7, "C")])
--   </pre>
unionWith :: Ord k => (a -> a -> a) -> NEMap k a -> NEMap k a -> NEMap k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Union with a combining function,
--   given the matching key.
--   
--   <pre>
--   let f key left_value right_value = (show key) ++ ":" ++ left_value ++ "|" ++ right_value
--   unionWithKey f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == fromList ((3, "b") :| [(5, "5:a|A"), (7, "C")])
--   </pre>
unionWithKey :: Ord k => (k -> a -> a -> a) -> NEMap k a -> NEMap k a -> NEMap k a

-- | The left-biased union of a non-empty list of maps.
--   
--   <pre>
--   unions (fromList ((5, "a") :| [(3, "b")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "A3") :| [(3, "B3")])])
--       == fromList [(3, "b"), (5, "a"), (7, "C")]
--   unions (fromList ((5, "A3") :| [(3, "B3")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "a") :| [(3, "b")])])
--       == fromList ((3, "B3") :| [(5, "A3"), (7, "C")])
--   </pre>
unions :: (Foldable1 f, Ord k) => f (NEMap k a) -> NEMap k a

-- | The union of a non-empty list of maps, with a combining operation:
--   (<tt><a>unionsWith</a> f == <a>foldl1</a> (<a>unionWith</a> f)</tt>).
--   
--   <pre>
--   unionsWith (++) (fromList ((5, "a") :| [(3, "b")]) :| [fromList ((5, "A") :| [(7, "C")]), fromList ((5, "A3") :| [(3, "B3")])])
--       == fromList ((3, "bB3") :| [(5, "aAA3"), (7, "C")])
--   </pre>
unionsWith :: (Foldable1 f, Ord k) => (a -> a -> a) -> f (NEMap k a) -> NEMap k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Difference of two maps. Return
--   elements of the first map not existing in the second map.
--   
--   Returns a potentially empty map (<a>Map</a>), in case the first map is
--   a subset of the second map.
--   
--   <pre>
--   difference (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.Map.singleton 3 "b"
--   </pre>
difference :: Ord k => NEMap k a -> NEMap k b -> Map k a

-- | Same as <a>difference</a>.
(\\) :: Ord k => NEMap k a -> NEMap k b -> Map k a

-- | <i>O(n+m)</i>. Difference with a combining function. When two equal
--   keys are encountered, the combining function is applied to the values
--   of these keys. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>Map</a>), in case the first map is
--   a subset of the second map and the function returns <a>Nothing</a> for
--   every pair.
--   
--   <pre>
--   let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing
--   differenceWith f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(3, "B"), (7, "C")]))
--       == Data.Map.singleton 3 "b:B"
--   </pre>
differenceWith :: Ord k => (a -> b -> Maybe a) -> NEMap k a -> NEMap k b -> Map k a

-- | <i>O(n+m)</i>. Difference with a combining function. When two equal
--   keys are encountered, the combining function is applied to the key and
--   both values. If it returns <a>Nothing</a>, the element is discarded
--   (proper set difference). If it returns (<tt><a>Just</a> y</tt>), the
--   element is updated with a new value <tt>y</tt>.
--   
--   Returns a potentially empty map (<a>Map</a>), in case the first map is
--   a subset of the second map and the function returns <a>Nothing</a> for
--   every pair.
--   
--   <pre>
--   let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing
--   differenceWithKey f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(3, "B"), (10, "C")]))
--       == Data.Map.singleton 3 "3:b|B"
--   </pre>
differenceWithKey :: Ord k => (k -> a -> b -> Maybe a) -> NEMap k a -> NEMap k b -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection of two maps. Return
--   data in the first map for the keys existing in both maps.
--   (<tt><a>intersection</a> m1 m2 == <a>intersectionWith</a> <a>const</a>
--   m1 m2</tt>).
--   
--   Returns a potentially empty map (<a>Map</a>), in case the two maps
--   share no keys in common.
--   
--   <pre>
--   intersection (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.Map.singleton 5 "a"
--   </pre>
intersection :: Ord k => NEMap k a -> NEMap k b -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection with a combining
--   function.
--   
--   Returns a potentially empty map (<a>Map</a>), in case the two maps
--   share no keys in common.
--   
--   <pre>
--   intersectionWith (++) (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.Map.singleton 5 "aA"
--   </pre>
intersectionWith :: Ord k => (a -> b -> c) -> NEMap k a -> NEMap k b -> Map k c

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Intersection with a combining
--   function.
--   
--   Returns a potentially empty map (<a>Map</a>), in case the two maps
--   share no keys in common.
--   
--   <pre>
--   let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar
--   intersectionWithKey f (fromList ((5, "a") :| [(3, "b")])) (fromList ((5, "A") :| [(7, "C")])) == Data.Map.singleton 5 "5:a|A"
--   </pre>
intersectionWithKey :: Ord k => (k -> a -> b -> c) -> NEMap k a -> NEMap k b -> Map k c

-- | <i>O(n)</i>. Map a function over all values in the map.
--   
--   <pre>
--   map (++ "x") (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "bx") :| [(5, "ax")])
--   </pre>
map :: (a -> b) -> NEMap k a -> NEMap k b

-- | <i>O(n)</i>. Map a function over all values in the map.
--   
--   <pre>
--   let f key x = (show key) ++ ":" ++ x
--   mapWithKey f (fromList ((5,"a") :| [(3,"b")])) == fromList ((3, "3:b") :| [(5, "5:a")])
--   </pre>
mapWithKey :: (k -> a -> b) -> NEMap k a -> NEMap k b

-- | <i>O(n)</i>. <tt><a>traverseWithKey1</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse1</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt>
--   
--   That is, behaves exactly like a regular <a>traverse1</a> except that
--   the traversing function also has access to the key associated with a
--   value.
--   
--   Is more general than <a>traverseWithKey</a>, since works with all
--   <a>Apply</a>, and not just <a>Applicative</a>.
traverseWithKey1 :: Apply t => (k -> a -> t b) -> NEMap k a -> t (NEMap k b)

-- | <i>O(n)</i>. <tt><a>traverseWithKey</a> f m == <a>fromList</a>
--   <a>$</a> <a>traverse</a> ((k, v) -&gt; (,) k <a>$</a> f k v)
--   (<a>toList</a> m)</tt> That is, behaves exactly like a regular
--   <a>traverse</a> except that the traversing function also has access to
--   the key associated with a value.
--   
--   <i>Use <a>traverseWithKey1</a></i> whenever possible (if your
--   <a>Applicative</a> also has <a>Apply</a> instance). This version is
--   provided only for types that do not have <a>Apply</a> instance, since
--   <a>Apply</a> is not at the moment (and might not ever be) an official
--   superclass of <a>Applicative</a>.
--   
--   <pre>
--   <a>traverseWithKey</a> f = <a>unwrapApplicative</a> . <a>traverseWithKey1</a> (\k -&gt; WrapApplicative . f k)
--   </pre>
traverseWithKey :: Applicative t => (k -> a -> t b) -> NEMap k a -> t (NEMap k b)

-- | <i>O(n)</i>. Traverse keys/values and collect the <a>Just</a> results.
--   
--   Returns a potentially empty map (<a>Map</a>), our function might
--   return <a>Nothing</a> on every item in the <a>NEMap</a>.
--   
--   Is more general than <a>traverseWithKey</a>, since works with all
--   <a>Apply</a>, and not just <a>Applicative</a>.
traverseMaybeWithKey1 :: Apply t => (k -> a -> t (Maybe b)) -> NEMap k a -> t (Map k b)

-- | <i>O(n)</i>. Traverse keys/values and collect the <a>Just</a> results.
--   
--   Returns a potentially empty map (<a>Map</a>), our function might
--   return <a>Nothing</a> on every item in the <a>NEMap</a>.
--   
--   <i>Use <a>traverseMaybeWithKey1</a></i> whenever possible (if your
--   <a>Applicative</a> also has <a>Apply</a> instance). This version is
--   provided only for types that do not have <a>Apply</a> instance, since
--   <a>Apply</a> is not at the moment (and might not ever be) an official
--   superclass of <a>Applicative</a>.
traverseMaybeWithKey :: Applicative t => (k -> a -> t (Maybe b)) -> NEMap k a -> t (Map k b)

-- | <i>O(n)</i>. The function <a>mapAccum</a> threads an accumulating
--   argument through the map in ascending order of keys.
--   
--   <pre>
--   let f a b = (a ++ b, b ++ "X")
--   mapAccum f "Everything: " (fromList ((5,"a") :| [(3,"b")])) == ("Everything: ba", fromList ((3, "bX") :| [(5, "aX")]))
--   </pre>
mapAccum :: (a -> b -> (a, c)) -> a -> NEMap k b -> (a, NEMap k c)

-- | <i>O(n)</i>. The function <a>mapAccumWithKey</a> threads an
--   accumulating argument through the map in ascending order of keys.
--   
--   <pre>
--   let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X")
--   mapAccumWithKey f "Everything:" (fromList ((5,"a") :| [(3,"b")])) == ("Everything: 3-b 5-a", fromList ((3, "bX") :| [(5, "aX")]))
--   </pre>
mapAccumWithKey :: (a -> k -> b -> (a, c)) -> a -> NEMap k b -> (a, NEMap k c)

-- | <i>O(n)</i>. The function <a>mapAccumRWithKey</a> threads an
--   accumulating argument through the map in descending order of keys.
mapAccumRWithKey :: (a -> k -> b -> (a, c)) -> a -> NEMap k b -> (a, NEMap k c)

-- | <i>O(n*log n)</i>. <tt><a>mapKeys</a> f s</tt> is the map obtained by
--   applying <tt>f</tt> to each key of <tt>s</tt>.
--   
--   The size of the result may be smaller if <tt>f</tt> maps two or more
--   distinct keys to the same new key. In this case the value at the
--   greatest of the original keys is retained.
--   
--   While the size of the result map may be smaller than the input map,
--   the output map is still guaranteed to be non-empty if the input map is
--   non-empty.
--   
--   <pre>
--   mapKeys (+ 1) (fromList ((5,"a") :| [(3,"b")]))                        == fromList ((4, "b") :| [(6, "a")])
--   mapKeys (\ _ -&gt; 1) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 1 "c"
--   mapKeys (\ _ -&gt; 3) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 3 "c"
--   </pre>
mapKeys :: Ord k2 => (k1 -> k2) -> NEMap k1 a -> NEMap k2 a

-- | <i>O(n*log n)</i>. <tt><a>mapKeysWith</a> c f s</tt> is the map
--   obtained by applying <tt>f</tt> to each key of <tt>s</tt>.
--   
--   The size of the result may be smaller if <tt>f</tt> maps two or more
--   distinct keys to the same new key. In this case the associated values
--   will be combined using <tt>c</tt>. The value at the greater of the two
--   original keys is used as the first argument to <tt>c</tt>.
--   
--   While the size of the result map may be smaller than the input map,
--   the output map is still guaranteed to be non-empty if the input map is
--   non-empty.
--   
--   <pre>
--   mapKeysWith (++) (\ _ -&gt; 1) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 1 "cdab"
--   mapKeysWith (++) (\ _ -&gt; 3) (fromList ((1,"b") :| [(2,"a"), (3,"d"), (4,"c")])) == singleton 3 "cdab"
--   </pre>
mapKeysWith :: Ord k2 => (a -> a -> a) -> (k1 -> k2) -> NEMap k1 a -> NEMap k2 a

-- | <i>O(n)</i>. <tt><a>mapKeysMonotonic</a> f s == <a>mapKeys</a> f
--   s</tt>, but works only when <tt>f</tt> is strictly monotonic. That is,
--   for any values <tt>x</tt> and <tt>y</tt>, if <tt>x</tt> &lt;
--   <tt>y</tt> then <tt>f x</tt> &lt; <tt>f y</tt>. <i>The precondition is
--   not checked.</i> Semi-formally, we have:
--   
--   <pre>
--   and [x &lt; y ==&gt; f x &lt; f y | x &lt;- ls, y &lt;- ls]
--                       ==&gt; mapKeysMonotonic f s == mapKeys f s
--       where ls = keys s
--   </pre>
--   
--   This means that <tt>f</tt> maps distinct original keys to distinct
--   resulting keys. This function has better performance than
--   <a>mapKeys</a>.
--   
--   While the size of the result map may be smaller than the input map,
--   the output map is still guaranteed to be non-empty if the input map is
--   non-empty.
--   
--   <pre>
--   mapKeysMonotonic (\ k -&gt; k * 2) (fromList ((5,"a") :| [(3,"b")])) == fromList ((6, "b") :| [(10, "a")])
--   valid (mapKeysMonotonic (\ k -&gt; k * 2) (fromList ((5,"a") :| [(3,"b")]))) == True
--   valid (mapKeysMonotonic (\ _ -&gt; 1)     (fromList ((5,"a") :| [(3,"b")]))) == False
--   </pre>
mapKeysMonotonic :: (k1 -> k2) -> NEMap k1 a -> NEMap k2 a

-- | <i>O(n)</i>. Fold the values in the map using the given
--   right-associative binary operator, such that <tt><a>foldr</a> f z ==
--   <a>foldr</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList map = foldr (:) [] map
--   </pre>
--   
--   <pre>
--   let f a len = len + (length a)
--   foldr f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldr :: (a -> b -> b) -> b -> NEMap k a -> b

-- | <i>O(n)</i>. Fold the values in the map using the given
--   left-associative binary operator, such that <tt><a>foldl</a> f z ==
--   <a>foldl</a> f z . <a>elems</a></tt>.
--   
--   <pre>
--   elemsList = reverse . foldl (flip (:)) []
--   </pre>
--   
--   <pre>
--   let f len a = len + (length a)
--   foldl f 0 (fromList ((5,"a") :| [(3,"bbb")])) == 4
--   </pre>
foldl :: (a -> b -> a) -> a -> NEMap k b -> a

-- | <i>O(n)</i>. A version of <a>foldr</a> that uses the value at the
--   maximal key in the map as the starting value.
--   
--   Note that, unlike <a>foldr1</a> for <a>Map</a>, this function is total
--   if the input function is total.
foldr1 :: (a -> a -> a) -> NEMap k a -> a

-- | <i>O(n)</i>. A version of <a>foldl</a> that uses the value at the
--   minimal key in the map as the starting value.
--   
--   Note that, unlike <a>foldl1</a> for <a>Map</a>, this function is total
--   if the input function is total.
foldl1 :: (a -> a -> a) -> NEMap k a -> a

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   right-associative binary operator, such that <tt><a>foldrWithKey</a> f
--   z == <a>foldr</a> (<a>uncurry</a> f) z . <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   keysList map = foldrWithKey (\k x ks -&gt; k:ks) [] map
--   </pre>
foldrWithKey :: (k -> a -> b -> b) -> b -> NEMap k a -> b

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   left-associative binary operator, such that <tt><a>foldlWithKey</a> f
--   z == <a>foldl</a> (\z' (kx, x) -&gt; f z' kx x) z .
--   <a>toAscList</a></tt>.
--   
--   For example,
--   
--   <pre>
--   keysList = reverse . foldlWithKey (\ks k x -&gt; k:ks) []
--   </pre>
foldlWithKey :: (a -> k -> b -> a) -> a -> NEMap k b -> a

-- | <i>O(n)</i>. Fold the keys and values in the map using the given
--   semigroup, such that
--   
--   <pre>
--   <a>foldMapWithKey</a> f = <a>fold1</a> . <a>mapWithKey</a> f
--   </pre>
--   
--   This can be an asymptotically faster than <a>foldrWithKey</a> or
--   <a>foldlWithKey</a> for some monoids.
foldMapWithKey :: Semigroup m => (k -> a -> m) -> NEMap k a -> m

-- | <i>O(n)</i>. A strict version of <a>foldr</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldr' :: (a -> b -> b) -> b -> NEMap k a -> b

-- | <i>O(n)</i>. A strict version of <a>foldr1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldr1' :: (a -> a -> a) -> NEMap k a -> a

-- | <i>O(n)</i>. A strict version of <a>foldl</a>. Each application of the
--   operator is evaluated before using the result in the next application.
--   This function is strict in the starting value.
foldl' :: (a -> b -> a) -> a -> NEMap k b -> a

-- | <i>O(n)</i>. A strict version of <a>foldl1</a>. Each application of
--   the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldl1' :: (a -> a -> a) -> NEMap k a -> a

-- | <i>O(n)</i>. A strict version of <a>foldrWithKey</a>. Each application
--   of the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldrWithKey' :: (k -> a -> b -> b) -> b -> NEMap k a -> b

-- | <i>O(n)</i>. A strict version of <a>foldlWithKey</a>. Each application
--   of the operator is evaluated before using the result in the next
--   application. This function is strict in the starting value.
foldlWithKey' :: (a -> k -> b -> a) -> a -> NEMap k b -> a

-- | <i>O(n)</i>. Return all elements of the map in the ascending order of
--   their keys.
--   
--   <pre>
--   elems (fromList ((5,"a") :| [(3,"b")])) == ("b" :| ["a"])
--   </pre>
elems :: NEMap k a -> NonEmpty a

-- | <i>O(n)</i>. Return all keys of the map in ascending order.
--   
--   <pre>
--   keys (fromList ((5,"a") :| [(3,"b")])) == (3 :| [5])
--   </pre>
keys :: NEMap k a -> NonEmpty k

-- | <i>O(n)</i>. An alias for <a>toAscList</a>. Return all key/value pairs
--   in the map in ascending key order.
--   
--   <pre>
--   assocs (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
assocs :: NEMap k a -> NonEmpty (k, a)

-- | <i>O(n)</i>. The non-empty set of all keys of the map.
--   
--   <pre>
--   keysSet (fromList ((5,"a") :| [(3,"b")])) == Data.Set.NonEmpty.fromList (3 :| [5])
--   </pre>
keysSet :: NEMap k a -> NESet k

-- | <i>O(n)</i>. Convert the map to a non-empty list of key/value pairs.
--   
--   <pre>
--   toList (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
toList :: NEMap k a -> NonEmpty (k, a)

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in ascending order.
--   
--   <pre>
--   toAscList (fromList ((5,"a") :| [(3,"b")])) == ((3,"b") :| [(5,"a")])
--   </pre>
toAscList :: NEMap k a -> NonEmpty (k, a)

-- | <i>O(n)</i>. Convert the map to a list of key/value pairs where the
--   keys are in descending order.
--   
--   <pre>
--   toDescList (fromList ((5,"a") :| [(3,"b")])) == ((5,"a") :| [(3,"b")])
--   </pre>
toDescList :: NEMap k a -> NonEmpty (k, a)

-- | <i>O(n)</i>. Filter all values that satisfy the predicate.
--   
--   Returns a potentially empty map (<a>Map</a>), because we could
--   potentailly filter out all items in the original <a>NEMap</a>.
--   
--   <pre>
--   filter (&gt; "a") (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "b"
--   filter (&gt; "x") (fromList ((5,"a") :| [(3,"b")])) == Data.Map.empty
--   filter (&lt; "a") (fromList ((5,"a") :| [(3,"b")])) == Data.Map.empty
--   </pre>
filter :: (a -> Bool) -> NEMap k a -> Map k a

-- | <i>O(n)</i>. Filter all keys/values that satisfy the predicate.
--   
--   Returns a potentially empty map (<a>Map</a>), because we could
--   potentailly filter out all items in the original <a>NEMap</a>.
--   
--   <pre>
--   filterWithKey (\k _ -&gt; k &gt; 4) (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   </pre>
filterWithKey :: (k -> a -> Bool) -> NEMap k a -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Restrict an <a>NEMap</a> to only
--   those keys found in a <a>Set</a>.
--   
--   <pre>
--   m `restrictKeys` s = <a>filterWithKey</a> (k _ -&gt; k <a>`member`</a> s) m
--   m `restrictKeys` s = m <a>`intersection`</a> <a>fromSet</a> (const ()) s
--   </pre>
restrictKeys :: Ord k => NEMap k a -> Set k -> Map k a

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Remove all keys in a <a>Set</a>
--   from an <a>NEMap</a>.
--   
--   <pre>
--   m `withoutKeys` s = <a>filterWithKey</a> (k _ -&gt; k <a>`notMember`</a> s) m
--   m `withoutKeys` s = m <a>`difference`</a> <a>fromSet</a> (const ()) s
--   </pre>
withoutKeys :: Ord k => NEMap k a -> Set k -> Map k a

-- | <i>O(n)</i>. Partition the map according to a predicate.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate was true for all
--   items.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate was false for all
--   items.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (all of the items
--   that were true for the predicate) and <tt>n2</tt> (all of the items
--   that were false for the predicate).</li>
--   </ul>
--   
--   See also <a>split</a>.
--   
--   <pre>
--   partition (&gt; "a") (fromList ((5,"a") :| [(3,"b")])) == These (singleton 3 "b") (singleton 5 "a")
--   partition (&lt; "x") (fromList ((5,"a") :| [(3,"b")])) == This  (fromList ((3, "b") :| [(5, "a")]))
--   partition (&gt; "x") (fromList ((5,"a") :| [(3,"b")])) == That  (fromList ((3, "b") :| [(5, "a")]))
--   </pre>
partition :: (a -> Bool) -> NEMap k a -> These (NEMap k a) (NEMap k a)

-- | <i>O(n)</i>. Partition the map according to a predicate.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate was true for all
--   items, returning the original map.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate was false for all
--   items, returning the original map.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (all of the items
--   that were true for the predicate) and <tt>n2</tt> (all of the items
--   that were false for the predicate).</li>
--   </ul>
--   
--   See also <a>split</a>.
--   
--   <pre>
--   partitionWithKey (\ k _ -&gt; k &gt; 3) (fromList ((5,"a") :| [(3,"b")])) == These (singleton 5 "a") (singleton 3 "b")
--   partitionWithKey (\ k _ -&gt; k &lt; 7) (fromList ((5,"a") :| [(3,"b")])) == This  (fromList ((3, "b") :| [(5, "a")]))
--   partitionWithKey (\ k _ -&gt; k &gt; 7) (fromList ((5,"a") :| [(3,"b")])) == That  (fromList ((3, "b") :| [(5, "a")]))
--   </pre>
partitionWithKey :: (k -> a -> Bool) -> NEMap k a -> These (NEMap k a) (NEMap k a)

-- | <i>O(log n)</i>. Take while a predicate on the keys holds. The user is
--   responsible for ensuring that for all keys <tt>j</tt> and <tt>k</tt>
--   in the map, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See note at
--   <a>spanAntitone</a>.
--   
--   Returns a potentially empty map (<a>Map</a>), because the predicate
--   might fail on the first input.
--   
--   <pre>
--   takeWhileAntitone p = Data.Map.fromDistinctAscList . Data.List.takeWhile (p . fst) . Data.Foldable.toList
--   takeWhileAntitone p = <a>filterWithKey</a> (k _ -&gt; p k)
--   </pre>
takeWhileAntitone :: (k -> Bool) -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Drop while a predicate on the keys holds. The user is
--   responsible for ensuring that for all keys <tt>j</tt> and <tt>k</tt>
--   in the map, <tt>j &lt; k ==&gt; p j &gt;= p k</tt>. See note at
--   <a>spanAntitone</a>.
--   
--   <pre>
--   dropWhileAntitone p = Data.Map.fromDistinctAscList . Data.List.dropWhile (p . fst) . Data.Foldable.toList
--   dropWhileAntitone p = <a>filterWithKey</a> (k -&gt; not (p k))
--   </pre>
dropWhileAntitone :: (k -> Bool) -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Divide a map at the point where a predicate on the
--   keys stops holding. The user is responsible for ensuring that for all
--   keys <tt>j</tt> and <tt>k</tt> in the map, <tt>j &lt; k ==&gt; p j
--   &gt;= p k</tt>.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the predicate never failed for
--   any item, returning the original map.</li>
--   <li><tt><a>That</a> n2</tt> means that the predicate failed for the
--   first item, returning the original map.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (the map up to the
--   point where the predicate on the keys stops holding) and <tt>n2</tt>
--   (the map starting from the point where the predicate stops
--   holding)</li>
--   </ul>
--   
--   <pre>
--   spanAntitone p xs = partitionWithKey (k _ -&gt; p k) xs
--   </pre>
--   
--   Note: if <tt>p</tt> is not actually antitone, then
--   <tt>spanAntitone</tt> will split the map at some <i>unspecified</i>
--   point where the predicate switches from holding to not holding (where
--   the predicate is seen to hold before the first key and to fail after
--   the last key).
spanAntitone :: (k -> Bool) -> NEMap k a -> These (NEMap k a) (NEMap k a)

-- | <i>O(n)</i>. Map values and collect the <a>Just</a> results.
--   
--   Returns a potentially empty map (<a>Map</a>), because the function
--   could potentially return <a>Nothing</a> on all items in the
--   <a>NEMap</a>.
--   
--   <pre>
--   let f x = if x == "a" then Just "new a" else Nothing
--   mapMaybe f (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "new a"
--   </pre>
mapMaybe :: (a -> Maybe b) -> NEMap k a -> Map k b

-- | <i>O(n)</i>. Map keys/values and collect the <a>Just</a> results.
--   
--   Returns a potentially empty map (<a>Map</a>), because the function
--   could potentially return <a>Nothing</a> on all items in the
--   <a>NEMap</a>.
--   
--   <pre>
--   let f k _ = if k &lt; 5 then Just ("key : " ++ (show k)) else Nothing
--   mapMaybeWithKey f (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "key : 3"
--   </pre>
mapMaybeWithKey :: (k -> a -> Maybe b) -> NEMap k a -> Map k b

-- | <i>O(n)</i>. Map values and separate the <a>Left</a> and <a>Right</a>
--   results.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the results were all
--   <a>Left</a>.</li>
--   <li><tt><a>That</a> n2</tt> means that the results were all
--   <a>Right</a>.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (the map where the
--   results were <a>Left</a>) and <tt>n2</tt> (the map where the results
--   were <a>Right</a>)</li>
--   </ul>
--   
--   <pre>
--   let f a = if a &lt; "c" then Left a else Right a
--   mapEither f (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == These (fromList ((3,"b") :| [(5,"a")])) (fromList ((1,"x") :| [(7,"z")]))
--   
--   mapEither (\ a -&gt; Right a) (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == That (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--   </pre>
mapEither :: (a -> Either b c) -> NEMap k a -> These (NEMap k b) (NEMap k c)

-- | <i>O(n)</i>. Map keys/values and separate the <a>Left</a> and
--   <a>Right</a> results.
--   
--   Returns a <a>These</a> with potentially two non-empty maps:
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that the results were all
--   <a>Left</a>.</li>
--   <li><tt><a>That</a> n2</tt> means that the results were all
--   <a>Right</a>.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (the map where the
--   results were <a>Left</a>) and <tt>n2</tt> (the map where the results
--   were <a>Right</a>)</li>
--   </ul>
--   
--   <pre>
--   let f k a = if k &lt; 5 then Left (k * 2) else Right (a ++ a)
--   mapEitherWithKey f (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == These (fromList ((1,2) :| [(3,6)])) (fromList ((5,"aa") :| [(7,"zz")]))
--   
--   mapEitherWithKey (\_ a -&gt; Right a) (fromList ((5,"a") :| [(3,"b"), (1,"x"), (7,"z")]))
--       == That (fromList ((1,"x") :| [(3,"b"), (5,"a"), (7,"z")]))
--   </pre>
mapEitherWithKey :: (k -> a -> Either b c) -> NEMap k a -> These (NEMap k b) (NEMap k c)

-- | <i>O(log n)</i>. The expression (<tt><a>split</a> k map</tt>) is
--   potentially a <a>These</a> containing up to two <a>NEMap</a>s based on
--   splitting the map into maps containing items before and after the
--   given key <tt>k</tt>. It will never return a map that contains
--   <tt>k</tt> itself.
--   
--   <ul>
--   <li><a>Nothing</a> means that <tt>k</tt> was the only key in the the
--   original map, and so there are no items before or after it.</li>
--   <li><tt><a>Just</a> (<a>This</a> n1)</tt> means <tt>k</tt> was larger
--   than or equal to all items in the map, and <tt>n1</tt> is the entire
--   original map (minus <tt>k</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>That</a> n2)</tt> means <tt>k</tt> was smaller
--   than or equal to all items in the map, and <tt>n2</tt> is the entire
--   original map (minus <tt>k</tt>, if it was present)</li>
--   <li><tt><a>Just</a> (<a>These</a> n1 n2)</tt> gives <tt>n1</tt> (the
--   map of all keys from the original map less than <tt>k</tt>) and
--   <tt>n2</tt> (the map of all keys from the original map greater than
--   <tt>k</tt>)</li>
--   </ul>
--   
--   <pre>
--   split 2 (fromList ((5,"a") :| [(3,"b")])) == Just (That  (fromList ((3,"b") :| [(5,"a")]))  )
--   split 3 (fromList ((5,"a") :| [(3,"b")])) == Just (That  (singleton 5 "a")                  )
--   split 4 (fromList ((5,"a") :| [(3,"b")])) == Just (These (singleton 3 "b") (singleton 5 "a"))
--   split 5 (fromList ((5,"a") :| [(3,"b")])) == Just (This  (singleton 3 "b")                  )
--   split 6 (fromList ((5,"a") :| [(3,"b")])) == Just (This  (fromList ((3,"b") :| [(5,"a")]))  )
--   split 5 (singleton 5 "a")                 == Nothing
--   </pre>
split :: Ord k => k -> NEMap k a -> Maybe (These (NEMap k a) (NEMap k a))

-- | <i>O(log n)</i>. The expression (<tt><a>splitLookup</a> k map</tt>)
--   splits a map just like <a>split</a> but also returns <tt><a>lookup</a>
--   k map</tt>, as the first field in the <a>These</a>:
--   
--   <pre>
--   splitLookup 2 (fromList ((5,"a") :| [(3,"b")])) == That      (That  (fromList ((3,"b") :| [(5,"a")])))
--   splitLookup 3 (fromList ((5,"a") :| [(3,"b")])) == These "b" (That  (singleton 5 "a"))
--   splitLookup 4 (fromList ((5,"a") :| [(3,"b")])) == That      (These (singleton 3 "b") (singleton 5 "a"))
--   splitLookup 5 (fromList ((5,"a") :| [(3,"b")])) == These "a" (This  (singleton 3 "b"))
--   splitLookup 6 (fromList ((5,"a") :| [(3,"b")])) == That      (This  (fromList ((3,"b") :| [(5,"a")])))
--   splitLookup 5 (singleton 5 "a")                 == This  "a"
--   </pre>
splitLookup :: Ord k => k -> NEMap k a -> These a (These (NEMap k a) (NEMap k a))

-- | <i>O(1)</i>. Decompose a map into pieces based on the structure of the
--   underlying tree. This function is useful for consuming a map in
--   parallel.
--   
--   No guarantee is made as to the sizes of the pieces; an internal, but
--   deterministic process determines this. However, it is guaranteed that
--   the pieces returned will be in ascending order (all elements in the
--   first submap less than all elements in the second, and so on).
--   
--   Note that the current implementation does not return more than four
--   submaps, but you should not depend on this behaviour because it can
--   change in the future without notice.
splitRoot :: NEMap k a -> NonEmpty (NEMap k a)

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. This function is defined as
--   (<tt><a>isSubmapOf</a> = <a>isSubmapOfBy</a> (==)</tt>).
isSubmapOf :: (Ord k, Eq a) => NEMap k a -> NEMap k a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. The expression
--   (<tt><a>isSubmapOfBy</a> f t1 t2</tt>) returns <a>True</a> if all keys
--   in <tt>t1</tt> are in tree <tt>t2</tt>, and when <tt>f</tt> returns
--   <a>True</a> when applied to their respective values. For example, the
--   following expressions are all <a>True</a>:
--   
--   <pre>
--   isSubmapOfBy (==) (singleton 'a' 1) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (&lt;=) (singleton 'a' 1) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (==) (fromList (('a',1) :| [('b',2)])) (fromList (('a',1) :| [('b',2)]))
--   </pre>
--   
--   But the following are all <a>False</a>:
--   
--   <pre>
--   isSubmapOfBy (==) (singleton 'a' 2) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (&lt;)  (singleton 'a' 1) (fromList (('a',1) :| [('b',2)]))
--   isSubmapOfBy (==) (fromList (('a',1) :| [('b',2)])) (singleton 'a' 1)
--   </pre>
isSubmapOfBy :: Ord k => (a -> b -> Bool) -> NEMap k a -> NEMap k b -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Is this a proper submap? (ie. a
--   submap but not equal). Defined as (<tt><a>isProperSubmapOf</a> =
--   <a>isProperSubmapOfBy</a> (==)</tt>).
isProperSubmapOf :: (Ord k, Eq a) => NEMap k a -> NEMap k a -> Bool

-- | <i>O(m*log(n/m + 1)), m &lt;= n</i>. Is this a proper submap? (ie. a
--   submap but not equal). The expression (<tt><a>isProperSubmapOfBy</a> f
--   m1 m2</tt>) returns <a>True</a> when <tt>m1</tt> and <tt>m2</tt> are
--   not equal, all keys in <tt>m1</tt> are in <tt>m2</tt>, and when
--   <tt>f</tt> returns <a>True</a> when applied to their respective
--   values. For example, the following expressions are all <a>True</a>:
--   
--   <pre>
--   isProperSubmapOfBy (==) (singleton 1 1) (fromList ((1,1) :| [(2,2)]))
--   isProperSubmapOfBy (&lt;=) (singleton 1 1) (fromList ((1,1) :| [(2,2)]))
--   </pre>
--   
--   But the following are all <a>False</a>:
--   
--   <pre>
--   isProperSubmapOfBy (==) (fromList ((1,1) :| [(2,2)])) (fromList ((1,1) :| [(2,2)]))
--   isProperSubmapOfBy (==) (fromList ((1,1) :| [(2,2)])) (singleton 1 1))
--   isProperSubmapOfBy (&lt;)  (singleton 1 1)               (fromList ((1,1) :| [(2,2)]))
--   </pre>
isProperSubmapOfBy :: Ord k => (a -> b -> Bool) -> NEMap k a -> NEMap k b -> Bool

-- | <i>O(log n)</i>. Lookup the <i>index</i> of a key, which is its
--   zero-based index in the sequence sorted by keys. The index is a number
--   from <i>0</i> up to, but not including, the <a>size</a> of the map.
--   
--   <pre>
--   isJust (lookupIndex 2 (fromList ((5,"a") :| [(3,"b")])))   == False
--   fromJust (lookupIndex 3 (fromList ((5,"a") :| [(3,"b")]))) == 0
--   fromJust (lookupIndex 5 (fromList ((5,"a") :| [(3,"b")]))) == 1
--   isJust (lookupIndex 6 (fromList ((5,"a") :| [(3,"b")])))   == False
--   </pre>
lookupIndex :: Ord k => k -> NEMap k a -> Maybe Int

-- | <i>O(log n)</i>. Return the <i>index</i> of a key, which is its
--   zero-based index in the sequence sorted by keys. The index is a number
--   from <i>0</i> up to, but not including, the <a>size</a> of the map.
--   Calls <a>error</a> when the key is not a <a>member</a> of the map.
--   
--   <pre>
--   findIndex 2 (fromList ((5,"a") :| [(3,"b")]))    Error: element is not in the map
--   findIndex 3 (fromList ((5,"a") :| [(3,"b")])) == 0
--   findIndex 5 (fromList ((5,"a") :| [(3,"b")])) == 1
--   findIndex 6 (fromList ((5,"a") :| [(3,"b")]))    Error: element is not in the map
--   </pre>
findIndex :: Ord k => k -> NEMap k a -> Int

-- | <i>O(log n)</i>. Retrieve an element by its <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   <pre>
--   elemAt 0 (fromList ((5,"a") :| [(3,"b")])) == (3,"b")
--   elemAt 1 (fromList ((5,"a") :| [(3,"b")])) == (5, "a")
--   elemAt 2 (fromList ((5,"a") :| [(3,"b")]))    Error: index out of range
--   </pre>
elemAt :: Int -> NEMap k a -> (k, a)

-- | <i>O(log n)</i>. Update the element at <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   Returns a possibly empty map (<a>Map</a>), because the function might
--   end up deleting the last key in the map. See <a>adjustAt</a> for a
--   version that disallows deletion, guaranteeing that the result is also
--   a non-empty Map.
--   
--   <pre>
--   updateAt (\ _ _ -&gt; Just "x") 0    (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "x"), (5, "a")]
--   updateAt (\ _ _ -&gt; Just "x") 1    (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "x")]
--   updateAt (\ _ _ -&gt; Just "x") 2    (fromList ((5,"a") :| [(3,"b")]))    Error: index out of range
--   updateAt (\ _ _ -&gt; Just "x") (-1) (fromList ((5,"a") :| [(3,"b")]))    Error: index out of range
--   updateAt (\_ _  -&gt; Nothing)  0    (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   updateAt (\_ _  -&gt; Nothing)  1    (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "b"
--   updateAt (\_ _  -&gt; Nothing)  2    (fromList ((5,"a") :| [(3,"b")]))    Error: index out of range
--   updateAt (\_ _  -&gt; Nothing)  (-1) (fromList ((5,"a") :| [(3,"b")]))    Error: index out of range
--   </pre>
updateAt :: (k -> a -> Maybe a) -> Int -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Variant of <a>updateAt</a> that disallows deletion.
--   Allows us to guarantee that the result is also a non-empty Map.
adjustAt :: (k -> a -> a) -> Int -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. Delete the element at <i>index</i>, i.e. by its
--   zero-based index in the sequence sorted by keys. If the <i>index</i>
--   is out of range (less than zero, greater or equal to <a>size</a> of
--   the map), <a>error</a> is called.
--   
--   Returns a potentially empty map (<a>Map</a>) because of the
--   possibility of deleting the last item in a map.
--   
--   <pre>
--   deleteAt 0  (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   deleteAt 1  (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "b"
--   deleteAt 2 (fromList ((5,"a") :| [(3,"b")]))     Error: index out of range
--   deleteAt (-1) (fromList ((5,"a") :| [(3,"b")]))  Error: index out of range
--   </pre>
deleteAt :: Int -> NEMap k a -> Map k a

-- | Take a given number of entries in key order, beginning with the
--   smallest keys.
--   
--   Returns a possibly empty map (<a>Map</a>), which can only happen if we
--   call <tt>take 0</tt>.
--   
--   <pre>
--   take n = Data.Map.fromDistinctAscList . Data.List.NonEmpty.take n . <a>toList</a>
--   </pre>
take :: Int -> NEMap k a -> Map k a

-- | Drop a given number of entries in key order, beginning with the
--   smallest keys.
--   
--   Returns a possibly empty map (<a>Map</a>), in case we drop all of the
--   elements (which can happen if we drop a number greater than or equal
--   to the number of items in the map)
--   
--   <pre>
--   drop n = Data.Map.fromDistinctAscList . Data.List.NonEmpty.drop' n . <a>toList</a>
--   </pre>
drop :: Int -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Split a map at a particular index <tt>i</tt>.
--   
--   <ul>
--   <li><tt><a>This</a> n1</tt> means that there are less than <tt>i</tt>
--   items in the map, and <tt>n1</tt> is the original map.</li>
--   <li><tt><a>That</a> n2</tt> means <tt>i</tt> was 0; we dropped 0
--   items, so <tt>n2</tt> is the original map.</li>
--   <li><tt><a>These</a> n1 n2</tt> gives <tt>n1</tt> (taking <tt>i</tt>
--   items from the original map) and <tt>n2</tt> (dropping <tt>i</tt>
--   items from the original map))</li>
--   </ul>
splitAt :: Int -> NEMap k a -> These (NEMap k a) (NEMap k a)

-- | <i>O(1)</i>. The minimal key of the map. Note that this is total,
--   making <a>lookupMin</a> obsolete. It is constant-time, so has better
--   asymptotics than <tt>Data.Map.lookupMin</tt> and
--   <tt>Data.Map.findMin</tt>, as well.
--   
--   <pre>
--   findMin (fromList ((5,"a") :| [(3,"b")])) == (3,"b")
--   </pre>
findMin :: NEMap k a -> (k, a)

-- | <i>O(log n)</i>. The maximal key of the map. Note that this is total,
--   making <a>lookupMin</a> obsolete.
--   
--   <pre>
--   findMax (fromList ((5,"a") :| [(3,"b")])) == (5,"a")
--   </pre>
findMax :: NEMap k a -> (k, a)

-- | <i>O(1)</i>. Delete the minimal key. Returns a potentially empty map
--   (<a>Map</a>), because we might end up deleting the final key in a
--   singleton map. It is constant-time, so has better asymptotics than
--   <a>deleteMin</a>.
--   
--   <pre>
--   deleteMin (fromList ((5,"a") :| [(3,"b"), (7,"c")])) == Data.Map.fromList [(5,"a"), (7,"c")]
--   deleteMin (singleton 5 "a") == Data.Map.empty
--   </pre>
deleteMin :: NEMap k a -> Map k a

-- | <i>O(log n)</i>. Delete the maximal key. Returns a potentially empty
--   map (<a>Map</a>), because we might end up deleting the final key in a
--   singleton map.
--   
--   <pre>
--   deleteMax (fromList ((5,"a") :| [(3,"b"), (7,"c")])) == Data.Map.fromList [(3,"b"), (5,"a")]
--   deleteMax (singleton 5 "a") == Data.Map.empty
--   </pre>
deleteMax :: NEMap k a -> Map k a

-- | <i>O(1)</i>. Delete and find the minimal key-value pair. It is
--   constant-time, so has better asymptotics that
--   <tt>Data.Map.minView</tt> for <a>Map</a>.
--   
--   Note that unlike <tt>Data.Map.deleteFindMin</tt> for <a>Map</a>, this
--   cannot ever fail, and so is a total function. However, the result
--   <a>Map</a> is potentially empty, since the original map might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMin (fromList ((5,"a") :| [(3,"b"), (10,"c")])) == ((3,"b"), Data.Map.fromList [(5,"a"), (10,"c")])
--   </pre>
deleteFindMin :: NEMap k a -> ((k, a), Map k a)

-- | <i>O(log n)</i>. Delete and find the minimal key-value pair.
--   
--   Note that unlike <tt>Data.Map.deleteFindMax</tt> for <a>Map</a>, this
--   cannot ever fail, and so is a total function. However, the result
--   <a>Map</a> is potentially empty, since the original map might have
--   contained just a single item.
--   
--   <pre>
--   deleteFindMax (fromList ((5,"a") :| [(3,"b"), (10,"c")])) == ((10,"c"), Data.Map.fromList [(3,"b"), (5,"a")])
--   </pre>
deleteFindMax :: NEMap k a -> ((k, a), Map k a)

-- | <i>O(1)</i> if delete, <i>O(log n)</i> otherwise. Update the value at
--   the minimal key. Returns a potentially empty map (<a>Map</a>), because
--   we might end up deleting the final key in the map if the function
--   returns <a>Nothing</a>. See <a>adjustMin</a> for a version that can
--   guaruntee that we return a non-empty map.
--   
--   <pre>
--   updateMin (\ a -&gt; Just ("X" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "Xb"), (5, "a")]
--   updateMin (\ _ -&gt; Nothing)         (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   </pre>
updateMin :: (a -> Maybe a) -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Update the value at the maximal key. Returns a
--   potentially empty map (<a>Map</a>), because we might end up deleting
--   the final key in the map if the function returns <a>Nothing</a>. See
--   <a>adjustMax</a> for a version that can guarantee that we return a
--   non-empty map.
--   
--   <pre>
--   updateMax (\ a -&gt; Just ("X" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3, "b"), (5, "Xa")]
--   updateMax (\ _ -&gt; Nothing)         (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 3 "b"
--   </pre>
updateMax :: (a -> Maybe a) -> NEMap k a -> Map k a

-- | <i>O(1)</i>. A version of <a>updateMin</a> that disallows deletion,
--   allowing us to guarantee that the result is also non-empty.
adjustMin :: (a -> a) -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. A version of <a>updateMax</a> that disallows
--   deletion, allowing us to guarantee that the result is also non-empty.
adjustMax :: (a -> a) -> NEMap k a -> NEMap k a

-- | <i>O(1)</i> if delete, <i>O(log n)</i> otherwise. Update the value at
--   the minimal key. Returns a potentially empty map (<a>Map</a>), because
--   we might end up deleting the final key in the map if the function
--   returns <a>Nothing</a>. See <a>adjustMinWithKey</a> for a version that
--   guaruntees a non-empty map.
--   
--   <pre>
--   updateMinWithKey (\ k a -&gt; Just ((show k) ++ ":" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3,"3:b"), (5,"a")]
--   updateMinWithKey (\ _ _ -&gt; Nothing)                     (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   </pre>
updateMinWithKey :: (k -> a -> Maybe a) -> NEMap k a -> Map k a

-- | <i>O(log n)</i>. Update the value at the maximal key. Returns a
--   potentially empty map (<a>Map</a>), because we might end up deleting
--   the final key in the map if the function returns <a>Nothing</a>. See
--   <a>adjustMaxWithKey</a> for a version that guaruntees a non-empty map.
--   
--   <pre>
--   updateMinWithKey (\ k a -&gt; Just ((show k) ++ ":" ++ a)) (fromList ((5,"a") :| [(3,"b")])) == Data.Map.fromList [(3,"3:b"), (5,"a")]
--   updateMinWithKey (\ _ _ -&gt; Nothing)                     (fromList ((5,"a") :| [(3,"b")])) == Data.Map.singleton 5 "a"
--   </pre>
updateMaxWithKey :: (k -> a -> Maybe a) -> NEMap k a -> Map k a

-- | <i>O(1)</i>. A version of <a>adjustMaxWithKey</a> that disallows
--   deletion, allowing us to guarantee that the result is also non-empty.
--   Note that it also is able to have better asymptotics than
--   <a>updateMinWithKey</a> in general.
adjustMinWithKey :: (k -> a -> a) -> NEMap k a -> NEMap k a

-- | <i>O(log n)</i>. A version of <a>updateMaxWithKey</a> that disallows
--   deletion, allowing us to guarantee that the result is also non-empty.
adjustMaxWithKey :: (k -> a -> a) -> NEMap k a -> NEMap k a

-- | <i>O(1)</i>. Retrieves the value associated with minimal key of the
--   map, and the map stripped of that element. It is constant-time, so has
--   better asymptotics than <tt>Data.Map.minView</tt> for <a>Map</a>.
--   
--   Note that unlike <tt>Data.Map.minView</tt> for <a>Map</a>, this cannot
--   ever fail, so doesn't need to return in a <a>Maybe</a>. However, the
--   result <a>Map</a> is potentially empty, since the original map might
--   have contained just a single item.
--   
--   <pre>
--   minView (fromList ((5,"a") :| [(3,"b")])) == ("b", Data.Map.singleton 5 "a")
--   </pre>
minView :: NEMap k a -> (a, Map k a)

-- | <i>O(log n)</i>. Retrieves the value associated with maximal key of
--   the map, and the map stripped of that element.
--   
--   Note that unlike <tt>Data.Map.maxView</tt> from <a>Map</a>, this
--   cannot ever fail, so doesn't need to return in a <a>Maybe</a>.
--   However, the result <a>Map</a> is potentially empty, since the
--   original map might have contained just a single item.
--   
--   <pre>
--   maxView (fromList ((5,"a") :| [(3,"b")])) == ("a", Data.Map.singleton 3 "b")
--   </pre>
maxView :: NEMap k a -> (a, Map k a)

-- | <i>O(n)</i>. Test if the internal map structure is valid.
valid :: Ord k => NEMap k a -> Bool


-- | <h1>Non-Empty Typeclass</h1>
--   
--   Provides the typeclass <a>HasNonEmpty</a>, which abstracts over
--   different types which have a "non-empty" variant.
--   
--   Used to convert between and in between possibly-empty and non-empty
--   types. Instances are provided for all modules in this package, as well
--   as for <a>NonEmpty</a> in <i>base</i> and <a>NonEmptyVector</a>.
module Data.Containers.NonEmpty

-- | If <tt>s</tt> is an instance of <tt>HasNonEmpty</tt>, it means that
--   there is a corresponding "non-empty" version of <tt>s</tt>,
--   <tt><a>NE</a> s</tt>.
--   
--   In order for things to be well-behaved, we expect that <a>nonEmpty</a>
--   and <tt>maybe <a>empty</a> <a>fromNonEmpty</a></tt> should form an
--   isomorphism (or that <tt><a>withNonEmpty</a> <a>empty</a>
--   <a>fromNonEmpty</a> == id</tt>. In addition, the following properties
--   should hold for most exectations:
--   
--   <ul>
--   <li><pre>(x == empty) ==&gt; isEmpty x</pre></li>
--   <li><pre>(x == empty) ==&gt; isNothing (nonEmpty x)</pre></li>
--   <li><pre>isEmpty x ==&gt; isNothing (nonEmpty x)</pre></li>
--   <li><pre>unsafeToNonEmpty x == fromJust (nonEmpty x)</pre></li>
--   <li>Usually, <tt>not (isEmpty x) ==&gt; isJust (nonEmpty x)</tt>, but
--   this isn't necessary.</li>
--   </ul>
class HasNonEmpty s where {
    
    -- | <tt><a>NE</a> s</tt> is the "non-empty" version of <tt>s</tt>.
    type family NE s = t | t -> s;
}

-- | "Smart constructor" for <tt><a>NE</a> s</tt> given a (potentailly
--   empty) <tt>s</tt>. Will return <a>Nothing</a> if the <tt>s</tt> was
--   empty, and <tt><a>Just</a> n</tt> if the <tt>s</tt> was not empty,
--   with <tt>n :: <a>NE</a> s</tt>.
--   
--   Should form an isomorphism with <tt><a>maybe</a> <a>empty</a>
--   <a>fromNonEmpty</a></tt>.
nonEmpty :: HasNonEmpty s => s -> Maybe (NE s)

-- | Convert a <tt><a>NE</a> s</tt> (non-empty <tt>s</tt>) back into an
--   <tt>s</tt>, "obscuring" its non-emptiness from its type.
fromNonEmpty :: HasNonEmpty s => NE s -> s

-- | Continuation-based version of <a>nonEmpty</a>, which can be more
--   efficient in certain situations.
--   
--   <tt><a>withNonEmpty</a> <a>empty</a> <a>fromNonEmpty</a></tt> should
--   be <tt>id</tt>.
withNonEmpty :: HasNonEmpty s => r -> (NE s -> r) -> s -> r

-- | An empty <tt>s</tt>.
empty :: HasNonEmpty s => s

-- | Check if an <tt>s</tt> is empty.
isEmpty :: HasNonEmpty s => s -> Bool

-- | Unsafely coerce an <tt>s</tt> into an <tt><a>NE</a> s</tt> (non-empty
--   <tt>s</tt>). Is undefined (throws a runtime exception when evaluation
--   is attempted) when the <tt>s</tt> is empty.
unsafeToNonEmpty :: HasNonEmpty s => s -> NE s

-- | The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow you to treat a
--   <tt>s</tt> as if it were either a <tt><a>IsNonEmpty</a> n</tt> (where
--   <tt>n</tt> is a non-empty version of <tt>s</tt>, type <tt><a>NE</a>
--   s</tt>) or an <a>IsEmpty</a>.
--   
--   For example, you can pattern match on a list to get a <a>NonEmpty</a>
--   (non-empty list):
--   
--   <pre>
--   safeHead :: [Int] -&gt; Int
--   safeHead (<a>IsNonEmpty</a> (x :| _)) = x     -- here, the list was not empty
--   safehead <a>IsEmpty</a>               = 0     -- here, the list was empty
--   </pre>
--   
--   Matching on <tt><a>IsNonEmpty</a> n</tt> means that the original input
--   was <i>not</i> empty, and you have a verified-non-empty <tt>n ::
--   <a>NE</a> s</tt> to use.
--   
--   Note that because of the way coverage checking works for polymorphic
--   pattern synonyms, you will unfortunatelly still get incomplete pattern
--   match warnings if you match on both <a>IsNonEmpty</a> and
--   <a>NonEmpty</a>, even though the two are meant to provide complete
--   coverage. However, many instances of <a>HasNonEmpty</a> (like
--   <a>NEMap</a>, <a>NEIntMap</a>, <a>NESet</a>, <a>NEIntSet</a>) will
--   provide their own monomorphic versions of these patterns that can be
--   verified as complete covers by GHC.
--   
--   This is a bidirectional pattern, so you can use <a>IsNonEmpty</a> to
--   convert a <tt><a>NE</a> s</tt> back into an <tt>s</tt>, "obscuring"
--   its non-emptiness (see <a>fromNonEmpty</a>).
pattern IsNonEmpty :: HasNonEmpty s => NE s -> s

-- | The <a>IsNonEmpty</a> and <a>IsEmpty</a> patterns allow you to treat a
--   <tt>s</tt> as if it were either a <tt><a>IsNonEmpty</a> n</tt> (where
--   <tt>n</tt> is a non-empty version of <tt>s</tt>, type <tt><a>NE</a>
--   s</tt>) or an <a>IsEmpty</a>.
--   
--   Matching on <a>IsEmpty</a> means that the original item was empty.
--   
--   This is a bidirectional pattern, so you can use <a>IsEmpty</a> as an
--   expression, and it will be interpreted as <a>empty</a>.
--   
--   Note that because of the way coverage checking works for polymorphic
--   pattern synonyms, you will unfortunatelly still get incomplete pattern
--   match warnings if you match on both <a>IsNonEmpty</a> and
--   <a>NonEmpty</a>, even though the two are meant to provide complete
--   coverage. However, many instances of <a>HasNonEmpty</a> (like
--   <a>NEMap</a>, <a>NEIntMap</a>, <a>NESet</a>, <a>NEIntSet</a>) will
--   provide their own monomorphic versions of these patterns that can be
--   verified as complete covers by GHC.
--   
--   See <a>IsNonEmpty</a> for more information.
pattern IsEmpty :: HasNonEmpty s => s

-- | Useful function for mapping over the "non-empty" representation of a
--   type.
overNonEmpty :: (HasNonEmpty s, HasNonEmpty t) => (NE s -> NE t) -> s -> t

-- | Useful function for applying a function on the "non-empty"
--   representation of a type.
--   
--   If you want a continuation taking <tt><a>NE</a> s -&gt; 'Maybe
--   r'</tt>, you can use <tt><a>withNonEmpty</a> <a>Nothing</a></tt>.
onNonEmpty :: HasNonEmpty s => (NE s -> r) -> s -> Maybe r
instance Data.Containers.NonEmpty.HasNonEmpty [a]
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Map.Internal.Map k a)
instance Data.Containers.NonEmpty.HasNonEmpty (Data.IntMap.Internal.IntMap a)
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Set.Internal.Set a)
instance Data.Containers.NonEmpty.HasNonEmpty Data.IntSet.Internal.IntSet
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Sequence.Internal.Seq a)
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Vector.Vector a)