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


-- | Express the minimum length of a container in its type
--   
--   Please see README.md
@package minlen
@version 0.1.0.0

module Data.MinLen

-- | <a>Zero</a> is the base value for the Peano numbers.
data Zero
Zero :: Zero

-- | <a>Succ</a> represents the next number in the sequence of natural
--   numbers.
--   
--   It takes a <tt>nat</tt> (a natural number) as an argument.
--   
--   <a>Zero</a> is a <tt>nat</tt>, allowing <tt><a>Succ</a>
--   <a>Zero</a></tt> to represent 1.
--   
--   <a>Succ</a> is also a <tt>nat</tt>, so it can be applied to itself,
--   allowing <tt><a>Succ</a> (<a>Succ</a> <a>Zero</a>)</tt> to represent
--   2, <tt><a>Succ</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>))</tt> to
--   represent 3, and so on.
data Succ nat
Succ :: nat -> Succ nat

-- | Type-level natural number utility typeclass
class TypeNat nat

-- | Turn a type-level natural number into a number
--   
--   <pre>
--   &gt; <a>toValueNat</a> <a>Zero</a>
--   0
--   &gt; <a>toValueNat</a> (<a>Succ</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>)))
--   3
--   </pre>
toValueNat :: (TypeNat nat, Num i) => nat -> i

-- | Get a data representation of a natural number type
--   
--   <pre>
--   &gt; <a>typeNat</a> :: <a>Succ</a> (<a>Succ</a> <a>Zero</a>)
--   Succ (Succ Zero) -- Errors because Succ and Zero have no Show typeclass,
--                    -- But this is what it would look like if it did.
--   </pre>
typeNat :: TypeNat nat => nat

-- | Adds two type-level naturals.
--   
--   See the <a>mlappend</a> type signature for an example.
--   
--   <pre>
--   &gt; :t <a>typeNat</a> :: <a>AddNat</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>)) (<a>Succ</a> <a>Zero</a>)
--   
--   <a>typeNat</a> :: <a>AddNat</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>)) (<a>Succ</a> <a>Zero</a>)
--     :: <a>Succ</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>))
--   </pre>

-- | Calculates the maximum of two type-level naturals.
--   
--   See the <a>mlunion</a> type signature for an example.
--   
--   <pre>
--   &gt; :t <a>typeNat</a> :: <a>MaxNat</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>)) (<a>Succ</a> <a>Zero</a>)
--   
--   <a>typeNat</a> :: <a>MaxNat</a> (<a>Succ</a> (<a>Succ</a> <a>Zero</a>)) (<a>Succ</a> <a>Zero</a>)
--     :: <a>Succ</a> (<a>Succ</a> <a>Zero</a>)
--   </pre>

-- | A wrapper around a container which encodes its minimum length in the
--   type system. This allows functions like <a>head</a> and <a>maximum</a>
--   to be made safe without using <a>Maybe</a>.
--   
--   The length, <tt>nat</tt>, is encoded as a <a>Peano number</a>, which
--   starts with the <a>Zero</a> constructor and is made one larger with
--   each application of <a>Succ</a> (<a>Zero</a> for 0, <tt><a>Succ</a>
--   <a>Zero</a></tt> for 1, <tt><a>Succ</a> (<a>Succ</a> <a>Zero</a>)</tt>
--   for 2, etc.). Functions which require at least one element, then, are
--   typed with <tt>Succ nat</tt>, where <tt>nat</tt> is either <a>Zero</a>
--   or any number of applications of <a>Succ</a>:
--   
--   <pre>
--   <a>head</a> :: <a>MonoTraversable</a> mono =&gt; <a>MinLen</a> (<a>Succ</a> nat) mono -&gt; <a>Element</a> mono
--   </pre>
--   
--   The length is also a <a>phantom type</a>, i.e. it is only used on the
--   left hand side of the type and doesn't exist at runtime. Notice how
--   <tt><a>Succ</a> <a>Zero</a></tt> isn't included in the printed output:
--   
--   <pre>
--   &gt; <a>toMinLen</a> [1,2,3] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   <a>Just</a> (<a>MinLen</a> {unMinLen = [1,2,3]})
--   </pre>
--   
--   You can still use GHCI's <tt>:i</tt> command to see the phantom type
--   information:
--   
--   <pre>
--   &gt; let xs = <a>mlcons</a> 1 $ <a>toMinLenZero</a> []
--   &gt; :i xs
--   xs :: <a>Num</a> t =&gt; <a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [t]
--   </pre>
data MinLen nat mono

