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


-- | Testing utilities for the validity library
--   
--   Note: There are companion instance packages for this library:
--   
--   <ul>
--   <li><a>genvalidity-aeson</a></li>
--   <li><a>genvalidity-bytestring</a></li>
--   <li><a>genvalidity-containers</a></li>
--   <li><a>genvalidity-path</a></li>
--   <li><a>genvalidity-scientific</a></li>
--   <li><a>genvalidity-text</a></li>
--   <li><a>genvalidity-time</a></li>
--   <li><a>genvalidity-unordered-containers</a></li>
--   <li><a>genvalidity-uuid</a></li>
--   <li><a>genvalidity-vector</a></li>
--   </ul>
@package genvalidity
@version 1.1.1.0

module Data.GenValidity.Utils

-- | <a>upTo</a> generates an integer between 0 (inclusive) and <tt>n</tt>.
upTo :: Int -> Gen Int

-- | 'genSplit a' generates a tuple '(b, c)' such that 'b + c' equals
--   <tt>a</tt>.
genSplit :: Int -> Gen (Int, Int)

-- | 'genSplit3 a' generates a triple '(b, c, d)' such that 'b + c + d'
--   equals <tt>a</tt>.
genSplit3 :: Int -> Gen (Int, Int, Int)

-- | 'genSplit4 a' generates a quadruple '(b, c, d, e)' such that 'b + c +
--   d + e' equals <tt>a</tt>.
genSplit4 :: Int -> Gen (Int, Int, Int, Int)

-- | 'genSplit5 a' generates a quintuple '(b, c, d, e, f)' such that 'b + c
--   + d + e + f' equals <tt>a</tt>.
genSplit5 :: Int -> Gen (Int, Int, Int, Int, Int)

-- | 'genSplit6 a' generates a sextuple '(b, c, d, e, f, g)' such that 'b +
--   c + d + e + f + g' equals <tt>a</tt>.
genSplit6 :: Int -> Gen (Int, Int, Int, Int, Int, Int)

-- | 'genSplit7 a' generates a septtuple '(b, c, d, e, f, g)' such that 'b
--   + c + d + e + f + g' equals <tt>a</tt>.
genSplit7 :: Int -> Gen (Int, Int, Int, Int, Int, Int, Int)

-- | 'genSplit8 a' generates a octtuple '(b, c, d, e, f, g, h)' such that
--   'b + c + d + e + f + g + h' equals <tt>a</tt>.
genSplit8 :: Int -> Gen (Int, Int, Int, Int, Int, Int, Int, Int)

-- | 'arbPartition n' generates a list <tt>ls</tt> such that 'sum ls'
--   equals <tt>n</tt>, approximately.
arbPartition :: Int -> Gen [Int]

-- | Generates a random permutation of the given list.
shuffle :: [a] -> Gen [a]
genListLength :: Gen Int
genStringBy :: Gen Char -> Gen String
genStringBy1 :: Gen Char -> Gen String

-- | A version of <tt>listOf</tt> that takes size into account more
--   accurately.
--   
--   This generator distributes the size that is is given among the values
--   in the list that it generates.
genListOf :: Gen a -> Gen [a]

-- | A version of <a>genNonEmptyOf</a> that returns a list instead of a
--   <a>NonEmpty</a>.
genListOf1 :: Gen a -> Gen [a]
genMaybe :: Gen a -> Gen (Maybe a)
genNonEmptyOf :: Gen a -> Gen (NonEmpty a)

-- | Generate Int, Int8, Int16, Int32 and Int64 values smartly.
--   
--   <ul>
--   <li>Some at the border</li>
--   <li>Some around zero</li>
--   <li>Mostly uniformly</li>
--   </ul>
genIntX :: (Integral a, Bounded a, Random a) => Gen a

