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

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

-- | 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]
genNonEmptyOf :: Gen a -> Gen (NonEmpty a)
shrinkTuple :: (a -> [a]) -> (b -> [b]) -> (a, b) -> [(a, b)]

-- | 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)]

-- | 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 :: forall a. (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 :: forall a. (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 :: forall a w. (Read a, RealFloat a, Bounded w, Random w) => (w -> a) -> Gen a
genInteger :: Gen Integer


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

-- | 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, 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]

-- | 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, 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
gGenValid :: GGenValid f => Gen (f a)
class GValidRecursivelyShrink f
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 a
gValidSubterms :: GValidSubterms f a => f a -> [a]
class GValidSubtermsIncl f a
gValidSubtermsIncl :: GValidSubtermsIncl f a => f a -> [a]
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubterms (f GHC.Generics.:*: g) a
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubterms (f GHC.Generics.:+: g) a
instance Data.GenValidity.GValidSubtermsIncl GHC.Generics.V1 a
instance Data.GenValidity.GValidSubtermsIncl GHC.Generics.U1 a
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubtermsIncl (f GHC.Generics.:*: g) a
instance (Data.GenValidity.GValidSubtermsIncl f a, Data.GenValidity.GValidSubtermsIncl g a) => Data.GenValidity.GValidSubtermsIncl (f GHC.Generics.:+: g) a
instance Data.GenValidity.GValidSubtermsIncl f a => Data.GenValidity.GValidSubtermsIncl (GHC.Generics.M1 i c f) a
instance Data.GenValidity.GValidSubtermsIncl (GHC.Generics.K1 i a) a
instance Data.GenValidity.GValidSubtermsIncl (GHC.Generics.K1 i a) b
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 (Data.Either.Either 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 a => Data.GenValidity.GenValid (GHC.Maybe.Maybe a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid (GHC.Base.NonEmpty a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GenValid [a]
instance Data.GenValidity.GenValid ()
instance Data.GenValidity.GenValid GHC.Types.Bool
instance Data.GenValidity.GenValid GHC.Types.Ordering
instance Data.GenValidity.GenValid GHC.Types.Char
instance Data.GenValidity.GenValid GHC.Types.Int
instance Data.GenValidity.GenValid GHC.Int.Int8
instance Data.GenValidity.GenValid GHC.Int.Int16
instance Data.GenValidity.GenValid GHC.Int.Int32
instance Data.GenValidity.GenValid GHC.Int.Int64
instance Data.GenValidity.GenValid GHC.Types.Word
instance Data.GenValidity.GenValid GHC.Word.Word8
instance Data.GenValidity.GenValid GHC.Word.Word16
instance Data.GenValidity.GenValid GHC.Word.Word32
instance Data.GenValidity.GenValid GHC.Word.Word64
instance Data.GenValidity.GenValid GHC.Types.Float
instance Data.GenValidity.GenValid GHC.Types.Double
instance Data.GenValidity.GenValid GHC.Integer.Type.Integer
instance Data.GenValidity.GenValid GHC.Natural.Natural
instance (GHC.Real.Integral a, GHC.Num.Num a, GHC.Classes.Ord a, Data.GenValidity.GenValid a) => Data.GenValidity.GenValid (GHC.Real.Ratio a)
instance Data.Fixed.HasResolution a => Data.GenValidity.GenValid (Data.Fixed.Fixed a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GGenValid (GHC.Generics.K1 i a)
instance Data.GenValidity.GenValid a => Data.GenValidity.GValidRecursivelyShrink (GHC.Generics.K1 i a)
instance Data.GenValidity.GValidSubterms GHC.Generics.V1 a
instance Data.GenValidity.GValidSubterms GHC.Generics.U1 a
instance Data.GenValidity.GValidSubterms f a => Data.GenValidity.GValidSubterms (GHC.Generics.M1 i c f) a
instance Data.GenValidity.GValidSubterms (GHC.Generics.K1 i a) b
instance (Data.GenValidity.GValidRecursivelyShrink f, Data.GenValidity.GValidRecursivelyShrink g) => Data.GenValidity.GValidRecursivelyShrink (f GHC.Generics.:*: g)
instance (Data.GenValidity.GValidRecursivelyShrink f, Data.GenValidity.GValidRecursivelyShrink g) => Data.GenValidity.GValidRecursivelyShrink (f GHC.Generics.:+: g)
instance Data.GenValidity.GValidRecursivelyShrink f => Data.GenValidity.GValidRecursivelyShrink (GHC.Generics.M1 i c f)
instance Data.GenValidity.GValidRecursivelyShrink GHC.Generics.U1
instance Data.GenValidity.GValidRecursivelyShrink GHC.Generics.V1
instance Data.GenValidity.GGenValid GHC.Generics.U1
instance (Data.GenValidity.GGenValid a, Data.GenValidity.GGenValid b) => Data.GenValidity.GGenValid (a GHC.Generics.:*: b)
instance (Data.GenValidity.GGenValid a, Data.GenValidity.GGenValid b) => Data.GenValidity.GGenValid (a GHC.Generics.:+: b)
instance Data.GenValidity.GGenValid a => Data.GenValidity.GGenValid (GHC.Generics.M1 i c a)