-- | Get the monomorphic container out of a <a>MinLen</a> wrapper.
unMinLen :: MinLen nat mono -> mono

-- | Types a container as having a minimum length of zero. This is useful
--   when combined with other <a>MinLen</a> functions that increase the
--   size of the container.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; 1 `mlcons` <a>toMinLenZero</a> []
--   <a>MinLen</a> {unMinLen = [1]}
--   </pre>
toMinLenZero :: (MonoFoldable mono) => mono -> MinLen Zero mono

-- | Attempts to add a <a>MinLen</a> constraint to a monomorphic container.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>toMinLen</a> [1,2,3] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   &gt; xs
--   <a>Just</a> (<a>MinLen</a> {unMinLen = [1,2,3]})
--   
--   &gt; :i xs
--   xs :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   </pre>
--   
--   <pre>
--   &gt; <a>toMinLen</a> [] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   <a>Nothing</a>
--   </pre>
toMinLen :: (MonoFoldable mono, TypeNat nat) => mono -> Maybe (MinLen nat mono)

-- | <b>Unsafe</b>
--   
--   Although this function itself cannot cause a segfault, it breaks the
--   safety guarantees of <a>MinLen</a> and can lead to a segfault when
--   using otherwise safe functions.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>unsafeToMinLen</a> [] :: <a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>]
--   &gt; <a>olength</a> xs
--   0
--   &gt; <a>head</a> xs
--   *** Exception: Data.MonoTraversable.headEx: empty
--   </pre>
unsafeToMinLen :: mono -> MinLen nat mono

-- | Adds an element to the front of a list, increasing its minimum length
--   by 1.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>unsafeToMinLen</a> [1,2,3] :: <a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>]
--   &gt; 0 `mlcons` xs
--   <a>MinLen</a> {unMinLen = [0,1,2,3]}
--   </pre>
mlcons :: IsSequence seq => Element seq -> MinLen nat seq -> MinLen (Succ nat) seq
infixr 5 `mlcons`

-- | Concatenate two sequences, adding their minimum lengths together.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>unsafeToMinLen</a> [1,2,3] :: <a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>]
--   &gt; xs `mlappend` xs
--   <a>MinLen</a> {unMinLen = [1,2,3,1,2,3]}
--   </pre>
mlappend :: IsSequence seq => MinLen x seq -> MinLen y seq -> MinLen (AddNat x y) seq

-- | Joins two semigroups, keeping the larger <a>MinLen</a> of the two.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>unsafeToMinLen</a> [1] :: <a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>]
--   &gt; let ys = xs `mlunion` xs
--   &gt; ys
--   <a>MinLen</a> {unMinLen = [1,1]}
--   
--   &gt; :i ys
--   ys :: <a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>]
--   </pre>
mlunion :: (Semigroup mono, GrowingAppend mono) => MinLen x mono -> MinLen y mono -> MinLen (MaxNat x y) mono

-- | Return the first element of a monomorphic container.
--   
--   Safe version of <a>headEx</a>, only works on monomorphic containers
--   wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
head :: MonoFoldable mono => MinLen (Succ nat) mono -> Element mono

-- | Return the last element of a monomorphic container.
--   
--   Safe version of <a>lastEx</a>, only works on monomorphic containers
--   wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
last :: MonoFoldable mono => MinLen (Succ nat) mono -> Element mono

