Generator

Some simple, "ordinary" values of type T.

canonicals are used for certain higher-order functions, mainly during shrink. For example, when the system is trying to simplify a List[T], it will look for canonical values of T to try putting into that simpler list, to see if that still causes the property to fail.

For example, a few of the common types provide these canonicals:

• Int: 0, 1, -1, 2, -2, 3, -3
• Char: the letters and digits
• String: single-charactor Strings of the letter and digits

You do not have to provide canonicals for a Generator. By default, this simply returns an empty LazyListOrStream.

This function takes a Randomizer to use as a parameter, in case canonical generation for this type has a random element to it. If you use this Randomizer, return the ''next'' one. If you don't use it, just use the passed-in one.

Some simple, "ordinary" values of type T.

canonicals are used for certain higher-order functions, mainly during shrink. For example, when the system is trying to simplify a List[T], it will look for canonical values of T to try putting into that simpler list, to see if that still causes the property to fail.

For example, a few of the common types provide these canonicals:

• Int: 0, 1, -1, 2, -2, 3, -3
• Char: the letters and digits
• String: single-charactor Strings of the letter and digits

You do not have to provide canonicals for a Generator. By default, this simply returns an empty LazyListOrStream.

This function takes a Randomizer to use as a parameter, in case canonical generation for this type has a random element to it. If you use this Randomizer, return the ''next'' one. If you don't use it, just use the passed-in one.

Some simple, "ordinary" values of type T.

canonicals are used for certain higher-order functions, mainly during shrink. For example, when the system is trying to simplify a List[T], it will look for canonical values of T to try putting into that simpler list, to see if that still causes the property to fail.

For example, a few of the common types provide these canonicals:

• Int: 0, 1, -1, 2, -2, 3, -3
• Char: the letters and digits
• String: single-charactor Strings of the letter and digits

You do not have to provide canonicals for a Generator. By default, this simply returns an empty LazyListOrStream.

This function takes a Randomizer to use as a parameter, in case canonical generation for this type has a random element to it. If you use this Randomizer, return the ''next'' one. If you don't use it, just use the passed-in one.

Support for filtering in for comprehensions.

This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.

It is closely related to Generator.withFilter, but is the older form.

The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.

You generally should not need to override this.

Support for filtering in for comprehensions.

This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.

It is closely related to Generator.withFilter, but is the older form.

The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.

You generally should not need to override this.

Support for filtering in for comprehensions.

This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.

It is closely related to Generator.withFilter, but is the older form.

The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.

You generally should not need to override this.

The usual Monad function, to allow Generators to be composed together.

This is primarily here to support the ability to create new Generators easily using for comprehensions. For example, say that you needed a Generator that produces a Tuple of an Int and a Float. You can write that easily:

 val tupleGen =
   for {
     a <- Generator.intGenerator
     b <- Generator.floatGenerator
   }
     yield (a, b)

That is, flatMap takes a function that returns a Generator, and combines it with ''this'' Generator, to produce a new Generator. That function ''may'' make use of a value from this Generator (that is part of the standard contract of flatMap), but usually does not.

The usual Monad function, to allow Generators to be composed together.

This is primarily here to support the ability to create new Generators easily using for comprehensions. For example, say that you needed a Generator that produces a Tuple of an Int and a Float. You can write that easily:

 val tupleGen =
   for {
     a <- Generator.intGenerator
     b <- Generator.floatGenerator
   }
     yield (a, b)

That is, flatMap takes a function that returns a Generator, and combines it with ''this'' Generator, to produce a new Generator. That function ''may'' make use of a value from this Generator (that is part of the standard contract of flatMap), but usually does not.

The usual Monad function, to allow Generators to be composed together.

This is primarily here to support the ability to create new Generators easily using for comprehensions. For example, say that you needed a Generator that produces a Tuple of an Int and a Float. You can write that easily:

 val tupleGen =
   for {
     a <- Generator.intGenerator
     b <- Generator.floatGenerator
   }
     yield (a, b)

