3 Error Handling

This chapter describes how error handling is performed in the PLT Scheme Science Collection and its error handling conventions.

3.1 Contracts

For more information, see Contracts in the PLT Scheme Reference Manual or Contracts in the PLT Scheme Guide.

The PLT Scheme Science Collection uses contracts to define and enforce the interfaces for all of the functions provided by the modules in the collection. This ensures that all calls to these functions are checked for proper number and type of arguments (and results), as well as range checking and interargument constraints, where practical.

All of the function definitions in the manual include a specification of the contract for the function.

The following examples show some of the different contract specifications for functions and how to interpret them. All of these examples are from the statistics module ("statistics.ss").

3.1.1 Fixed Number of Arguments with a Single Result

Example: mean from the statistics module.

> (require (planet williams/science/statistics))

> (mean #(1 2 3 4))

2.5

> (mean #(1 2 5 a))

top-level broke the contract (-> (vectorof real?) real?) on mean; expected <(vectorof real?)>, given: #(1 2 5 a)

3.1.2 Multiple Lambda Forms (case-lambda)

Example: variance from the statistics module.

PLT Schme 4.0 introduced direct support of optional arguments in lambda. At some point, the uses of multiple lambda forms to specify optional arguments will be converted to single lambda forms with optional arguments.

> (require (planet williams/science/statistics))

> (variance #(1 2 3 4))

1.6666666666666665

> (variance #(1 2 3 4) 2.5)

1.6666666666666665

> (variance #(1 2 3 4) 'a)

top-level broke the contract

(case->

(-> (vectorof real?) real? (>=/c 0.0))

(-> (vectorof real?) (>=/c 0.0)))

on variance; expected <real?>, given: a

3.1.3 Interparameter Constraints

Example: weighted-mean from the statistics module.

> (require (planet williams/science/statistics))

> (weighted-mean #(1 2 3 4) #(4 3 2 1))

2.0

> (weighted-mean #(1 2 3 4) #(4 3 2))

top-level broke the contract

(->r ((w ...) (data ...)) ...)

on weighted-mean; expected <(and/c (vectorof real?) ...\0\statistics.ss:152:21)>, given: #(4 3 2)

3.1.4 Unchecked Operations

Constraint checking does incur an execution-time penalty that the user may wish to avoid. For example, the algorithm for the median-from-sorted-data function has a computation complexity of O(1), but the constraint check to insure the input is indeed a sorted sequence has a computational complexity of O(n). Many of the routines in the science collection have a unchecked variant that avoids the constraint check. These functions have "unchecked-" prepended to the corresponding function name. For example, unchecked-median-from-sorted-data does not check its argument’s constraints.

In general, constraint checking is a good thing. The unchecked versions of functions should only be called when it is known that the arguments do indeed meet their constraints. As of Version 4.0 of the PLT Scheme Science Collection, some operations internally use ’unsafe’ operations for efficiency. Arguments that don’t match their constraints may result in crashing the run-time system.

3.2 Infinities and Not-a-Number

PLT Scheme provides +inf.0 (positive infinity), -inf.0 (negative infinity), +nan.0 (not-a-number), and +nan.0 (same as +nan.0). In general these are contagious and are passed as the result in subsequent numerical computations. However, operations with infinities and zero (both exact and inecact) can give non-intuitive results. For example:

• (* 0 +inf.0) → 0

• (/ 0 +inf.0) → 0

• (/ 0 -inf.0) → 0

• (* 0.0 +inf.0) → +nan.0

• (/ 0.0 -inf.0) → -0.0

Note that some of these may break naive algorithms.

The PLT Scheme Science Collection uses infinities to represent overflow – +inf.0 for positive overflow and -inf.0 for negative overflow. This is used in cases where the arguments to the function are within the range of the function, but the (absolute value of) result is too large to be represented. For example, (gamma 200.0) → +inf.0.

The PLT Scheme Science Collection uses inexact zero to represent underflow – 0.0 for positive underflow and -0.0 for negative underflow. This is used in cases where the arguments to the function are within the range of the function, but the (absolute value of) the result is too small to be represented.

The PLT Scheme Science Collection uses +nan.0 for domain errors – where the arguments match the contract, but the value cannot be computed. For example (gamma 0.0) → +nan.0.

3.3 Exceptions

In PLT Scheme, an exception is a change in control flow, typically as the result of an error.

The PLT Scheme Science Collection attempts to catch as many errors as possible using contracts. Contracts raise exceptions when violated.

The PLT Scheme Science Collection may raise exceptions for errors other than underflow, overflow, and domain errors. Also, the underlying functions and/or modules used by the science collection may raise exceptions, as may errors in the implementation.