-- | Returns all but the first element of a sequence, reducing its
--   <a>MinLen</a> by 1.
--   
--   Safe, only works on sequences wrapped in a <tt><a>MinLen</a>
--   (<a>Succ</a> nat)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>toMinLen</a> [1,2,3] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   &gt; <a>fmap</a> <a>tailML</a> xs
--   <a>Just</a> (<a>MinLen</a> {unMinLen = [2,3]})
--   </pre>
tailML :: IsSequence seq => MinLen (Succ nat) seq -> MinLen nat seq

-- | Returns all but the last element of a sequence, reducing its
--   <a>MinLen</a> by 1.
--   
--   Safe, only works on sequences wrapped in a <tt><a>MinLen</a>
--   (<a>Succ</a> nat)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>toMinLen</a> [1,2,3] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   &gt; <a>fmap</a> <a>initML</a> xs
--   <a>Just</a> (<a>MinLen</a> {unMinLen = [1,2]})
--   </pre>
initML :: IsSequence seq => MinLen (Succ nat) seq -> MinLen nat seq

-- | Containers which, when two values are combined, the combined length is
--   no less than the larger of the two inputs. In code:
--   
--   <pre>
--   olength (x &lt;&gt; y) &gt;= max (olength x) (olength y)
--   </pre>
--   
--   This class has no methods, and is simply used to assert that this law
--   holds, in order to provide guarantees of correctness (see, for
--   instance, <a>Data.NonNull</a>).
--   
--   This should have a <tt>Semigroup</tt> superclass constraint, however,
--   due to <tt>Semigroup</tt> only recently moving to base, some packages
--   do not provide instances.
class MonoFoldable mono => GrowingAppend mono

-- | Map each element of a monomorphic container to a semigroup, and
--   combine the results.
--   
--   Safe version of <a>ofoldMap1Ex</a>, only works on monomorphic
--   containers wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = ("hello", 1 :: <tt>Integer</tt>) `mlcons` (" world", 2) `mlcons` (<a>toMinLenZero</a> [])
--   &gt; <a>ofoldMap1</a> <tt>fst</tt> xs
--   "hello world"
--   </pre>
ofoldMap1 :: (MonoFoldable mono, Semigroup m) => (Element mono -> m) -> MinLen (Succ nat) mono -> m

-- | Join a monomorphic container, whose elements are <a>Semigroup</a>s,
--   together.
--   
--   Safe, only works on monomorphic containers wrapped in a
--   <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = "a" `mlcons` "b" `mlcons` "c" `mlcons` (<a>toMinLenZero</a> [])
--   &gt; xs
--   <a>MinLen</a> {unMinLen = ["a","b","c"]}
--   
--   &gt; <a>ofold1</a> xs
--   "abc"
--   </pre>
ofold1 :: (MonoFoldable mono, Semigroup (Element mono)) => MinLen (Succ nat) mono -> Element mono

-- | Right-associative fold of a monomorphic container with no base
--   element.
--   
--   Safe version of <a>ofoldr1Ex</a>, only works on monomorphic containers
--   wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
--   
--   <pre>
--   <tt>foldr1</tt> f = <a>Prelude</a>.<a>foldr1</a> f . <a>otoList</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = "a" `mlcons` "b" `mlcons` "c" `mlcons` (<a>toMinLenZero</a> [])
--   &gt; <a>ofoldr1</a> (++) xs
--   "abc"
--   </pre>
ofoldr1 :: MonoFoldable mono => (Element mono -> Element mono -> Element mono) -> MinLen (Succ nat) mono -> Element mono

-- | Strict left-associative fold of a monomorphic container with no base
--   element.
--   
--   Safe version of <a>ofoldl1Ex'</a>, only works on monomorphic
--   containers wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
--   
--   <pre>
--   <tt>foldl1'</tt> f = <a>Prelude</a>.<a>foldl1'</a> f . <a>otoList</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = "a" `mlcons` "b" `mlcons` "c" `mlcons` (<a>toMinLenZero</a> [])
--   &gt; <a>ofoldl1'</a> (++) xs
--   "abc"
--   </pre>
ofoldl1' :: MonoFoldable mono => (Element mono -> Element mono -> Element mono) -> MinLen (Succ nat) mono -> Element mono