That is, flatMap takes a function that returns a Generator, and combines it with ''this'' Generator, to produce a new Generator. That function ''may'' make use of a value from this Generator (that is part of the standard contract of flatMap), but usually does not.

Prepare a list of edge-case values ("edges") for testing this type.

The contents of this list are entirely up to the Generator. It is allowed to be empty, but it is a good idea to think about whether there are appropriate edge cases for this type. (By default, this is empty, so you can get your Generator working first, and think about edge cases after that.)

It is common, but not required, to randomize the order of the edge cases here. If so, you should use the Randomizer.shuffle function for this, so that the order is reproducible if something fails. If you don't use the Randomizer, just return it unchanged as part of the returned tuple.

Note the ''maxLength'' parameter. This is the number of tests to be run in total. So the list of returned edges should be no longer than this.

Prepare a list of edge-case values ("edges") for testing this type.

The contents of this list are entirely up to the Generator. It is allowed to be empty, but it is a good idea to think about whether there are appropriate edge cases for this type. (By default, this is empty, so you can get your Generator working first, and think about edge cases after that.)

It is common, but not required, to randomize the order of the edge cases here. If so, you should use the Randomizer.shuffle function for this, so that the order is reproducible if something fails. If you don't use the Randomizer, just return it unchanged as part of the returned tuple.

Note the ''maxLength'' parameter. This is the number of tests to be run in total. So the list of returned edges should be no longer than this.

Prepare a list of edge-case values ("edges") for testing this type.

The contents of this list are entirely up to the Generator. It is allowed to be empty, but it is a good idea to think about whether there are appropriate edge cases for this type. (By default, this is empty, so you can get your Generator working first, and think about edge cases after that.)

It is common, but not required, to randomize the order of the edge cases here. If so, you should use the Randomizer.shuffle function for this, so that the order is reproducible if something fails. If you don't use the Randomizer, just return it unchanged as part of the returned tuple.

Note the ''maxLength'' parameter. This is the number of tests to be run in total. So the list of returned edges should be no longer than this.

Given a function from types T to U, return a new Generator that produces values of type U.

For example, say that you needed a Generator that only creates even Ints. We already have Generator.intGenerator, so one way to write this would be:

 val evenGen: Generator[Int] = Generator.intGenerator.map { i =>
   val mod = i % 2
   if ((mod == 1) || (mod == -1))
     // It is odd, so the one before it is even:
     i - 1
   else
     // Already even
     i
 }

This often makes it much easier to create a new Generator, if you have an existing one you can base it on.

Given a function from types T to U, return a new Generator that produces values of type U.

For example, say that you needed a Generator that only creates even Ints. We already have Generator.intGenerator, so one way to write this would be:

 val evenGen: Generator[Int] = Generator.intGenerator.map { i =>
   val mod = i % 2
   if ((mod == 1) || (mod == -1))
     // It is odd, so the one before it is even:
     i - 1
   else
     // Already even
     i
 }

This often makes it much easier to create a new Generator, if you have an existing one you can base it on.

Given a function from types T to U, return a new Generator that produces values of type U.

For example, say that you needed a Generator that only creates even Ints. We already have Generator.intGenerator, so one way to write this would be:

 val evenGen: Generator[Int] = Generator.intGenerator.map { i =>
   val mod = i % 2
   if ((mod == 1) || (mod == -1))
     // It is odd, so the one before it is even:
     i - 1
   else
     // Already even
     i
 }

This often makes it much easier to create a new Generator, if you have an existing one you can base it on.

Produce the next value for this Generator.

This is the heart and soul of Generator -- it is the one function that you are required to implement when creating a new one. It takes several fields describing the state of the current evaluation, and returns the next value to try, along with the new state.

The state consists of three fields:

• The ''size'' to generate, if that is meaningful for this Generator.
• The ''remaining'' edge cases that need to be generated. In general, if this List is non-empty, you should simply return the next item on the List.
• The current Randomizer. If you need to generate random information, use this to do so.

