On this page:
3.1 Contracts
3.1.1 Fixed Number of Arguments with a Single Result
3.1.2 Multiple Lambda Forms (case-lambda)
3.1.3 Interparameter Constraints
3.2 Infinities and Not-a-Number
3.3 Exceptions
Version: 4.2.1

3 Error Handling

    3.1 Contracts

      3.1.1 Fixed Number of Arguments with a Single Result

      3.1.2 Multiple Lambda Forms (case-lambda)

      3.1.3 Interparameter Constraints

    3.2 Infinities and Not-a-Number

    3.3 Exceptions

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.

  (provide/contract
   (mean
    (-> (vectorof real?) real?)))
This contract specifies a function with one argument that must match the contract (vectorof real?) and returns a single result that must match the contract real?.

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

  (provide/contract
   (variance
    (case-> (-> (vectorof real?) real? (>=/c 0.0))
            (-> (vectorof real?) (>=/c 0.0)))))
The contract specifies multiple lambda forms using case->. The first case specifies a function with two arguments, data and mu, that must match the contracts (vectorof real?) and real? and returns a single value that must match the contract (>=/c 0.0). The second case specifies a function with a single argument, data that muct match the contract (vectorof real?) and returns a single result that must match the contract (>=/c 0.0).

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

  (provide/contract
   (weighted-mean
    (-> ((w (vectorof real?))
         (data (and/c (vectorof real?)
                      (lambda (x)
                        (= (vector-length w)
                           (vector-length data)))))))))
The contract specified a function that takes two arguments. The first argument, w must be a vector of real numbers. The second argument, data, must be a vector of real numbers that must be the same length as w. The function returns one result that must match the contract real?.

> (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.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:

Note that some of these may break naÏve 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.