-- | Generate Word, Word8, Word16, Word32 and Word64 values smartly.
--   
--   <ul>
--   <li>Some at the border</li>
--   <li>Some around zero</li>
--   <li>Mostly uniformly</li>
--   </ul>
genWordX :: (Integral a, Bounded a, Random a) => Gen a

-- | See <a>genFloatX</a>
genFloat :: Gen Float

-- | See <a>genFloatX</a>
genDouble :: Gen Double

-- | Generate floating point numbers smartly:
--   
--   <ul>
--   <li>Some denormalised</li>
--   <li>Some around zero</li>
--   <li>Some around the bounds</li>
--   <li>Some by encoding an Integer and an Int to a floating point
--   number.</li>
--   <li>Some accross the entire range</li>
--   <li>Mostly uniformly via the bitrepresentation</li>
--   </ul>
--   
--   The function parameter is to go from the bitrepresentation to the
--   floating point value.
genFloatX :: (Read a, RealFloat a, Bounded w, Random w) => (w -> a) -> Gen a
genInteger :: Gen Integer

-- | Lift a shrinker function into a maybe
shrinkMaybe :: (a -> [a]) -> Maybe a -> [Maybe a]

-- | Combine two shrinking functions to shrink a tuple.
shrinkTuple :: (a -> [a]) -> (b -> [b]) -> (a, b) -> [(a, b)]

-- | Like <a>shrinkTuple</a>, but for triples
shrinkTriple :: (a -> [a]) -> (b -> [b]) -> (c -> [c]) -> (a, b, c) -> [(a, b, c)]

-- | Like <a>shrinkTuple</a>, but for quadruples
shrinkQuadruple :: (a -> [a]) -> (b -> [b]) -> (c -> [c]) -> (d -> [d]) -> (a, b, c, d) -> [(a, b, c, d)]

-- | Turn a shrinking function into a function that shrinks tuples.
shrinkT2 :: (a -> [a]) -> (a, a) -> [(a, a)]

-- | Turn a shrinking function into a function that shrinks triples.
shrinkT3 :: (a -> [a]) -> (a, a, a) -> [(a, a, a)]

-- | Turn a shrinking function into a function that shrinks quadruples.
shrinkT4 :: (a -> [a]) -> (a, a, a, a) -> [(a, a, a, a)]

-- | Shrink a list of values given a shrinking function for individual
--   values.
shrinkList :: (a -> [a]) -> [a] -> [[a]]
shrinkNonEmpty :: (a -> [a]) -> NonEmpty a -> [NonEmpty a]


-- | <tt>GenValid</tt> exists to make tests involving <tt>Validity</tt>
--   types easier and speed up the generation of data for them.
--   
--   To implement tests for this datatype, we would have to be able to
--   generate both primes. We could do this with a generator like this one:
--   
--   <pre>
--   (Prime &lt;$&gt; 'arbitrary') `suchThat` isValid
--   </pre>
--   
--   However, this is tedious and inefficient, as well as quite naive
--   (because <a>arbitrary</a> tends to use very naive generators).
--   
--   The <tt>GenValid</tt> type class allows you to specify how to
--   (efficiently) generate valid data of the given type to allow for
--   easier and quicker testing. The default implementation of
--   <a>GenValid</a> already gives you a generator and shrinking function
--   for free:
--   
--   <pre>
--   instance GenValid Prime
--   </pre>
--   
--   For example, to generate primes, we don't have to consider even
--   numbers other than 2. A more efficient implementation could then look
--   as follows:
--   
--   <pre>
--   instance GenValid Prime where
--       genValid = Prime &lt;$&gt;
--          (oneof
--            [ pure 2
--            , ((\y -&gt; 2 * abs y + 1) &lt;$&gt; arbitrary) `suchThat` isPrime)
--            ])
--   </pre>
--   
--   Typical examples of tests involving validity could look as follows:
--   
--   <pre>
--   it "succeeds when given valid input" $ do
--       forAllValid $ \input -&gt;
--           myFunction input `shouldSatisfy` isRight
--   </pre>
--   
--   <pre>
--   it "produces valid output when it succeeds" $ do
--       forAllValid $ \input -&gt;
--           case myFunction input of
--               Nothing -&gt; return () -- Can happen
--               Just output -&gt; output `shouldSatisfy` isValid
--   </pre>
--   
--   Definitely also look at the companion packages for more info on how to
--   use this package.
module Data.GenValidity

