-- 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:
--   
--   
--   
- genvalidity-aeson
--   
- genvalidity-bytestring
--   
- genvalidity-containers
--   
- genvalidity-path
--   
- genvalidity-scientific
--   
- genvalidity-text
--   
- genvalidity-time
--   
- genvalidity-unordered-containers
--   
- genvalidity-uuid
--   
- genvalidity-vector
--   
@package genvalidity
@version 1.1.1.0

module Data.GenValidity.Utils

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

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

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

-- | 'genSplit4 a' generates a quadruple '(b, c, d, e)' such that 'b + c +
--   d + e' equals a.
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 a.
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 a.
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 a.
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 a.
genSplit8 :: Int -> Gen (Int, Int, Int, Int, Int, Int, Int, Int)

-- | 'arbPartition n' generates a list ls such that 'sum ls'
--   equals n, 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 listOf 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 genNonEmptyOf that returns a list instead of a
--   NonEmpty.
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.
--   
--   
--   
- Some at the border
--   
- Some around zero
--   
- Mostly uniformly
--   
genIntX :: (Integral a, Bounded a, Random a) => Gen a

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

-- | See genFloatX
genFloat :: Gen Float

-- | See genFloatX
genDouble :: Gen Double

-- | Generate floating point numbers smartly:
--   
--   
--   
- Some denormalised
--   
- Some around zero
--   
- Some around the bounds
--   
- Some by encoding an Integer and an Int to a floating point
--   number.
--   
- Some accross the entire range
--   
- Mostly uniformly via the bitrepresentation
--   
--   
--   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 shrinkTuple, but for triples
shrinkTriple :: (a -> [a]) -> (b -> [b]) -> (c -> [c]) -> (a, b, c) -> [(a, b, c)]

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

-- | GenValid exists to make tests involving Validity
--   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:
--   
--   
--   (Prime <$> 'arbitrary') `suchThat` isValid
--   
--   
--   However, this is tedious and inefficient, as well as quite naive
--   (because arbitrary tends to use very naive generators).
--   
--   The GenValid 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
--   GenValid already gives you a generator and shrinking function
--   for free:
--   
--   
--   instance GenValid Prime
--   
--   
--   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:
--   
--   
--   instance GenValid Prime where
--       genValid = Prime <$>
--          (oneof
--            [ pure 2
--            , ((\y -> 2 * abs y + 1) <$> arbitrary) `suchThat` isPrime)
--            ])
--   
--   
--   Typical examples of tests involving validity could look as follows:
--   
--   
--   it "succeeds when given valid input" $ do
--       forAllValid $ \input ->
--           myFunction input `shouldSatisfy` isRight
--   
--   
--   
--   it "produces valid output when it succeeds" $ do
--       forAllValid $ \input ->
--           case myFunction input of
--               Nothing -> return () -- Can happen
--               Just output -> output `shouldSatisfy` isValid
--   
--   
--   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.
--   
--   
How to instantiate GenValid
--   
--   Step 1: Try to instantiate GenValid 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.
--   
--   Step 2: Consider using
--   genValidStructurallyWithoutExtraChecking and
--   shrinkValidStructurallyWithoutExtraFiltering to speed up
--   generation. This only works if your type has a derived or trivial
--   Validity instance.
--   
--   Step 3: 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.
--   
--   
A note about Arbitrary
--   
--   If you also write Arbitrary instances for GenValid
--   types, it may be best to simply use
--   
--   
--   instance Arbitrary A where
--     arbitrary = genValid
--     shrink = shrinkValid
--   
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:
--   
--   
--   genValid = genValidStructurally
--   
--   
--   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:
--   
--   
--   shrinkValid = shrinkValidStructurally
--   
--   
--   It is important that this shrinking function only shrinks values to
--   valid values. If shrinkValid 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
--   Generic instance, and trying that until a valid value has been
--   generated
--   
--   
--   genValidStructurally = genValidStructurallyWithoutExtraChecking `suchThat` isValid
--   
--   
--   This is probably the function that you are looking for. If you do use
--   this function to override genValid, you probably also want to
--   use shrinkValidStructurally to override shrinkValid.
genValidStructurally :: (Validity a, Generic a, GGenValid (Rep a)) => Gen a

-- | Generate a valid value by generating all the sub parts using the
--   Generic instance,
--   
--   This generator is _not_ guaranteed to generate a valid value.
--   
--   This is probably _not_ the function that you are looking for when
--   overriding genValid _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.
--   
--   
--   shrinkValidStructurally = filter isValid . shrinkValidStructurallyWithoutExtraFiltering
--   
--   
--   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 shrinkValid _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
