-- 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.5.0


-- | 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(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
instance Data.Functor.Alt.Alt Data.IntMap.NonEmpty.Internal.NEIntMap
instance Control.Comonad.Comonad Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Internal.Data.Data.Data a => GHC.Internal.Data.Data.Data (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Functor.Classes.Eq1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Foldable1.Foldable1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Internal.Data.Foldable.Foldable Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance GHC.Internal.Base.Functor Data.IntMap.NonEmpty.Internal.NEIntMap
instance Data.Functor.Invariant.Invariant Data.IntMap.NonEmpty.Internal.NEIntMap
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Functor.Classes.Ord1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Functor.Classes.Read1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Internal.Read.Read e => GHC.Internal.Read.Read (Data.IntMap.NonEmpty.Internal.NEIntMap e)
instance GHC.Internal.Base.Semigroup (Data.IntMap.NonEmpty.Internal.NEIntMap a)
instance Data.Functor.Classes.Show1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (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.Semigroup.Traversable.Class.Traversable1 Data.IntMap.NonEmpty.Internal.NEIntMap
instance GHC.Internal.Data.Traversable.Traversable 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
instance GHC.Internal.Data.Data.Data Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Classes.Eq Data.IntSet.NonEmpty.Internal.NEIntSet
instance Data.Aeson.Types.FromJSON.FromJSON Data.IntSet.NonEmpty.Internal.NEIntSet
instance Control.DeepSeq.NFData Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Classes.Ord Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Internal.Read.Read Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Internal.Base.Semigroup Data.IntSet.NonEmpty.Internal.NEIntSet
instance GHC.Internal.Show.Show Data.IntSet.NonEmpty.Internal.NEIntSet
instance Data.Aeson.Types.ToJSON.ToJSON 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.Ord k => Data.Functor.Alt.Alt (Data.Map.NonEmpty.Internal.NEMap k)
instance Control.Comonad.Comonad (Data.Map.NonEmpty.Internal.NEMap k)
instance (GHC.Internal.Data.Data.Data k, GHC.Internal.Data.Data.Data a, GHC.Classes.Ord k) => GHC.Internal.Data.Data.Data (Data.Map.NonEmpty.Internal.NEMap k a)
instance GHC.Classes.Eq k => Data.Functor.Classes.Eq1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Functor.Classes.Eq2 Data.Map.NonEmpty.Internal.NEMap
instance (GHC.Classes.Eq k, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Map.NonEmpty.Internal.NEMap k a)
instance Data.Foldable1.Foldable1 (Data.Map.NonEmpty.Internal.NEMap k)
instance GHC.Internal.Data.Foldable.Foldable (Data.Map.NonEmpty.Internal.NEMap k)
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.Internal.Base.Functor (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Functor.Invariant.Invariant (Data.Map.NonEmpty.Internal.NEMap k)
instance (Control.DeepSeq.NFData k, Control.DeepSeq.NFData a) => Control.DeepSeq.NFData (Data.Map.NonEmpty.Internal.NEMap k a)
instance GHC.Classes.Ord k => Data.Functor.Classes.Ord1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Functor.Classes.Ord2 Data.Map.NonEmpty.Internal.NEMap
instance (GHC.Classes.Ord k, GHC.Classes.Ord a) => GHC.Classes.Ord (Data.Map.NonEmpty.Internal.NEMap k a)
instance (GHC.Classes.Ord k, GHC.Internal.Read.Read k) => Data.Functor.Classes.Read1 (Data.Map.NonEmpty.Internal.NEMap k)
instance (GHC.Classes.Ord k, GHC.Internal.Read.Read k, GHC.Internal.Read.Read e) => GHC.Internal.Read.Read (Data.Map.NonEmpty.Internal.NEMap k e)
instance GHC.Classes.Ord k => GHC.Internal.Base.Semigroup (Data.Map.NonEmpty.Internal.NEMap k a)
instance GHC.Internal.Show.Show k => Data.Functor.Classes.Show1 (Data.Map.NonEmpty.Internal.NEMap k)
instance Data.Functor.Classes.Show2 Data.Map.NonEmpty.Internal.NEMap
instance (GHC.Internal.Show.Show k, GHC.Internal.Show.Show a) => GHC.Internal.Show.Show (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.Semigroup.Traversable.Class.Traversable1 (Data.Map.NonEmpty.Internal.NEMap k)
instance GHC.Internal.Data.Traversable.Traversable (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)
instance Data.Functor.Alt.Alt Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Base.Applicative Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Bind.Class.Apply Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Bind.Class.Bind Data.Sequence.NonEmpty.Internal.NESeq
instance Control.Comonad.Comonad Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Data.Data.Data a => GHC.Internal.Data.Data.Data (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Functor.Classes.Eq1 Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Functor.Extend.Extend Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Foldable1.Foldable1 Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Data.Foldable.Foldable Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Aeson.Types.FromJSON.FromJSON a => Data.Aeson.Types.FromJSON.FromJSON (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Internal.Base.Functor Data.Sequence.NonEmpty.Internal.NESeq
instance Data.Functor.Invariant.Invariant Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Control.Monad.Fix.MonadFix Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Base.Monad Data.Sequence.NonEmpty.Internal.NESeq
instance Control.Monad.Zip.MonadZip Data.Sequence.NonEmpty.Internal.NESeq
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Functor.Classes.Ord1 Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Functor.Classes.Read1 Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Read.Read a => GHC.Internal.Read.Read (Data.Sequence.NonEmpty.Internal.NESeq a)
instance GHC.Internal.Base.Semigroup (Data.Sequence.NonEmpty.Internal.NESeq a)
instance Data.Functor.Classes.Show1 Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (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.Semigroup.Traversable.Class.Traversable1 Data.Sequence.NonEmpty.Internal.NESeq
instance GHC.Internal.Data.Traversable.Traversable Data.Sequence.NonEmpty.Internal.NESeq


-- | <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`
infixl 5 :||>
infixr 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
instance (GHC.Internal.Data.Data.Data a, GHC.Classes.Ord a) => GHC.Internal.Data.Data.Data (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Functor.Classes.Eq1 Data.Set.NonEmpty.Internal.NESet
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Foldable1.Foldable1 Data.Set.NonEmpty.Internal.NESet
instance GHC.Internal.Data.Foldable.Foldable Data.Set.NonEmpty.Internal.NESet
instance (Data.Aeson.Types.FromJSON.FromJSON a, GHC.Classes.Ord a) => Data.Aeson.Types.FromJSON.FromJSON (Data.Set.NonEmpty.Internal.NESet a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Functor.Classes.Ord1 Data.Set.NonEmpty.Internal.NESet
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Set.NonEmpty.Internal.NESet a)
instance (GHC.Internal.Read.Read a, GHC.Classes.Ord a) => GHC.Internal.Read.Read (Data.Set.NonEmpty.Internal.NESet a)
instance GHC.Internal.Base.Semigroup (Data.Set.NonEmpty.Internal.MergeNESet a)
instance GHC.Classes.Ord a => GHC.Internal.Base.Semigroup (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Functor.Classes.Show1 Data.Set.NonEmpty.Internal.NESet
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Data.Set.NonEmpty.Internal.NESet a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Data.Set.NonEmpty.Internal.NESet a)


-- | <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 :: 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.
--   
--   This function is non-total and will raise a runtime exception if the
--   structure happens to be empty.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (+) [1..4]
--   10
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (+) []
--   Exception: Prelude.foldr1: empty list
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (+) Nothing
--   *** Exception: foldr1: empty structure
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (-) [1..4]
--   -2
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (&amp;&amp;) [True, False, True, True]
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (||) [False, False, True, True]
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (+) [1..]
--   * Hangs forever *
--   </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.
--   
--   This function is non-total and will raise a runtime exception if the
--   structure happens to be empty.
--   
--   <pre>
--   <a>foldl1</a> f = <a>foldl1</a> f . <a>toList</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (+) [1..4]
--   10
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (+) []
--   *** Exception: Prelude.foldl1: empty list
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (+) Nothing
--   *** Exception: foldl1: empty structure
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (-) [1..4]
--   -8
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (&amp;&amp;) [True, False, True, True]
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (||) [False, False, True, True]
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1 (+) [1..]
--   * Hangs forever *
--   </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 <tt>foldr1</tt>. 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 <tt>foldl1</tt>. 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 NE s = (t :: Type) | 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 (Data.IntMap.Internal.IntMap a)
instance Data.Containers.NonEmpty.HasNonEmpty Data.IntSet.Internal.IntSet
instance Data.Containers.NonEmpty.HasNonEmpty [a]
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Map.Internal.Map k a)
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Sequence.Internal.Seq a)
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Set.Internal.Set a)
instance Data.Containers.NonEmpty.HasNonEmpty (Data.Vector.Vector a)