-- | A class of types for which valid values can be generated to be valid.
--   
--   <h3>How to instantiate <a>GenValid</a></h3>
--   
--   <b>Step 1</b>: Try to instantiate <a>GenValid</a> without overriding
--   any functions. It is possible that, if few values are valid or if
--   validity checking is expensive, the resulting generator is too slow.
--   In that case, go to Step 2.
--   
--   <b>Step 2</b>: Consider using
--   <a>genValidStructurallyWithoutExtraChecking</a> and
--   <a>shrinkValidStructurallyWithoutExtraFiltering</a> to speed up
--   generation. This only works if your type has a derived or trivial
--   <a>Validity</a> instance.
--   
--   <b>Step 3</b>: If that still is not fast enough, consider writing your
--   own generator and shrinking function. Make sure to generate any
--   possible valid value, but only valid values.
--   
--   <h3>A note about <a>Arbitrary</a></h3>
--   
--   If you also write <tt>Arbitrary</tt> instances for <tt>GenValid</tt>
--   types, it may be best to simply use
--   
--   <pre>
--   instance Arbitrary A where
--     arbitrary = genValid
--     shrink = shrinkValid
--   </pre>
class Validity a => GenValid a

-- | Generate a valid datum, this should cover all possible valid values in
--   the type
--   
--   The default implementation is as follows:
--   
--   <pre>
--   genValid = genValidStructurally
--   </pre>
--   
--   To speed up testing, it may be a good idea to implement this yourself.
--   If you do, make sure that it is possible to generate all possible
--   valid data, otherwise your testing may not cover all cases.
genValid :: GenValid a => Gen a
($dmgenValid) :: (GenValid a, Generic a, GGenValid (Rep a)) => Gen a

-- | Shrink a valid value.
--   
--   The default implementation is as follows:
--   
--   <pre>
--   shrinkValid = shrinkValidStructurally
--   </pre>
--   
--   It is important that this shrinking function only shrinks values to
--   valid values. If <a>shrinkValid</a> ever shrinks a value to an invalid
--   value, the test that is being shrunk for might fail for a different
--   reason than for the reason that it originally failed. This would lead
--   to very confusing error messages.
shrinkValid :: GenValid a => a -> [a]
($dmshrinkValid) :: (GenValid a, Generic a, GValidRecursivelyShrink (Rep a), GValidSubterms (Rep a) a) => a -> [a]

-- | Generate a valid value by generating all the sub parts using the
--   <a>Generic</a> instance, and trying that until a valid value has been
--   generated
--   
--   <pre>
--   genValidStructurally = genValidStructurallyWithoutExtraChecking `suchThat` isValid
--   </pre>
--   
--   This is probably the function that you are looking for. If you do use
--   this function to override <a>genValid</a>, you probably also want to
--   use <a>shrinkValidStructurally</a> to override <a>shrinkValid</a>.
genValidStructurally :: (Validity a, Generic a, GGenValid (Rep a)) => Gen a

-- | Generate a valid value by generating all the sub parts using the
--   <a>Generic</a> instance,
--   
--   This generator is _not_ guaranteed to generate a valid value.
--   
--   This is probably _not_ the function that you are looking for when
--   overriding <a>genValid</a> _unless_ the type in question has no
--   _extra_ validity constraints on top of the validity of its sub parts.
genValidStructurallyWithoutExtraChecking :: (Generic a, GGenValid (Rep a)) => Gen a