-- | Get the maximum element of a monomorphic container.
--   
--   Safe version of <a>maximumEx</a>, only works on monomorphic containers
--   wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>toMinLen</a> [1,2,3] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   &gt; <a>fmap</a> <a>maximum</a> xs
--   <a>Just</a> 3
--   </pre>
maximum :: (MonoFoldable mono, Ord (Element mono)) => MinLen (Succ nat) mono -> Element mono

-- | Get the minimum element of a monomorphic container.
--   
--   Safe version of <a>minimumEx</a>, only works on monomorphic containers
--   wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt; let xs = <a>toMinLen</a> [1,2,3] :: <a>Maybe</a> (<a>MinLen</a> (<a>Succ</a> <a>Zero</a>) [<a>Int</a>])
--   &gt; <a>fmap</a> <a>minimum</a> xs
--   <a>Just</a> 1
--   </pre>
minimum :: (MonoFoldable mono, Ord (Element mono)) => MinLen (Succ nat) mono -> Element mono

-- | Get the maximum element of a monomorphic container, using a supplied
--   element ordering function.
--   
--   Safe version of <a>maximumByEx</a>, only works on monomorphic
--   containers wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
maximumBy :: MonoFoldable mono => (Element mono -> Element mono -> Ordering) -> MinLen (Succ nat) mono -> Element mono

-- | Get the minimum element of a monomorphic container, using a supplied
--   element ordering function.
--   
--   Safe version of <a>minimumByEx</a>, only works on monomorphic
--   containers wrapped in a <tt><a>MinLen</a> (<a>Succ</a> nat)</tt>.
minimumBy :: MonoFoldable mono => (Element mono -> Element mono -> Ordering) -> MinLen (Succ nat) mono -> Element mono
instance (Data.Data.Data nat, Data.Data.Data mono) => Data.Data.Data (Data.MinLen.MinLen nat mono)
instance GHC.Show.Show mono => GHC.Show.Show (Data.MinLen.MinLen nat mono)
instance GHC.Read.Read mono => GHC.Read.Read (Data.MinLen.MinLen nat mono)
instance GHC.Classes.Ord mono => GHC.Classes.Ord (Data.MinLen.MinLen nat mono)
instance GHC.Classes.Eq mono => GHC.Classes.Eq (Data.MinLen.MinLen nat mono)
instance Data.MonoTraversable.MonoFunctor mono => Data.MonoTraversable.MonoFunctor (Data.MinLen.MinLen nat mono)
instance Data.MonoTraversable.MonoFoldable mono => Data.MonoTraversable.MonoFoldable (Data.MinLen.MinLen nat mono)
instance Data.MonoTraversable.GrowingAppend mono => Data.MonoTraversable.GrowingAppend (Data.MinLen.MinLen nat mono)
instance Data.MinLen.TypeNat Data.MinLen.Zero
instance Data.MinLen.TypeNat nat => Data.MinLen.TypeNat (Data.MinLen.Succ nat)
instance Data.MonoTraversable.MonoTraversable mono => Data.MonoTraversable.MonoTraversable (Data.MinLen.MinLen nat mono)
instance (Data.Semigroup.Semigroup mono, Data.MonoTraversable.GrowingAppend mono) => Data.Semigroup.Semigroup (Data.MinLen.MinLen nat mono)
instance Data.Sequences.SemiSequence seq => Data.Sequences.SemiSequence (Data.MinLen.MinLen nat seq)
instance Data.MonoTraversable.MonoPointed mono => Data.MonoTraversable.MonoPointed (Data.MinLen.MinLen Data.MinLen.Zero mono)
instance Data.MonoTraversable.MonoPointed mono => Data.MonoTraversable.MonoPointed (Data.MinLen.MinLen (Data.MinLen.Succ Data.MinLen.Zero) mono)
instance Data.Sequences.IsSequence mono => Data.MonoTraversable.MonoComonad (Data.MinLen.MinLen (Data.MinLen.Succ Data.MinLen.Zero) mono)