This function returns a Tuple of three fields:

• The next value of type T to try evaluating.
• The remaining edges ''without'' the one that you are using. That is, if this function received a non-empty edges List, it should usually return the head as the next value, and the tail as the remainder after that.
• If you used the passed-in Randomizer, return the one you got back from that function. (Note that all Randomizer functions return a new Randomizer. If you didn't use it, just return the one that was passed in.

Produce the next value for this Generator.

This is the heart and soul of Generator -- it is the one function that you are required to implement when creating a new one. It takes several fields describing the state of the current evaluation, and returns the next value to try, along with the new state.

The state consists of three fields:

• The ''size'' to generate, if that is meaningful for this Generator.
• The ''remaining'' edge cases that need to be generated. In general, if this List is non-empty, you should simply return the next item on the List.
• The current Randomizer. If you need to generate random information, use this to do so.

This function returns a Tuple of three fields:

• The next value of type T to try evaluating.
• The remaining edges ''without'' the one that you are using. That is, if this function received a non-empty edges List, it should usually return the head as the next value, and the tail as the remainder after that.
• If you used the passed-in Randomizer, return the one you got back from that function. (Note that all Randomizer functions return a new Randomizer. If you didn't use it, just return the one that was passed in.

Produce the next value for this Generator.

This is the heart and soul of Generator -- it is the one function that you are required to implement when creating a new one. It takes several fields describing the state of the current evaluation, and returns the next value to try, along with the new state.

The state consists of three fields:

• The ''size'' to generate, if that is meaningful for this Generator.
• The ''remaining'' edge cases that need to be generated. In general, if this List is non-empty, you should simply return the next item on the List.
• The current Randomizer. If you need to generate random information, use this to do so.

This function returns a Tuple of three fields:

• The next value of type T to try evaluating.
• The remaining edges ''without'' the one that you are using. That is, if this function received a non-empty edges List, it should usually return the head as the next value, and the tail as the remainder after that.
• If you used the passed-in Randomizer, return the one you got back from that function. (Note that all Randomizer functions return a new Randomizer. If you didn't use it, just return the one that was passed in.

Fetch a generated value of type T.

sample allows you to experiment with this Generator in a convenient, ad-hoc way. Each time you call it, it will create a new Randomizer and a random size, and then calls next to generate a value.

You should not need to override this method; it is here to let you play with your Generator as you build it, and see what sort of values are actually coming out.

Fetch a generated value of type T.

sample allows you to experiment with this Generator in a convenient, ad-hoc way. Each time you call it, it will create a new Randomizer and a random size, and then calls next to generate a value.

You should not need to override this method; it is here to let you play with your Generator as you build it, and see what sort of values are actually coming out.

Fetch a generated value of type T.

sample allows you to experiment with this Generator in a convenient, ad-hoc way. Each time you call it, it will create a new Randomizer and a random size, and then calls next to generate a value.

You should not need to override this method; it is here to let you play with your Generator as you build it, and see what sort of values are actually coming out.

Generate a number of values of type T.

This is essentially the same as sample, and all the same comments apply, but this will generate as many values as you ask for.

Generate a number of values of type T.

This is essentially the same as sample, and all the same comments apply, but this will generate as many values as you ask for.

Generate a number of values of type T.

This is essentially the same as sample, and all the same comments apply, but this will generate as many values as you ask for.

Support for filtering in for comprehensions.

This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.

The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.

You generally should not need to override this.

Support for filtering in for comprehensions.

This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.

The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.

You generally should not need to override this.

Support for filtering in for comprehensions.

This means the same thing is does for all standard Scala Monads: it applies a filter function to this Generator. If you use an if clause in a for comprehension, this is the function that will be called.

The default implementation of this has a safety check, such that if an enormous number of values (100000 by default) are rejected by the filter in a row, it aborts in order to prevent infinite loops. If this occurs, you should probably rewrite your generator to not use a filter.

You generally should not need to override this.