### 3` `Error Handling

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

#### 3.1` `Contracts

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

The 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.rkt").

##### 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 Scheme 4.0 —

Racket was formerly known as PLT Scheme — 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)))))

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

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

Racket 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 naive algorithms.

The Science Collection uses infinities to represent overflow—

The Science Collection uses inexact zero to represent underflow—

The Science Collection uses +nan.0 for domain errors—

#### 3.3` `Exceptions

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

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

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