-- | Shrink a term to any of its immediate valid subterms, and also
--   recursively shrink all subterms, and then filtering out the results
--   that are not valid.
--   
--   <pre>
--   shrinkValidStructurally = filter isValid . shrinkValidStructurallyWithoutExtraFiltering
--   </pre>
--   
--   This is probably the function that you are looking for.
shrinkValidStructurally :: (Validity a, Generic a, GValidRecursivelyShrink (Rep a), GValidSubterms (Rep a) a) => a -> [a]

-- | Shrink a term to any of its immediate valid subterms, and also
--   recursively shrink all subterms.
--   
--   This shrinking function is _not_ guaranteed to shrink to valid values.
--   
--   This is probably _not_ the function that you are looking for when
--   overriding <a>shrinkValid</a> _unless_ the type in question has no
--   _extra_ validity constraints on top of the validity of its sub parts.
shrinkValidStructurallyWithoutExtraFiltering :: (Generic a, GValidRecursivelyShrink (Rep a), GValidSubterms (Rep a) a) => a -> [a]
genUtf16SurrogateCodePoint :: Gen Char
genLineSeparator :: Gen Char
genNonLineSeparator :: Gen Char
genSingleLineString :: Gen String
class GGenValid (f :: Type -> Type)
gGenValid :: GGenValid f => Gen (f a)
class GValidRecursivelyShrink (f :: Type -> Type)
gValidRecursivelyShrink :: GValidRecursivelyShrink f => f a -> [f a]

