Packages

  • package root
    Definition Classes
    root
  • package org
    Definition Classes
    root
  • package scalactic
    Definition Classes
    org
  • trait Requirements extends AnyRef

    Trait that contains require, and requireState, and requireNonNull methods for checking pre-conditions that give descriptive error messages extracted via a macro.

    Trait that contains require, and requireState, and requireNonNull methods for checking pre-conditions that give descriptive error messages extracted via a macro.

    These methods of trait Requirements aim to improve error messages provided when a pre-condition check fails at runtime in production code. Although it is recommended practice to supply helpful error messages when doing pre-condition checks, often people don't. Instead of this:

    scala> val length = 5
length: Int = 5

scala> val idx = 6
idx: Int = 6

scala> require(idx >= 0 && idx <= length, "index, " + idx + ", was less than zero or greater than or equal to length, " + length)
java.lang.IllegalArgumentException: requirement failed: index, 6, was less than zero or greater than or equal to length, 5
	at scala.Predef$.require(Predef.scala:233)
	...

    People write simply:

    scala> require(idx >= 0 && idx <= length)
java.lang.IllegalArgumentException: requirement failed
	at scala.Predef$.require(Predef.scala:221)
	...

    Note that the detail message of the IllegalArgumentException thrown by the previous line of code is simply, "requirement failed". Such messages often end up in a log file or bug report, where a better error message can save time in debugging the problem. By importing the members of Requirements (or mixing in its companion trait), you'll get a more helpful error message extracted by a macro, whether or not a clue message is provided:

    scala> import org.scalactic._
import org.scalactic._

scala> import Requirements._
import Requirements._

scala> require(idx >= 0 && idx <= length)
java.lang.IllegalArgumentException: 6 was greater than or equal to 0, but 6 was not less than or equal to 5
	at org.scalactic.Requirements$RequirementsHelper.macroRequire(Requirements.scala:56)
	...

scala> require(idx >= 0 && idx <= length, "(hopefully that helps)")
java.lang.IllegalArgumentException: 6 was greater than or equal to 0, but 6 was not less than or equal to 5 (hopefully that helps)
	at org.scalactic.Requirements$RequirementsHelper.macroRequire(Requirements.scala:56)
	...

    The requireState method provides identical error messages to require, but throws IllegalStateException instead of IllegalArgumentException:

    scala> val connectionOpen = false
connectionOpen: Boolean = false

scala> requireState(connectionOpen)
java.lang.IllegalStateException: connectionOpen was false
	at org.scalactic.Requirements$RequirementsHelper.macroRequireState(Requirements.scala:71)
	...

    Thus, whereas the require methods throw the Java platform's standard exception indicating a passed argument violated a precondition, IllegalArgumentException, the requireState methods throw the standard exception indicating an object's method was invoked when the object was in an inappropriate state for that method, IllegalStateException.

    The requireNonNull method takes one or more variables as arguments and throws NullArgumentException with an error messages that includes the variable names if any are null. Here's an example:

    scala> val e: String = null
e: String = null

scala> val f: java.util.Date = null
f: java.util.Date = null

scala> requireNonNull(a, b, c, d, e, f)
org.scalactic.exceptions.NullArgumentException: e and f were null
	at org.scalactic.Requirements$RequirementsHelper.macroRequireNonNull(Requirements.scala:101)
	...

    Although trait Requirements can help you debug problems that occur in production, bear in mind that a much better alternative is to make it impossible for such events to occur at all. Use the type system to ensure that all pre-conditions are met so that the compiler can find broken pre-conditions and point them out with compiler error messages. When this is not possible or practical, however, trait Requirements is helpful.

    Definition Classes
    scalactic
  • RequirementsHelper
c

org.scalactic.Requirements

RequirementsHelper

class RequirementsHelper extends Serializable

Helper class used by code generated by the require macro.

Source
Requirements.scala
Linear Supertypes
Serializable, Serializable, AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. RequirementsHelper
  2. Serializable
  3. Serializable
  4. AnyRef
  5. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new RequirementsHelper()

Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  6. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  7. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  8. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  9. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  10. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  11. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  12. def macroRequire(bool: Bool, clue: Any): Unit

    Require that the passed in Bool is true, else fail with IllegalArgumentException.

    Require that the passed in Bool is true, else fail with IllegalArgumentException.

    bool

    the Bool to check as requirement

    clue

    optional clue to be included in IllegalArgumentException's error message when the requirement failed

  13. def macroRequireNonNull(variableNames: Array[String], arguments: Array[Any], prettifier: Prettifier, pos: Position): Unit

    Require that all of the passed in arguments are not null, else fail with NullArgumentException.

    Require that all of the passed in arguments are not null, else fail with NullArgumentException.

    variableNames

    names of variable passed as appear in source

    arguments

    arguments to check for null value

  14. def macroRequireState(bool: Bool, clue: Any): Unit

    Require that the passed in Bool is true, else fail with IllegalStateException.

    Require that the passed in Bool is true, else fail with IllegalStateException.

    bool

    the Bool to check as requirement

    clue

    optional clue to be included in IllegalStateException's error message when the requirement failed

  15. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  16. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  17. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  18. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  19. def toString(): String
    Definition Classes
    AnyRef → Any
  20. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  21. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  22. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )

Inherited from Serializable

Inherited from Serializable

Inherited from AnyRef

Inherited from Any

Ungrouped