-- | All immediate validSubterms of a term.
structurallyValidSubterms :: (Generic a, GValidSubterms (Rep a) a) => a -> [a]
class GValidSubterms (f :: Type -> Type) a
gValidSubterms :: GValidSubterms f a => f a -> [a]
class GValidSubtermsIncl (f :: Type -> Type) a
gValidSubtermsIncl :: GValidSubtermsIncl f a => f a -> [a]
instance (Data.GenValidity.GGenValid a, Data.GenValidity.GGenValid b) => Data.GenValidity.GGenValid (a GHC.Internal.Generics.:*: b)
instance (Data.GenValidity.GGenValid a, Data.GenValidity.GGenValid b) => Data.GenValidity.GGenValid (a GHC.Internal.Generics.:+: b)
instance Data.GenValidity.GenValid a => Data.GenValidity.GGenValid (GHC.Internal.Generics.K1 i a)
instance Data.GenValidity.GGenValid a => Data.GenValidity.GGenValid (GHC.Internal.Generics.M1 i c a)
instance Data.GenValidity.GGenValid GHC.Internal.Generics.U1
instance (Data.GenValidity.GValidRecursivelyShrink f, Data.GenValidity.GValidRecursivelyShrink g) => Data.GenValidity.GValidRecursivelyShrink (f GHC.Internal.Generics.:*: g)
instance (Data.GenValidity.GValidRecursivelyShrink f, Data.GenValidity.GValidRecursivelyShrink g) => Data.GenValidity.GValidRecursivelyShrink (f GHC.Internal.Generics.:+: g)
instance Data.GenValidity.GenValid a => Data.GenValidity.GValidRecursivelyShrink (GHC.Internal.Generics.K1 i a)
instance Data.GenValidity.GValidRecursivelyShrink f => Data.GenValidity.GValidRecursivelyShrink (GHC.Internal.Generics.M1 i c f)
instance Data.GenValidity.GValidRecursivelyShrink GHC.Internal.Generics.U1
instance Data.GenValidity.GValidRecursivelyShrink GHC.Internal.Generics.V1
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubtermsIncl (f GHC.Internal.Generics.:*: g) a
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubtermsIncl (f GHC.Internal.Generics.:+: g) a
instance Data.GenValidity.GValidSubtermsIncl (GHC.Internal.Generics.K1 i a) b
instance Data.GenValidity.GValidSubtermsIncl (GHC.Internal.Generics.K1 i a) a
instance Data.GenValidity.GValidSubtermsIncl f a => Data.GenValidity.GValidSubtermsIncl (GHC.Internal.Generics.M1 i c f) a
instance Data.GenValidity.GValidSubtermsIncl GHC.Internal.Generics.U1 a
instance Data.GenValidity.GValidSubtermsIncl GHC.Internal.Generics.V1 a
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubterms (f GHC.Internal.Generics.:*: g) a
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubterms (f GHC.Internal.Generics.:+: g) a
instance Data.GenValidity.GValidSubterms (GHC.Internal.Generics.K1 i a) b
instance Data.GenValidity.GValidSubterms f a => Data.GenValidity.GValidSubterms (GHC.Internal.Generics.M1 i c f) a
instance Data.GenValidity.GValidSubterms GHC.Internal.Generics.U1 a
instance Data.GenValidity.GValidSubterms GHC.Internal.Generics.V1 a
instance Data.GenValidity.GenValid (f a) => Data.GenValidity.GenValid (GHC.Internal.Data.Semigroup.Internal.Alt f a)
instance Data.GenValidity.GenValid GHC.Types.Bool
instance Data.GenValidity.GenValid GHC.Types.Char
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Data.Functor.Const.Const a b)
instance Data.GenValidity.GenValid GHC.Types.Double
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Data.Semigroup.Internal.Dual a)
instance (Data.GenValidity.GenValid a, Data.GenValidity.GenValid b) => Data.GenValidity.GenValid (GHC.Internal.Data.Either.Either a b)
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Data.Monoid.First a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (Data.Semigroup.First a)
instance Data.Fixed.HasResolution a => Data.GenValidity.GenValid (Data.Fixed.Fixed a)
instance Data.GenValidity.GenValid GHC.Types.Float
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Data.Functor.Identity.Identity a)
instance Data.GenValidity.GenValid GHC.Types.Int
instance Data.GenValidity.GenValid GHC.Internal.Int.Int16
instance Data.GenValidity.GenValid GHC.Internal.Int.Int32
instance Data.GenValidity.GenValid GHC.Internal.Int.Int64
instance Data.GenValidity.GenValid GHC.Internal.Int.Int8
instance Data.GenValidity.GenValid GHC.Num.Integer.Integer
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Data.Monoid.Last a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (Data.Semigroup.Last a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid [a]
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Maybe.Maybe a)
instance Data.GenValidity.GenValid GHC.Num.Natural.Natural
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Internal.Base.NonEmpty a)
instance Data.GenValidity.GenValid GHC.Types.Ordering
instance (GHC.Internal.Real.Integral a, GHC.Internal.Num.Num a, GHC.Classes.Ord a, Data.GenValidity.GenValid a) => Data.GenValidity.GenValid (GHC.Internal.Real.Ratio a)
instance (Data.GenValidity.GenValid a, Data.GenValidity.GenValid b) => Data.GenValidity.GenValid (a, b)
instance (Data.GenValidity.GenValid a, Data.GenValidity.GenValid b, Data.GenValidity.GenValid c) => Data.GenValidity.GenValid (a, b, c)
instance (Data.GenValidity.GenValid a, Data.GenValidity.GenValid b, Data.GenValidity.GenValid c, Data.GenValidity.GenValid d) => Data.GenValidity.GenValid (a, b, c, d)
instance (Data.GenValidity.GenValid a, Data.GenValidity.GenValid b, Data.GenValidity.GenValid c, Data.GenValidity.GenValid d, Data.GenValidity.GenValid e) => Data.GenValidity.GenValid (a, b, c, d, e)
instance Data.GenValidity.GenValid ()
instance Data.GenValidity.GenValid GHC.Types.Word
instance Data.GenValidity.GenValid GHC.Internal.Word.Word16
instance Data.GenValidity.GenValid GHC.Internal.Word.Word32
instance Data.GenValidity.GenValid GHC.Internal.Word.Word64
instance Data.GenValidity.GenValid GHC.Internal.Word.Word8
