# 9 Pattern Matching
|  |  |  |  |  |  |  |
|---------|-----|-----|-----|-----------------------------------------|-----|----------------------------------------------------------------------------------------------------------------------------------|
| pat  |    | ::= |    | id  |    | match anything, bind identifier  |
|    |    |  \| |    | (var id)  |    | match anything, bind identifier  |
|    |    |  \| |    | \_  |    | match anything  |
|    |    |  \| |    | literal  |    | match literal  |
|    |    |  \| |    | (quote datum)  |    | match equal? value  |
|    |    |  \| |    | (list lvp ...)  |    | match sequence of lvps  |
|    |    |  \| |    | (list-rest lvp ... pat)  |    | match lvps consed onto a pat  |
|    |    |  \| |    | (list\* lvp ... pat)  |    | match lvps consed onto a pat  |
|    |    |  \| |    | (list-no-order pat ...)  |    | match pats in any order  |
|    |    |  \| |    | (list-no-order pat ... lvp)  |    | match pats in any order  |
|    |    |  \| |    | (vector lvp ...)  |    | match vector of pats  |
|    |    |  \| |    | (hash expr pat ... ... ht-opt)  |    | match hash table  |
|    |    |  \| |    | (hash\* \[expr pat kv-opt\] ... ht-opt) |    | match hash table  |
|    |    |  \| |    | (hash-table (pat pat) ...)  |    | match hash table - deprecated  |
|    |    |  \| |    | (hash-table (pat pat) ...+ ooo)  |    | match hash table - deprecated  |
|    |    |  \| |    | (cons pat pat)  |    | match pair of pats  |
|    |    |  \| |    | (mcons pat pat)  |    | match mutable pair of pats  |
|    |    |  \| |    | (box pat)  |    | match boxed pat  |
|    |    |  \| |    | (struct-id pat ...)  |    | match struct-id instance  |
|    |    |  \| |    | (struct struct-id (pat ...))  |    | match struct-id instance  |
|    |    |  \| |    | (regexp rx-expr)  |    | match string  |
|    |    |  \| |    | (regexp rx-expr pat)  |    | match string, result with pat  |
|    |    |  \| |    | (pregexp px-expr)  |    | match string  |
|    |    |  \| |    | (pregexp px-expr pat)  |    | match string, result with pat  |
|    |    |  \| |    | (and pat ...)  |    | match when all pats match  |
|    |    |  \| |    | (or pat ...)  |    | match when any pat match  |
|    |    |  \| |    | (not pat ...)  |    | match when no pat matches  |
|    |    |  \| |    | (app expr pats ...)  |    | match (expr value) output values to pats  |
|    |    |  \| |    | (? expr pat ...)  |    | match if (expr value) and pats  |
|    |    |  \| |    | (quasiquote qp)  |    | match a quasipattern  |
|    |    |  \| |    | derived-pattern  |    | match using extension  |
| literal |    | ::= |    | #t  |    | match true  |
|    |    |  \| |    | #f  |    | match false  |
|    |    |  \| |    | string  |    | match equal? string  |
|    |    |  \| |    | bytes  |    | match equal? byte string  |
|    |    |  \| |    | number  |    | match equal? number  |
|    |    |  \| |    | char  |    | match equal? character  |
|    |    |  \| |    | keyword  |    | match equal? keyword  |
|    |    |  \| |    | regexp  |    | match equal? regexp literal  |
|    |    |  \| |    | pregexp  |    | match equal? pregexp literal |
| lvp  |    | ::= |    | pat ooo  |    | greedily match pat instances  |
|    |    |  \| |    | pat  |    | match pat  |
| qp  |    | ::= |    | literal  |    | match literal  |
|    |    |  \| |    | id  |    | match symbol  |
|    |    |  \| |    | (qp ...)  |    | match sequences of qps  |
|    |    |  \| |    | (qp ... . qp)  |    | match qps ending qp  |
|    |    |  \| |    | (qp ooo . qp)  |    | match qps beginning with repeated qp  |
|    |    |  \| |    | #(qp ...)  |    | match vector of qps  |
|    |    |  \| |    | #&qp  |    | match boxed qp  |
|    |    |  \| |    | #s(prefab-key qp ...)  |    | match prefab struct with qp fields  |
|    |    |  \| |    | ,pat  |    | match pat  |
|    |    |  \| |    | ,@(list lvp ...)  |    | match lvps, spliced  |
|    |    |  \| |    | ,@(list-rest lvp ... pat)  |    | match lvps plus pat, spliced  |
|    |    |  \| |    | ,@'qp  |    | match list-matching qp, spliced  |
| ooo  |    | ::= |    | ...  |    | zero or more; ... is literal  |
|    |    |  \| |    | \_\_\_  |    | zero or more  |
|    |    |  \| |    | ..k  |    | k or more  |
|    |    |  \| |    | \_\_k  |    | k or more  |
| kv-opt  |    | ::= |    |  |    | key must exist  |
|    |    |  \| |    | #:default def-expr  |    | key may not exist; match def-expr with the value pattern  |
| ht-opt  |    | ::= |    |  |    | default mode  |
|    |    |  \| |    | #:closed  |    | closed to extension mode  |
|    |    |  \| |    | #:open  |    | open to extension mode  |
|    |    |  \| |    | #:rest pat  |    | residue mode  |


# 9 Pattern Matching
In more detail, patterns match as follows:
-
id (excluding the reserved names \_, ..., \_\_\_, ..k, and \_\_k for non-negative integers k)
> > > Unlike in cond and case, else is not a keyword in match. Use the \_ pattern for the “else” clause.
or (var id) — matches anything, and binds id to the matching values. If an id is used multiple times within a pattern, the corresponding matches must be the same according to (match-equality-test), except that instances of an id in different or and not sub-patterns are independent. The binding for id is not available in other parts of the same pattern.
Examples:
> ```racket
> > ( match ' ( 1 2 3 ) [ ( list a b a ) ( list a b ) ] [ ( list a b c ) ( list c b a ) ] )
> '(3 2 1)
> > ( match ' ( 1 ( x y z ) 1 ) [ ( list a b a ) ( list a b ) ] [ ( list a b c ) ( list c b a ) ] )
> '(1 (x y z))
> > ( match #f [ else ( cond [ #f ' not-evaluated ] [ else ' also-not-evaluated ] ) ] )
> ```
-  \_ — matches anything, without binding any identifiers.
Example:
> ```racket
> > ( match ' ( 1 2 3 ) [ ( list _ _ a ) a ] )
> 3
> ```
-  #t, #f, string, bytes, number, char, or (quote datum) — matches an equal? constant.
Example:
> ```racket
> > ( match "yes" [ "no" #f ] [ "yes" #t ] )
> #t
> ```
-  (list lvp ...) — matches a list of elements. In the case of (list pat ...), the pattern matches a list with as many elements as pats, and each element must match the corresponding pat. In the more general case, each lvp corresponds to a “spliced” list of greedy matches.


# 9 Pattern Matching
For spliced lists, ... and \_\_\_ are aliases for zero or more matches. The ..k and \_\_k forms are also aliases, specifying k or more matches. Pattern variables that precede these splicing operators are bound to lists of matching forms.
Examples:
> ```racket
> > ( match ' ( 1 2 3 ) [ ( list a b c ) ( list c b a ) ] )
> '(3 2 1)
> > ( match ' ( 1 2 3 ) [ ( list 1 a ... ) a ] )
> '(2 3)
> > ( match ' ( 1 2 3 ) [ ( list 1 a ..3 ) a ] [ _ ' else ] )
> 'else
> > ( match ' ( 1 2 3 4 ) [ ( list 1 a ..3 ) a ] [ _ ' else ] )
> '(2 3 4)
> > ( match ' ( 1 2 3 4 5 ) [ ( list 1 a ..3 5 ) a ] [ _ ' else ] )
> '(2 3 4)
> > ( match ' ( 1 ( 2 ) ( 2 ) ( 2 ) 5 ) [ ( list 1 ( list a ) ..3 5 ) a ] [ _ ' else ] )
> '(2 2 2)
> ```
-  (list-rest lvp ... pat) or (list\* lvp ... pat) — similar to a list pattern, but the final pat matches the “rest” of the list after the last lvp. In fact, the matched value can be a non-list chain of pairs (i.e., an “improper list”) if pat matches non-list values.
Examples:
> ```racket
> > ( match ' ( 1 2 3 . 4 ) [ ( list-rest a b c d ) d ] )
> 4
> > ( match ' ( 1 2 3 . 4 ) [ ( list-rest a ... d ) ( list a d ) ] )
> '((1 2 3) 4)
> ```
-  (list-no-order pat ...) — similar to a list pattern, but the elements to match each pat can appear in the list in any order.
Example:
> ```racket
> > ( match ' ( 1 2 3 ) [ ( list-no-order 3 2 x ) x ] )
> 1
> ```


# 9 Pattern Matching
> > > Unlike other patterns, list-no-order doesn’t allow duplicate identifiers between subpatterns. For example the patterns (list-no-order x 1 x) and (list-no-order x 1 x ...) both produce syntax errors.
-  (list-no-order pat ... lvp) — generalizes list-no-order to allow a pattern that matches multiple list elements that are interspersed in any order with matches for the other patterns.
Example:
> ```racket
> > ( match ' ( 1 2 3 4 5 6 ) [ ( list-no-order 6 2 y ... ) y ] )
> '(1 3 4 5)
> ```
-  (vector lvp ...) — like a list pattern, but matching a vector.
Example:
> ```racket
> > ( match # ( 1 ( 2 ) ( 2 ) ( 2 ) 5 ) [ ( vector 1 ( list a ) ..3 5 ) a ] )
> '(2 2 2)
> ```
-  (hash expr pat ... ... ht-opt) — matches against a hash table where expr matches a key and pat matches a corresponding value.
Examples:
> ```racket
> > ( match ( hash "aa" 1 "b" 2 ) [ ( hash "b" b ( string-append "a" "a" ) a ) ( list b a ) ] )
> '(2 1)
> > ( match ( hash "aa" 1 "b" 2 ) [ ( hash "b" _ "c" _ ) ' matched ] [ _ ' not-matched ] )
> 'not-matched
> ```
The key matchings use the key comparator of the matching hash table.
Examples:
> ```racket
> > ( let ( [ k ( string-append "a" "b" ) ] ) ( match ( hasheq "ab" 1 ) [ ( hash k v ) ' matched ] [ _ ' not-matched ] ) )
> 'not-matched
> > ( let ( [ k ( string-append "a" "b" ) ] ) ( match ( hasheq k 1 ) [ ( hash k v ) ' matched ] [ _ ' not-matched ] ) )
> 'matched
> ```
The behavior of residue key-value entries in the hash table value depends on ht-opt.


# 9 Pattern Matching
When ht-opt is not provided or when it is #:closed, all of the keys in the hash table value must be matched. I.e., the matching is closed to extension.
Example:
> ```racket
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash "b" _ ) ' matched ] [ _ ' not-matched ] )
> 'not-matched
> ```
When ht-opt is #:open, there can be keys in the hash table value that are not specified in the pattern. I.e., the matching is open to extension.
Example:
> ```racket
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash "b" _ #:open ) ' matched ] [ _ ' not-matched ] )
> 'matched
> ```
When ht-opt is #:rest pat, pat is further matched against the residue hash table. If the matching hash table is immutable, this residue matching is efficient. Otherwise, the matching hash table will be copied, which could be expensive.
Example:
> ```racket
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash "b" _ #:rest ( hash "a" a ) ) a ] [ _ #f ] )
> 1
> ```
Many key exprs could evaluate to the same value.
Example:
> ```racket
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash "b" _ "b" 2 "a" _ ) ' matched ] [ _ ' not-matched ] )
> 'matched
> ```
-  (hash\* \[expr pat kv-opt\] ... ht-opt) — similar to hash, but with the following differences:
-  The key-value pattern must be grouped syntactically.
-  If ht-opt is not specified, it behaves like #:open (as opposed to #:closed).
-  If kv-opt is specified with #:default def-expr, and the key does not exist in the hash table value, then the default value from def-expr will be matched against the value pattern, instead of immediately failing to match.
Examples:


# 9 Pattern Matching
> ```racket
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash* [ "b" b ] [ "a" a ] ) ( list b a ) ] )
> '(2 1)
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash* [ "b" b ] ) ' matched ] [ _ ' not-matched ] )
> 'matched
> > ( match ( hash "a" 1 "b" 2 ) [ ( hash* [ "a" a #:default 42 ] [ "c" c #:default 100 ] ) ( list a c ) ] [ _ #f ] )
> '(1 100)
> ```
-  (hash-table (pat pat) ...) — This pattern is deprecated because it can be incorrect. However, many programs rely on the incorrect behavior, so we still provide this pattern for backward compatibility reasons.
Similar to list-no-order, but matching against hash table’s key–value pairs.
Example:
> ```racket
> > ( match #hash ( ( "a" . 1 ) ( "b" . 2 ) ) [ ( hash-table ( "b" b ) ( "a" a ) ) ( list b a ) ] )
> '(2 1)
> ```
-  (hash-table (pat pat) ...+ ooo) — This pattern is deprecated because it can be incorrect. However, many programs rely on the incorrect behavior, so we still provide this pattern for backward compatibility reasons.
Generalizes hash-table to support a final repeating pattern.
Example:
> ```racket
> > ( match #hash ( ( "a" . 1 ) ( "b" . 2 ) ) [ ( hash-table ( key val ) ... ) key ] )
> '("b" "a")
> ```
-  (cons pat1 pat2) — matches a pair value.
Example:
> ```racket
> > ( match ( cons 1 2 ) [ ( cons a b ) ( + a b ) ] )
> 3
> ```
-  (mcons pat1 pat2) — matches a mutable pair value.
Example:
> ```racket
> > ( match ( mcons 1 2 ) [ ( cons a b ) ' immutable ] [ ( mcons a b ) ' mutable ] )
> 'mutable
> ```
-  (box pat) — matches a boxed value.
Example:
> ```racket
> > ( match #& 1 [ ( box a ) a ] )
> 1
> ```


# 9 Pattern Matching
-  (struct-id pat ...) or (struct struct-id (pat ...)) — matches an instance of a structure type named struct-id, where each field in the instance matches the corresponding pat. See also struct*.
Usually, struct-id is defined with struct. More generally, struct-id must be bound to expansion-time information for a structure type (see Structure Type Transformer Binding), where the information includes at least a predicate binding and field accessor bindings corresponding to the number of field pats. In particular, a module import or a unit import with a signature containing a struct declaration can provide the structure type information.
Examples:
> ```racket
> ( struct tree ( val left right ) )
> > ( match ( tree 0 ( tree 1 #f #f ) #f ) [ ( tree a ( tree b _ _ ) _ ) ( list a b ) ] )
> '(0 1)
> ```
-  (struct struct-id _) — matches any instance of struct-id, without regard to contents of the fields of the instance.
-  (regexp rx-expr) — matches a string that matches the regexp pattern produced by rx-expr, where rx-expr can be either a regexp, a pregexp, a byte-regexp, a byte-pregexp, a string, or a byte string. A string and byte string value is converted to a pattern using regexp and byte-regexp respectively. See Regular Expressions for more information about regexps.
Examples:


# 9 Pattern Matching
> ```racket
> > ( match "apple" [ ( regexp #rx"p+" ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match "banana" [ ( regexp #px"(na){2}" ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match "banana" [ ( regexp "(na){2}" ) ' yes ] [ _ ' no ] )
> 'no
> > ( match #"apple" [ ( regexp #rx#"p+" ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match #"banana" [ ( regexp #px#"(na){2}" ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match #"banana" [ ( regexp #"(na){2}" ) ' yes ] [ _ ' no ] )
> 'no
> ```
-  (regexp rx-expr pat) — extends the regexp form to further constrain the match where the result of regexp-match is matched against pat.
Examples:
> ```racket
> > ( match "apple" [ ( regexp #rx"p+(.)" ( list _ "l" ) ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match "append" [ ( regexp #rx"p+(.)" ( list _ "l" ) ) ' yes ] [ _ ' no ] )
> 'no
> ```
-  (pregexp rx-expr) or (pregexp rx-expr pat) — like the regexp patterns, but rx-expr must be either a pregexp, a byte-pregexp, a string, or a byte string. A string and byte string value is converted to a pattern using pregexp and byte-pregexp respectively.
-  (and pat ...) — matches if all of the pats match. This pattern is often used as (and id pat) to bind id to the entire value that matches pat. The pats are matched in the order that they appear.
Example:
> ```racket
> > ( match ' ( 1 ( 2 3 ) 4 ) [ ( list _ ( and a ( list _ ... ) ) _ ) a ] )
> '(2 3)
> ```
-  (or pat ...) — matches if any of the pats match. Each pat must bind the same set of identifiers.
Example:
> ```racket
> > ( match ' ( 1 2 ) [ ( or ( list a 1 ) ( list a 2 ) ) a ] )
> 1
> ```


# 9 Pattern Matching
-  (not pat ...) — matches when none of the pats match, and binds no identifiers.
Examples:
> ```racket
> > ( match ' ( 1 2 3 ) [ ( list ( not 4 ) ... ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match ' ( 1 4 3 ) [ ( list ( not 4 ) ... ) ' yes ] [ _ ' no ] )
> 'no
> ```
-  (app expr pats ...) — applies expr to the value to be matched; each result of the application is matched against one of the pats, respectively.
Examples:
> ```racket
> > ( match ' ( 1 2 ) [ ( app length 2 ) ' yes ] )
> 'yes
> > ( match "3.14" [ ( app string  →  number ( ? number? pi ) ) ` ( I got , pi ) ] )
> '(I got 3.14)
> > ( match ' ( 1 2 ) [ ( app ( lambda ( v ) ( split-at v 1 ) ) ' ( 1 ) ' ( 2 ) ) ' yes ] )
> 'yes
> > ( match ' ( 1 2 3 ) [ ( app ( λ ( ls ) ( apply values ls ) ) x y ( ? odd? z ) ) ( list ' yes x y z ) ] )
> '(yes 1 2 3)
> ```
-  (? expr pat ...) — applies expr to the value to be matched, and checks whether the result is a true value; the additional pats must also match; i.e., ? combines a predicate application and an and pattern. However, ?, unlike and, guarantees that expr is matched before any of the pats.
> > > The expr procedure may be called more than once on identical input (although this happens only rarely), and the order in which calls to expr are made should not be relied upon.
Example:
> ```racket
> > ( match ' ( 1 3 5 ) [ ( list ( ? odd? ) ... ) ' yes ] )
> 'yes
> ```
-  (quasiquote qp) — introduces a quasipattern, in which identifiers match symbols. Like the quasiquote expression form, unquote and unquote-splicing escape back to normal patterns.
Example:


# 9 Pattern Matching
> ```racket
> > ( match ' ( 1 2 3 ) [ ` ( 1 , a , ( ? odd? b ) ) ( list a b ) ] )
> '(2 3)
> ```
-  derived-pattern — matches a pattern defined by a macro extension via define-match-expander.
Note that the matching process may destructure the input multiple times, and may evaluate expressions embedded in patterns such as (app expr pat) in arbitrary order, or multiple times. Therefore, such expressions must be safe to call multiple times, or in an order other than they appear in the original program.
Changed in version 8.9.0.5 of package base: Added a support for #:do.
Changed in version 8.11.1.10: Added the hash and hash\* patterns.


### 9.1 Additional Matching Forms
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

(match* (val-expr ...+) clause* ...)

clause*	 	=	 	[(pat ...+) option=> option ... body ...+]

Matches a sequence of values against each clause in order, matching only when all patterns in a clause match. Each clause must have the same number of patterns as the number of val-exprs.
Examples:
> ```racket
> > ( match* ( 1 2 3 ) [ ( _ ( ? number? ) x ) ( add1 x ) ] )
> 4
> > ( match* ( 15 17 ) [ ( ( ? number? a ) ( ? number? b ) ) #:when ( = ( + a 2 ) b ) ' diff-by-two ] )
> 'diff-by-two
> ```
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

(match/values expr clause* clause* ...)

If expr evaluates to n values, then match all n values against the patterns in clause\* .... Each clause must contain exactly n patterns. At least one clause is required to determine how many values to expect from expr.
Example:


### 9.1 Additional Matching Forms
> ```racket
> > ( match/values ( values 1 2 3 ) [ ( a ( ? number? b ) ( ? odd? c ) ) ( + a b c ) ] )
> 6
> ```
> ```
syntax
(define/match (head args)
> match*-clause ... )
head   =   id
    |   (head args)
args   =   arg ...
    |   arg ... . rest-id
arg   =   arg-id
    |   [arg-id default-expr]
    |   keyword arg-id
    |   keyword [arg-id default-expr]
match*-clause   =   [(pat ...+) option=> option ... body ...+]```
Binds id to a procedure that is defined by pattern matching clauses using [match*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2A%29%29). Each clause takes a sequence of patterns that correspond to the arguments in the function header. The arguments are ordered as they appear in the function header for matching purposes.
Examples:
> ```racket
> ( define/match ( fact n ) [ ( 0 ) 1 ] [ ( n ) ( * n ( fact ( sub1 n ) ) ) ] )
> > ( fact 5 )
> 120
> ```
The function header may also contain optional or keyword arguments, may have curried arguments, and may also contain a rest argument.
Examples:
> ```racket
> ( define/match ( ( f x ) #:y [ y ' ( 1 2 3 ) ] ) [ ( ( regexp #rx"p+" ) ` ( , a 2 3 ) ) a ] [ ( _ _ ) #f ] )
> > ( ( f "ape" ) #:y ' ( 5 2 3 ) )
> 5
> > ( ( f "dog" ) )
> #f
> ( define/match ( g x y . rst ) [ ( 0 0 ' ( ) ) #t ] [ ( 5 5 ' ( 5 5 ) ) #t ] [ ( _ _ _ ) #f ] )
> > ( g 0 0 )
> #t
> > ( g 5 5 5 5 )
> #t
> > ( g 1 2 )
> #f
> ```


### 9.1 Additional Matching Forms
>
<colgroup><col style="width: 100%" /></colgroup>

<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-lambda](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-lambda%29%29) clause ...)

<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-λ](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-~ce~bb%29%29) clause ...)

Equivalent to ([lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) (id) ([match](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%29%29) id clause [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29))).
Changed in version 8.13.0.5 of package base: Added [match-λ](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-~ce~bb%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

<colgroup><col style="width: 100%" /></colgroup>

syntax


### 9.1 Additional Matching Forms

([match-lambda*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-lambda%2A%29%29) clause ...)

<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-λ*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-~ce~bb%2A%29%29) clause ...)

Equivalent to ([lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) lst ([match](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%29%29) lst clause [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29))).
Changed in version 8.13.0.5 of package base: Added [match-λ*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-~ce~bb%2A%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-lambda**](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-lambda%2A%2A%29%29) clause* ...)

<colgroup><col style="width: 100%" /></colgroup>

syntax


### 9.1 Additional Matching Forms

([match-λ**](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-~ce~bb%2A%2A%29%29) clause* ...)

Equivalent to ([lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) (args [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) ([match*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2A%29%29) (args [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) clause\* [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29))), where the number of args [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) is computed from the number of patterns appearing in each of the clause\*.
Changed in version 8.13.0.5 of package base: Added [match-λ**](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-~ce~bb%2A%2A%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-let](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%29%29) ([pat expr] ...) body ...+)


### 9.1 Additional Matching Forms
Generalizes [let](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29) to support pattern bindings. Each expr is matched against its corresponding pat (the match must succeed), and the bindings that pat introduces are visible in the bodys.
Example:
> ```racket
> > ( match-let ( [ ( list a b ) ' ( 1 2 ) ] [ ( vector x ... ) # ( 1 2 3 4 ) ] ) ( list b a x ) )
> '(2 1 (1 2 3 4))
> ```
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-let*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%2A%29%29) ([pat expr] ...) body ...+)

Like [match-let](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%29%29), but generalizes [let*](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%2A%29%29), so that the bindings of each pat are available in each subsequent expr.
Example:
> ```racket
> > ( match-let* ( [ ( list a b ) ' ( # ( 1 2 3 4 ) 2 ) ] [ ( vector x ... ) a ] ) x )
> '(1 2 3 4)
> ```
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-let-values](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let-values%29%29) ([(pat ...) expr] ...) body ...+)


### 9.1 Additional Matching Forms
Like [match-let](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%29%29), but generalizes [let-values](let.html#%28form._%28%28quote._~23~25kernel%29._let-values%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-let*-values](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%2A-values%29%29) ([(pat ...) expr] ...) body ...+)

Like [match-let*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%2A%29%29), but generalizes [let*-values](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%2A-values%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-letrec](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-letrec%29%29) ([pat expr] ...) body ...+)

Like [match-let](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%29%29), but generalizes [letrec](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._letrec%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-letrec-values](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-letrec-values%29%29) ([(pat ...) expr] ...) body ...+)


### 9.1 Additional Matching Forms
Like [match-let](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-let%29%29), but generalizes [letrec-values](let.html#%28form._%28%28quote._~23~25kernel%29._letrec-values%29%29).
Added in version 6.1.1.8 of package base.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-define](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-define%29%29) pat expr)

Defines the names bound by pat to the values produced by matching against the result of expr.
Examples:
> ```racket
> > ( match-define ( list a b ) ' ( 1 2 ) )
> > b
> 2
> ```
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([match-define-values](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-define-values%29%29) (pat pats ...) expr)

Like [match-define](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-define%29%29) but for when expr produces multiple values. Like match/values, it requires at least one pattern to determine the number of values to expect.
Examples:
> ```racket
> > ( match-define-values ( a b ) ( values 1 2 ) )
> > b
> 2
> ```
> ```
(exn:misc:match? v)  →  boolean?
  v : any/c


### 9.1 Additional Matching Forms
```
(failure-cont)	→
(-> define-match-expander syntax-list (lambda (stx) (syntax-case stx () [ (_ elts ...) #' (? syntax-list? (app syntax → list (list elts ...))) ])))```

Predicates for values which implement the appropriate match expander properties.

> ```
(syntax-local-match-introduce stx)  →  syntax?
  stx : syntax?
```
(match-equality-test)	→
(-> any/c any/c . → . any)
(match-equality-test comp-proc) → void?
    comp-proc	:
(-> any/c any/c . → . any)```
A [parameter](eval-model.html#%28tech._parameter%29) that determines the comparison procedure used to check whether multiple uses of an identifier match the “same” value. The default is [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

<colgroup><col style="width: 100%" /></colgroup>

syntax

([match/derived](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2Fderived%29%29) val-expr original-datum clause ...)

<colgroup><col style="width: 100%" /></colgroup>

syntax

([match*/derived](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2A%2Fderived%29%29) (val-expr ...) original-datum clause* ...)


### 9.1 Additional Matching Forms
Like [match](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%29%29) and [match*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2A%29%29) respectively, but includes a sub-expression to be used as the source for all syntax errors within the form. For example, [match-lambda](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-lambda%29%29) expands to [match/derived](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%2Fderived%29%29) so that errors in the body of the form are reported in terms of [match-lambda](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match-lambda%29%29) instead of [match](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%29%29).


### 9.3 Library Extensions
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([==](#%28form._%28%28lib._racket%2Fmatch..rkt%29._~3d~3d%29%29) val comparator)

([==](#%28form._%28%28lib._racket%2Fmatch..rkt%29._~3d~3d%29%29) val)

A [match expander](#%28tech._match._expander%29) which checks if the matched value is the same as val when compared by comparator. If comparator is not provided, it defaults to [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29).
Examples:
> ```racket
> > ( match ( list 1 2 3 ) [ ( == ( list 1 2 3 ) ) ' yes ] [ _ ' no ] )
> 'yes
> > ( match ( list 1 2 3 ) [ ( == ( list 1 2 3 ) eq? ) ' yes ] [ _ ' no ] )
> 'no
> > ( match ( list 1 2 3 ) [ ( list 1 2 ( == 3 = ) ) ' yes ] [ _ ' no ] )
> 'yes
> ```
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([struct*](#%28form._%28%28lib._racket%2Fmatch..rkt%29._struct%2A%29%29) struct-id ([field pat] ...))

A [match](#%28form._%28%28lib._racket%2Fmatch..rkt%29._match%29%29) pattern form that matches an instance of a structure type named struct-id, where the field field in the instance matches the corresponding pat. The fields do not include those from super types.
Any field of struct-id may be omitted, and such fields can occur in any order.
Examples:


### 9.3 Library Extensions
> ```racket
> ( struct tree ( val left right ) ) ( struct tree* tree ( val ) )
> > ( match ( tree 0 ( tree 1 #f #f ) #f ) [ ( struct* tree ( [ val a ] [ left ( struct* tree ( [ right #f ] [ val b ] ) ) ] ) ) ( list a b ) ] )
> '(0 1)
> > ( match ( tree* 0 #f #f 42 ) [ ( and ( struct* tree* ( [ val a ] ) ) ( struct* tree ( [ val b ] ) ) ) ( list a b ) ] )
> '(42 0)
> ```
------------------------------------------------------------------------


# 10 Control Flow


## 10 Control Flow
|                                                                                |
|-------------------------------------------------------------------------------------------------------------------------------------|
|     [10.1 Multiple Values](values.html)                                                                  |
|     [10.2 Exceptions](exns.html)                                                                         |
|       [10.2.1 Error Message Conventions](exns.html#%28part._err-msg-conventions%29)                      |
|       [10.2.2 Raising Exceptions](exns.html#%28part._errorproc%29)                                       |
|       [10.2.3 Handling Exceptions](exns.html#%28part._.Handling_.Exceptions%29)                          |
|       [10.2.4 Configuring Default Handling](exns.html#%28part._.Configuring_.Default_.Handling%29)       |
|       [10.2.5 Built-in Exception Types](exns.html#%28part._.Built-in_.Exception_.Types%29)               |
|       [10.2.6 Additional Exception Functions](exns.html#%28part._.Additional_.Exception_.Functions%29)   |
|       [10.2.7 Realms and Error Message Adjusters](exns.html#%28part._err-realm%29)                       |
|     [10.3 Delayed Evaluation](Delayed_Evaluation.html)                                                   |
|       [10.3.1 Additional Promise Kinds](Delayed_Evaluation.html#%28part._.Additional_.Promise_.Kinds%29) |
|     [10.4 Continuations](cont.html)                                                                      |
|       [10.4.1 Additional Control Operators](cont.html#%28part._.Additional_.Control_.Operators%29)       |
|     [10.5 Continuation Marks](contmarks.html)                                                            |
|     [10.6 Breaks](breakhandler.html)                                                                     |
|     [10.7 Exiting](Exiting.html)                                                                         |
|     [10.8 Unreachable Expressions](unreachable.html)                                                     |
|       [10.8.1 Customized Unreachable Reporting](unreachable.html#%28part._with-unreachable%29)           |


# 10 Control Flow
------------------------------------------------------------------------


# 10.1 Multiple Values


### 10.1 Multiple Values
See [Multiple Return Values](eval-model.html#%28part._values-model%29) for general information about multiple result values. In addition to [call-with-values](#%28def._%28%28quote._~23~25kernel%29._call-with-values%29%29) (described in this section), the [let-values](let.html#%28form._%28%28quote._~23~25kernel%29._let-values%29%29), [let*-values](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%2A-values%29%29), [letrec-values](let.html#%28form._%28%28quote._~23~25kernel%29._letrec-values%29%29), and [define-values](define.html#%28form._%28%28quote._~23~25kernel%29._define-values%29%29) forms (among others) create continuations that receive multiple values.
> ```
(values v ...) → any
  v : any/c


# 10.1 Multiple Values
```
Returns the given vs. That is, values returns its provided arguments.

Examples:

> ```racket
> > ( values 1 )
> 1
> > ( values 1 2 3 )
> 1 2 3
> > ( values )
> ```

> ```
(call-with-values generator receiver)   →   any
  generator : (  →   any)
  receiver : procedure?```

Calls generator, and passes the values that generator produces as arguments to receiver. Thus, [call-with-values](#%28def._%28%28quote._~23~25kernel%29._call-with-values%29%29) creates a continuation that accepts any number of values that receiver can accept. The receiver procedure is called in tail position with respect to the [call-with-values](#%28def._%28%28quote._~23~25kernel%29._call-with-values%29%29) call.

Examples:

> ```racket
> > ( call-with-values ( lambda ( ) ( values 1 2 ) ) + )
> 3
> > ( call-with-values ( lambda ( ) 1 ) ( lambda ( x y ) ( + x y ) ) )
> arity mismatch;
> the expected number of arguments does not match the given
> number
> expected: 2
> given: 1
> ```

------------------------------------------------------------------------

# 10.2 Exceptions

### 10.2 Exceptions

> > > <img src="finger.png" width="24" height="24" alt="+" />[Exceptions](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=exns.html&version=8.18.0.13) in [The Racket Guide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=index.html&version=8.18.0.13) introduces exceptions.

See [Exceptions](eval-model.html#%28part._exn-model%29) for information on the Racket exception model. It is based on a proposal by Friedman, Haynes, and Dybvig \[[Friedman95](doc-bibliography.html#%28cite._.Friedman95%29)\].

Whenever a primitive error occurs in Racket, an exception is raised. The value that is passed to the current [exception handler](eval-model.html#%28tech._exception._handler%29) for a primitive error is always an instance of the [exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn%29%29) structure type. Every [exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn%29%29) structure value has a message field that is a string, the primitive error message. The default exception handler recognizes exception values with the [exn?](#%28def._%28%28quote._~23~25kernel%29._exn~3f%29%29) predicate and passes the error message to the current [error display handler](#%28tech._error._display._handler%29) (see [error-display-handler](#%28def._%28%28quote._~23~25kernel%29._error-display-handler%29%29)).

Primitive procedures that accept a procedure argument with a particular required arity (e.g., [call-with-input-file](file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._call-with-input-file%29%29), [call/cc](cont.html#%28def._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._call%2Fcc%29%29)) check the argument’s arity immediately, raising [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) if the arity is incorrect.

#### 10.2.1 Error Message Conventions

Racket’s error message convention is to produce error messages with the following shape:

> ```racket
> ‹ srcloc › : ‹ name › : ‹ message › ;
> ‹ continued-message › ...
> ‹ field › : ‹ detail ›
> ...
> ```

The message starts with an optional source location, ‹srcloc›, which is followed by a colon and space when present. The message continues with an optional ‹name› that usually identifies the complaining function, syntactic form, or other entity, but may also refer to an entity being complained about; the ‹name› is also followed by a colon and space when present.

The ‹message› should be relatively short, and it should be largely independent of specific values that triggered the error. More detailed explanation that requires multiple lines should continue with each line indented by a single space, in which case ‹message› should end in a semi-colon (but the semi-colon should be omitted if ‹continued-message› is not present). Message text should be lowercase—using semi-colons to separate sentences if needed, although long explanations may be better deferred to extra fields.

Specific values that triggered the error or other helpful information should appear in separate ‹field› lines, each of which is indented by two spaces. If a ‹detail› is especially long or takes multiple lines, it should start on its own line after the ‹field› label, and each of its lines should be indented by three spaces. Field names should be all lowercase.

A ‹field› name should end with ... if the field provides relatively detailed information that might be distracting in common cases but useful in others. For example, when a contract failure is reported for a particular argument of a function, other arguments to the function might be shown in an “other arguments...” field. The intent is that fields whose names end in ... might be hidden by default in an environment such as DrRacket.

Make ‹field› names as short as possible, relying on ‹message› or ‹continued message› text to clarify the meaning for a field. For example, prefer “given” to “given turtle” as a field name, where ‹message› is something like “given turtle is too sleepy” to clarify that “given” refers to a turtle.

#### 10.2.2 Raising Exceptions

> ```
(raise v [barrier?) → any
  v : any/c
  barrier? : any/c = #t
```


# 10.1 Multiple Values
(parameter)	→
(-> error message-str v ...)```
Raises the exception [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29), which contains an error string. The different forms produce the error string in different ways:
-   ([error](#%28def._%28%28quote._~23~25kernel%29._error%29%29) message-sym) creates a message string by concatenating "error: " with the string form of message-sym. Use this form sparingly.
-   ([error](#%28def._%28%28quote._~23~25kernel%29._error%29%29) message-str v [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) creates a message string by concatenating message-str with string versions of the vs (as produced by the current error value conversion handler; see [error-value->string-handler](#%28def._%28%28quote._~23~25kernel%29._error-value-~3estring-handler%29%29)). A space is inserted before each v. Use this form sparingly, because it does not conform well to Racket’s [error message conventions](#%28tech._error._message._convention%29); consider [raise-arguments-error](#%28def._%28%28quote._~23~25kernel%29._raise-arguments-error%29%29), instead.
-   ([error](#%28def._%28%28quote._~23~25kernel%29._error%29%29) who-sym format-str v [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) creates a message string equivalent to the string created by


# 10.1 Multiple Values
    > ([format](Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29) ([string-append](strings.html#%28def._%28%28quote._~23~25kernel%29._string-append%29%29) "\~s: " format-str) who-sym v [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29))
    When possible, use functions such as [raise-argument-error](#%28def._%28%28quote._~23~25kernel%29._raise-argument-error%29%29), instead, which construct messages that follow Racket’s [error message conventions](#%28tech._error._message._convention%29).
In all cases, the constructed message string is passed to [make-exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail%29%29), and the resulting exception is raised.
Examples:
> ```racket
> > ( error ' failed )
> error: failed
> > ( error "failed" 23 ' pizza ( list 1 2 3 ) )
> failed 23 'pizza '(1 2 3)
> > ( error ' method-a "failed because ~a" "no argument supplied" )
> method-a: failed because no argument supplied
> ```
> ```
(parameter)	→
(-> raise-user-error message-str v ...)


# 10.1 Multiple Values
```
(parameter)	→
(-> raise-argument-error name
    expected
    bad-pos
    v ...)```

Creates an [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) value and [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)s it as an exception. The name argument is used as the source procedure’s name in the error message. The expected argument is used as a description of the expected contract (i.e., as a string, but the string is intended to contain a contract expression).

In the first form, v is the value received by the procedure that does not have the expected type.

In the second form, the bad argument is indicated by an index bad-pos (counting from 0), and all of the original arguments v are provided (in order). The resulting error message names the bad argument and also lists the other arguments. If bad-pos is not less than the number of vs, the [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.

The error message generated by [raise-argument-error](#%28def._%28%28quote._~23~25kernel%29._raise-argument-error%29%29) is adjusted via [error-contract->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-contract-~3eadjusted-string%29%29) and then [error-message->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-message-~3eadjusted-string%29%29) using the default 'racket realm.

Examples:

> ```racket
> > ( define ( feed-machine bits ) ( unless ( integer? bits ) ( raise-argument-error ' feed-machine "integer?" bits ) ) "fed the machine" )
> > ( feed-machine ' turkey )
> feed-machine: contract violation
> expected: integer?
> given: 'turkey
> > ( define ( feed-cow animal ) ( unless ( eq? animal ' cow ) ( raise-argument-error ' feed-cow "'cow" animal ) ) "fed the cow" )
> > ( feed-cow ' turkey )
> feed-cow: contract violation
> expected: 'cow
> given: 'turkey
> > ( define ( feed-animals cow sheep goose cat ) ( unless ( eq? goose ' goose ) ( raise-argument-error ' feed-animals "'goose" 2 cow sheep goose cat ) ) "fed the animals" )
> > ( feed-animals ' cow ' sheep ' dog ' cat )
> feed-animals: contract violation
> expected: 'goose
> given: 'dog
> argument position: 3rd
> other arguments...:
> 'cow
> 'sheep
> 'cat
> ```

> ```
(parameter)	→
(-> raise-argument-error* name
    realm
    expected
    bad-pos
    v ...)
```


# 10.1 Multiple Values
(parameter)	→
(-> raise-result-error name
    expected
    bad-pos
    v ...)```
Like [raise-argument-error](#%28def._%28%28quote._~23~25kernel%29._raise-argument-error%29%29), but the error message describe v as a “result” instead of an “argument.”
> ```
(parameter)	→
(-> raise-result-error* name
    realm
    expected
    bad-pos
    v ...)
```
(parameter)	→```

Creates an [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) value and [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)s it as an exception. The name is used as the source procedure’s name in the error message. The message is the error message; if message contains newline characters, each extra line should be suitably indented (with one extra space at the start of each line), but it should not end with a newline character. Each field must have a corresponding v, and the two are rendered on their own line in the error message; each v is formatted using the error value conversion handler (see [error-value->string-handler](#%28def._%28%28quote._~23~25kernel%29._error-value-~3estring-handler%29%29)), unless v is a [unquoted-printing string](#%28tech._unquoted._printing._string%29), in which case the string content is [display](Writing.html#%28def._%28%28quote._~23~25kernel%29._display%29%29)ed without using the error value conversion handler. When a string produced by the error value conversion handler or in an unquoted-printing string contains a newline but does not start with a newline, then the string is started on its own line with extra spaces added before each line to indent the string content.

The error message generated by [raise-arguments-error](#%28def._%28%28quote._~23~25kernel%29._raise-arguments-error%29%29) is adjusted via [error-message->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-message-~3eadjusted-string%29%29) using the default 'racket realm.

Examples:

> ```racket
> > ( raise-arguments-error ' eat "fish is smaller than its given meal" "fish" 12 "meal" 13 )
> eat: fish is smaller than its given meal
> fish: 12
> meal: 13
> > ( raise-arguments-error ' eat "not edible" "candidate" ( unquoted-printing-string "a banana made\nof wax" ) )
> eat: not edible
> candidate:
> a banana made
> of wax
> ```

Changed in version 8.15.0.2 of package base: Added indentation for v strings that contain newlines.

> ```
(parameter)	→
```


# 10.1 Multiple Values
(parameter)	→
(-> or/c #f exact-integer?)```
Creates an [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) value and [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)s it as an exception to report an out-of-range error. The type-description string describes the value for which the index is meant to select an element, and index-prefix is a prefix for the word “index.” The index argument is the rejected index. The in-value argument is the value for which the index was meant. The lower-bound and upper-bound arguments specify the valid range of indices, inclusive; if upper-bound is below lower-bound, the value is characterized as “empty.” If alt-lower-bound is not #f, and if index is between alt-lower-bound and upper-bound, then the error is report as index being less than the “starting” index lower-bound.
Since upper-bound is inclusive, a typical value is one less than the size of a collection—for example, ([sub1](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._sub1%29%29) ([vector-length](vectors.html#%28def._%28%28quote._~23~25kernel%29._vector-length%29%29) vec)), ([sub1](generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._sub1%29%29) ([length](pairs.html#%28def._%28%28quote._~23~25kernel%29._length%29%29) lst)), and so on.


# 10.1 Multiple Values
The error message generated by [raise-range-error](#%28def._%28%28quote._~23~25kernel%29._raise-range-error%29%29) is adjusted via [error-message->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-message-~3eadjusted-string%29%29) using the default 'racket realm.
Examples:
> ```racket
> > ( raise-range-error ' vector-ref "vector" "starting " 5 # ( 1 2 3 4 ) 0 3 )
> vector-ref: starting index is out of range
> starting index: 5
> valid range: [0, 3]
> vector: '#(1 2 3 4)
> > ( raise-range-error ' vector-ref "vector" "ending " 5 # ( 1 2 3 4 ) 0 3 )
> vector-ref: ending index is out of range
> ending index: 5
> valid range: [0, 3]
> vector: '#(1 2 3 4)
> > ( raise-range-error ' vector-ref "vector" "" 3 # ( ) 0 -1 )
> vector-ref: index is out of range for empty vector
> index: 3
> > ( raise-range-error ' vector-ref "vector" "ending " 1 # ( 1 2 3 4 ) 2 3 0 )
> vector-ref: ending index is smaller than starting index
> ending index: 1
> starting index: 2
> valid range: [0, 3]
> vector: '#(1 2 3 4)
> ```
> ```
(parameter)	→
(-> or/c #f exact-integer?)


# 10.1 Multiple Values
```
(parameter)	→
(-> raise-type-error name expected bad-pos v ...)```

Like [raise-argument-error](#%28def._%28%28quote._~23~25kernel%29._raise-argument-error%29%29), but with Racket’s old formatting conventions, and where expected is used as a “type” description instead of a contract expression. Use [raise-argument-error](#%28def._%28%28quote._~23~25kernel%29._raise-argument-error%29%29) or [raise-result-error](#%28def._%28%28quote._~23~25kernel%29._raise-result-error%29%29), instead.

The error message generated by [raise-type-error](#%28def._%28%28quote._~23~25kernel%29._raise-type-error%29%29) is adjusted via [error-message->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-message-~3eadjusted-string%29%29) using the default 'racket realm.

> ```
(parameter)	→
```
(parameter)	→
(-> parameter)```
Creates an [exn:fail:contract:arity](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3aarity%29%29) value and [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)s it as an exception. The name is used for the source procedure’s name in the error message.


# 10.1 Multiple Values
The arity-v value must be a possible result from [procedure-arity](procedures.html#%28def._%28%28quote._~23~25kernel%29._procedure-arity%29%29), except that it does not have to be normalized (see [procedure-arity?](procedures.html#%28def._%28%28quote._~23~25kernel%29._procedure-arity~3f%29%29) for the details of normalized arities); [raise-arity-error](#%28def._%28%28quote._~23~25kernel%29._raise-arity-error%29%29) will normalize the arity and use the normalized form in the error message. If name is a procedure, its actual arity is ignored.
The arg-v arguments are the actual supplied arguments, which are shown in the error message (using the error value conversion handler; see [error-value->string-handler](#%28def._%28%28quote._~23~25kernel%29._error-value-~3estring-handler%29%29)); also, the number of supplied arg-vs is explicitly mentioned in the message.
The error message generated by [raise-arity-error](#%28def._%28%28quote._~23~25kernel%29._raise-arity-error%29%29) is adjusted via [error-message->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-message-~3eadjusted-string%29%29) using the default 'racket realm.
Example:
> ```racket
> > ( raise-arity-error ' unite ( arity-at-least 13 ) "Virginia" "Maryland" )
> unite: arity mismatch;
> the expected number of arguments does not match the given
> number
> expected: at least 13
> given: 2
> arguments...:
> "Virginia"
> "Maryland"
> ```
> ```
(parameter)	→
(-> or/c symbol? procedure?)


# 10.1 Multiple Values
```
(parameter)	→
(-> or/c symbol? procedure?)```

The same as [raise-arity-error](#%28def._%28%28quote._~23~25kernel%29._raise-arity-error%29%29), but using the arity representation described with [procedure-arity-mask](procedures.html#%28def._%28%28quote._~23~25kernel%29._procedure-arity-mask%29%29).

Added in version 7.0.0.11 of package base.

> ```
(parameter)	→
(-> or/c symbol? procedure?)
```
(parameter)	→
(-> or/c symbol? #f)```
Like [raise-arity-error](#%28def._%28%28quote._~23~25kernel%29._raise-arity-error%29%29), but reports a “result” mismatch instead of an “argument” mismatch. The name argument can be #f to omit an initial source for the error. The detail-str argument, if non-#f, should be a string that starts with a newline, since it is added near the end of the generated error message.
The error message generated by [raise-result-arity-error](#%28def._%28%28quote._~23~25kernel%29._raise-result-arity-error%29%29) is adjusted via [error-message->adjusted-string](#%28def._%28%28quote._~23~25kernel%29._error-message-~3eadjusted-string%29%29) using the default 'racket realm.
Example:
> ```racket
> > ( raise-result-arity-error ' let-values 2 "\n in: example" ' a 2.0 "three" )
> let-values: result arity mismatch;
> expected number of values not received
> expected: 2
> received: 3
> in: example
> arguments...:
> 'a
> 2.0
> "three"
> ```
Added in version 6.90.0.26 of package base.
> ```
(parameter)	→
(-> or/c symbol? #f)


# 10.1 Multiple Values
```
(parameter)	→
(-> or/c symbol? #f)```

Creates an [exn:fail:syntax?](#%28def._%28%28quote._~23~25kernel%29._exn~3afail~3asyntax~3f%29%29) value and [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)s it as an exception. Macros use this procedure to report syntax errors.

The name argument is usually #f when expr is provided; it is described in more detail below. The message is used as the main body of the error message; if message contains newline characters, each new line should be suitably indented (with one space at the start), and it should not end with a newline character.

The optional expr argument is the erroneous source syntax object or S-expression (but the expression #f cannot be represented by itself; it must be wrapped as a [syntax object](syntax-model.html#%28tech._syntax._object%29)). The optional sub-expr argument is a syntax object or S-expression (again, #f cannot represent itself) within expr that more precisely locates the error. Both may appear in the generated error-message text if [error-print-source-location](#%28def._%28%28quote._~23~25kernel%29._error-print-source-location%29%29) is #t. Source location information in the error-message text is similarly extracted from sub-expr or expr when at least one is a syntax object and [error-print-source-location](#%28def._%28%28quote._~23~25kernel%29._error-print-source-location%29%29) is #t.

If sub-expr is provided and not #f, it is used (in syntax form) for the exprs field of the generated exception record, else the expr is used if provided and not #f. In either case, the syntax object is [cons](pairs.html#%28def._%28%28quote._~23~25kernel%29._cons%29%29)ed onto extra-sources to produce the exprs field, or extra-sources is used directly for exprs if neither expr nor sub-expr is provided and not #f. The extra-sources argument is also used directly for exprs in the unusual case that the sub-expr or expr that would be included in exprs cannot be converted to a syntax object (because it contains a cycle).

The form name used in the generated error message is determined through a combination of the name, expr, and sub-expr arguments:

-   When name is #f, and when expr is either an identifier or a syntax pair containing an identifier as its first element, then the form name from the error message is the identifier’s symbol.

-   When name is #f and when expr is not an identifier or a syntax pair containing an identifier as its first element, then the form name in the error message is "?".

-   When name is a symbol, then the symbol is used as the form name in the generated error message.

The message-suffix string is appended to the end of the error message. If not "", it should normally start with a newline and two spaces to add extra fields to the message (see [Error Message Conventions](#%28part._err-msg-conventions%29)).

If specified, exn should be a constructor or function that has the same signature as the [exn:fail:syntax](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29) constructor.

Examples:

> ```racket
> > ( raise-syntax-error #f "bad syntax" ' ( bad syntax ) )
> ?: bad syntax
> in: (bad syntax)
> > ( raise-syntax-error #f "unbound identifier" ' unbound-id #:exn exn:fail:syntax:unbound )
> ?: unbound identifier
> in: unbound-id
> ```

Changed in version 6.90.0.18 of package base: Added the message-suffix optional argument.
Changed in version 8.4.0.6: Added the exn optional argument.

> ```
(unquoted-printing-string? v)  →  boolean?
  v : any/c

(unquoted-printing-string s)  →  unquoted-printing-string?
  s : string?

(unquoted-printing-string-value ups)  →  string?
  ups : unquoted-printing-string?
```


# 10.1 Multiple Values
An unquoted-printing string wraps a string and prints, writes, and displays the same way that the string displays. An unquoted-printing string is especially useful with raise-arguments-error to serve as a field “value” that causes literal text to be printed as the field content.
The unquoted-printing-string? procedure returns #t if v is a unquoted-printing string, #f otherwise. The unquoted-printing-string creates a unquoted-printing string value that encapsulates the string s, and unquoted-printing-string-value returns the string within a unquoted-printing string.
Added in version 6.10.0.2 of package base.


#### 10.2.3 Handling Exceptions
> ```
(call-with-exception-handler f thunk)   →   any
  f : (any/c .  →  . any)
  thunk : (  →   any)```
Installs f as the [exception handler](eval-model.html#%28tech._exception._handler%29) for the [dynamic extent](eval-model.html#%28tech._dynamic._extent%29) of the call to thunk. If an exception is raised during the evaluation of thunk (in an extension of the current continuation that does not have its own exception handler), then f is applied to the [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)d value in the continuation of the [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29) call (but the continuation is normally extended with a [continuation barrier](eval-model.html#%28tech._continuation._barrier%29); see [Prompts, Delimited Continuations, and Barriers](eval-model.html#%28part._prompt-model%29) and [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29)).


# 10.1 Multiple Values
Any procedure that takes one argument can be an exception handler. Normally, an exception handler escapes from the context of the [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29) call via [abort-current-continuation](cont.html#%28def._%28%28quote._~23~25kernel%29._abort-current-continuation%29%29) or some other escape mechanism. To propagate an exception to the “previous” exception handler—that is, the exception handler associated with the rest of the continuation after the point where the called exception handler was associated with the continuation—an exception handler can simply return a result instead of escaping, in which case the [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29) call propagates the value to the previous exception handler (still in the dynamic extent of the call to [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29), and under the same barrier, if any). If an exception handler returns a result and no previous handler is available, the [uncaught-exception handler](#%28tech._uncaught._exception._handler%29) is used.


# 10.1 Multiple Values
A call to an exception handler is [parameterize-break](breakhandler.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize-break%29%29)ed to disable breaks, and it is wrapped with [call-with-exception-handler](#%28def._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._call-with-exception-handler%29%29) to install an exception handler that reports both the original and newly raised exceptions via the [error display handler](#%28tech._error._display._handler%29) and then escapes via the [error escape handler](#%28tech._error._escape._handler%29).
> ```
(uncaught-exception-handler)	→
(-> any/c . → . any)
(uncaught-exception-handler f) → void?
    f	:
(-> any/c . → . any)


# 10.1 Multiple Values
```
(parameter)	→```

Evaluates each pred-expr and handler-expr in the order that they are specified, and then evaluates the bodys with a new exception handler during its dynamic extent.

The new exception handler processes an exception only if one of the pred-expr procedures returns a true value when applied to the exception, otherwise the exception handler is invoked from the continuation of the [with-handlers](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._with-handlers%29%29) expression (by raising the exception again). If an exception is handled by one of the handler-expr procedures, the result of the entire [with-handlers](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._with-handlers%29%29) expression is the return value of the handler.

When an exception is raised during the evaluation of bodys, each predicate procedure pred-expr is applied to the exception value; if a predicate returns a true value, the corresponding handler-expr procedure is invoked with the exception as an argument. The predicates are tried in the order that they are specified.

Before any predicate or handler procedure is invoked, the continuation of the entire [with-handlers](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._with-handlers%29%29) expression is restored, but also [parameterize-break](breakhandler.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize-break%29%29)ed to disable breaks. Thus, breaks are disabled by default during the predicate and handler procedures (see [Breaks](breakhandler.html)), and the exception handler is the one from the continuation of the [with-handlers](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._with-handlers%29%29) expression.

The [exn:fail?](#%28def._%28%28quote._~23~25kernel%29._exn~3afail~3f%29%29) procedure is useful as a handler predicate to catch all error exceptions. Avoid using ([lambda](lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29) (x) #t) as a predicate, because the [exn:break](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) exception typically should not be caught (unless it will be re-raised to cooperatively break). Beware, also, of catching and discarding exceptions, because discarding an error message can make debugging unnecessarily difficult; instead of discarding an error message, consider logging it via [log-error](logging.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-error%29%29) or a logging form created by [define-logger](logging.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._define-logger%29%29).

Examples:

> ```racket
> > ( with-handlers ( [ exn:fail:syntax? ( λ ( e ) ( displayln "got a syntax error" ) ) ] ) ( raise-syntax-error #f "a syntax error" ) )
> got a syntax error
> > ( with-handlers ( [ exn:fail:syntax? ( λ ( e ) ( displayln "got a syntax error" ) ) ] [ exn:fail? ( λ ( e ) ( displayln "fallback clause" ) ) ] ) ( raise-syntax-error #f "a syntax error" ) )
> got a syntax error
> ```

> ```
syntax

(with-handlers* ([pred-expr handler-expr] ...)
> body ...+ )
```


# 10.1 Multiple Values
(error-escape-handler)	→
(-> any)
(error-escape-handler proc) → void?
    proc	:
(-> any)```
A parameter for the error escape handler, which takes no arguments and escapes from the dynamic context of an exception. The default error escape handler escapes using ([abort-current-continuation](cont.html#%28def._%28%28quote._~23~25kernel%29._abort-current-continuation%29%29) ([default-continuation-prompt-tag](cont.html#%28def._%28%28quote._~23~25kernel%29._default-continuation-prompt-tag%29%29)) [void](void.html#%28def._%28%28quote._~23~25kernel%29._void%29%29)).
The error escape handler is normally called directly by an exception handler, in a [parameterization](eval-model.html#%28tech._parameterization%29) that sets the [error display handler](#%28tech._error._display._handler%29) and [error escape handler](#%28tech._error._escape._handler%29) to the default handlers, and it is normally [parameterize-break](breakhandler.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize-break%29%29)ed to disable breaks. To escape from a run-time error in a different context, use [raise](#%28def._%28%28quote._~23~25kernel%29._raise%29%29) or [error](#%28def._%28%28quote._~23~25kernel%29._error%29%29).


# 10.1 Multiple Values
Due to a [continuation barrier](eval-model.html#%28tech._continuation._barrier%29) around exception-handling calls, an error escape handler cannot invoke a full continuation that was created prior to the exception, but it can abort to a prompt (see [call-with-continuation-prompt](cont.html#%28def._%28%28quote._~23~25kernel%29._call-with-continuation-prompt%29%29)) or invoke an escape continuation (see [call-with-escape-continuation](cont.html#%28def._%28%28quote._~23~25kernel%29._call-with-escape-continuation%29%29)).
> ```
(error-display-handler)	→
(-> string? any/c . → . any)
(error-display-handler proc) → void?
    proc	:
(-> string? any/c . → . any)
```
(error-print-width)	→
(-> error-print-width)
(error-print-width width) → void?
    width	:
(-> error-print-width)```

A parameter whose value is used as the maximum number of characters used to print a Racket value that is embedded in a primitive error message.

> ```
(error-print-context-length)	→
(-> error-print-context-length cnt)
(error-print-context-length cnt) → void?
    cnt	:
(-> error-print-context-length cnt)
```
(error-print-source-location)	→
(-> error-print-source-location include?)```


# 10.1 Multiple Values
A [parameter](eval-model.html#%28tech._parameter%29) that controls whether read and syntax error messages include source information, such as the source line and column or the expression. This parameter also controls the error message when a module-defined variable is accessed before its definition is executed; the parameter determines whether the message includes a module name. Only the message field of an [exn:fail:read](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aread%29%29), [exn:fail:syntax](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29), or [exn:fail:contract:variable](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3avariable%29%29) structure is affected by the parameter. The default is #t.
> ```
(parameter)	→
(-> any/c exact-nonnegative-integer?
    . → .
    string?)


# 10.1 Multiple Values
```
(parameter)	→
(-> see print-unreadable)```

A [parameter](eval-model.html#%28tech._parameter%29) that determines the error syntax conversion handler, which is used to print a syntax form that is embedded in an error message, such as from [raise-syntax-error](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._raise-syntax-error%29%29) when [error-print-source-location](#%28def._%28%28quote._~23~25kernel%29._error-print-source-location%29%29) is #t.

The arguments to the handler are analogous to the arguments for a [error value conversion handler](#%28tech._error._value._conversion._handler%29) as configured with [error-value->string-handler](#%28def._%28%28quote._~23~25kernel%29._error-value-~3estring-handler%29%29), except that #f can be provided instead of an integer for the length, meaning that the printed form should not be truncated. The first argument is normally a [syntax object](syntax-model.html#%28tech._syntax._object%29), but in the same way that [raise-syntax-error](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._raise-syntax-error%29%29) accepts other S-expressions, the error syntax conversion handler must also handle representations that are not syntax objects.

Added in version 8.2.0.8 of package base.

> ```
(parameter)	→
(-> syntax? . → . (or/c symbol? #f))
```
(parameter)	→
(-> any/c exact-nonnegative-integer?
    . → .
    string?)```


# 10.1 Multiple Values
Similar to [error-value->string-handler](#%28def._%28%28quote._~23~25kernel%29._error-value-~3estring-handler%29%29), but intended for a module path. The default [write](Writing.html#%28def._%28%28quote._~23~25kernel%29._write%29%29)s the module path to a string.
Added in version 8.16.0.3 of package base.


#### 10.2.5 Built-in Exception Types
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn%29%29) (message continuation-marks)

    #:extra-constructor-name [make-exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn%29%29)

    #:transparent)

  message : [string?](strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29)

  continuation-marks : [continuation-mark-set?](contmarks.html#%28def._%28%28quote._~23~25kernel%29._continuation-mark-set~3f%29%29)

The base [structure type](structures.html#%28tech._structure._type%29) for exceptions. The message field contains an error message, and the [continuation-marks](contmarks.html#%28def._%28%28quote._~23~25kernel%29._continuation-marks%29%29) field contains the value produced by ([current-continuation-marks](contmarks.html#%28def._%28%28quote._~23~25kernel%29._current-continuation-marks%29%29)) immediately before the exception was raised.
Exceptions raised by Racket form a hierarchy under [exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn%29%29):


# 10.1 Multiple Values
> ```racket
> exn
> exn:fail
> exn:fail:contract
> exn:fail:contract:arity
> exn:fail:contract:divide-by-zero
> exn:fail:contract:non-fixnum-result
> exn:fail:contract:continuation
> exn:fail:contract:variable
> exn:fail:syntax
> exn:fail:syntax:unbound
> exn:fail:syntax:missing-module
> exn:fail:read
> exn:fail:read:eof
> exn:fail:read:non-char
> exn:fail:filesystem
> exn:fail:filesystem:exists
> exn:fail:filesystem:version
> exn:fail:filesystem:errno
> exn:fail:filesystem:missing-module
> exn:fail:network
> exn:fail:network:errno
> exn:fail:out-of-memory
> exn:fail:unsupported
> exn:fail:user
> exn:break
> exn:break:hang-up
> exn:break:terminate
> ```
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) [exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn%29%29) ()

    #:extra-constructor-name [make-exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail%29%29)

    #:transparent)

Raised for exceptions that represent errors, as opposed to [exn:break](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29).


# 10.1 Multiple Values
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) ()

    #:extra-constructor-name [make-exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3acontract%29%29)

    #:transparent)

Raised for errors from the inappropriate run-time use of a function or syntactic form.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:contract:arity](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3aarity%29%29) [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) ()

    #:extra-constructor-name [make-exn:fail:contract:arity](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3acontract~3aarity%29%29)

    #:transparent)

Raised when a procedure is applied to the wrong number of arguments.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:contract:divide-by-zero](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3adivide-by-zero%29%29) [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) ()

    #:extra-constructor-name

    [make-exn:fail:contract:divide-by-zero](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3acontract~3adivide-by-zero%29%29)

    #:transparent)

Raised for division by exact zero.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:contract:non-fixnum-result](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3anon-fixnum-result%29%29) [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) ()

    #:extra-constructor-name

    [make-exn:fail:contract:non-fixnum-result](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3acontract~3anon-fixnum-result%29%29)

    #:transparent)

Raised by functions like [fx+](fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._fx%2B%29%29) when the result would not be a fixnum.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:contract:continuation](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3acontinuation%29%29) [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) ()

    #:extra-constructor-name [make-exn:fail:contract:continuation](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3acontract~3acontinuation%29%29)

    #:transparent)

Raised when a continuation is applied where the jump would cross a continuation barrier.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:contract:variable](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract~3avariable%29%29) [exn:fail:contract](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) (id)

    #:extra-constructor-name [make-exn:fail:contract:variable](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3acontract~3avariable%29%29)

    #:transparent)

  id : [symbol?](symbols.html#%28def._%28%28quote._~23~25kernel%29._symbol~3f%29%29)

Raised for a reference to a not-yet-defined [top-level variable](eval-model.html#%28tech._top._level._variable%29) or [module-level variable](eval-model.html#%28tech._module._level._variable%29).
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:syntax](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) (exprs)

    #:extra-constructor-name [make-exn:fail:syntax](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3asyntax%29%29)

    #:transparent)

  exprs : ([listof](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29) [syntax?](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax~3f%29%29))

Raised for a syntax error that is not a [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) error. The exprs indicate the relevant source expressions, least-specific to most-specific.
This structure type implements the [prop:exn:srclocs](#%28def._%28%28quote._~23~25kernel%29._prop~3aexn~3asrclocs%29%29) property.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:syntax:unbound](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax~3aunbound%29%29) [exn:fail:syntax](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29) ()

    #:extra-constructor-name [make-exn:fail:syntax:unbound](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3asyntax~3aunbound%29%29)

    #:transparent)

Raised by [#%top](__top.html#%28form._%28%28quote._~23~25kernel%29._~23~25top%29%29) or [set!](set_.html#%28form._%28%28quote._~23~25kernel%29._set%21%29%29) for an unbound identifier within a module.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:syntax:missing-module](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax~3amissing-module%29%29) [exn:fail:syntax](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29) (path)

    #:extra-constructor-name [make-exn:fail:syntax:missing-module](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3asyntax~3amissing-module%29%29)

    #:transparent)

  path : [module-path?](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._module-path~3f%29%29)

Raised by the default [module name resolver](Module_Names_and_Loading.html#%28tech._module._name._resolver%29) or default [load handler](eval.html#%28tech._load._handler%29) to report a module path—a reported in the path field—whose implementation file cannot be found.


# 10.1 Multiple Values
The default [module name resolver](Module_Names_and_Loading.html#%28tech._module._name._resolver%29) raises this exception only when it is given a syntax object as its second argument, and the default [load handler](eval.html#%28tech._load._handler%29) raises this exception only when the value of [current-module-path-for-load](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._current-module-path-for-load%29%29) is a syntax object (in which case both the exprs field and the path field are determined by the syntax object).
This structure type implements the [prop:exn:missing-module](#%28def._%28%28quote._~23~25kernel%29._prop~3aexn~3amissing-module%29%29) property.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:read](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aread%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) (srclocs)

    #:extra-constructor-name [make-exn:fail:read](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3aread%29%29)

    #:transparent)

  srclocs : ([listof](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29) [srcloc?](#%28def._%28%28quote._~23~25kernel%29._srcloc~3f%29%29))

Raised for a [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) error. The srclocs indicate the relevant source expressions.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:read:eof](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aread~3aeof%29%29) [exn:fail:read](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aread%29%29) ()

    #:extra-constructor-name [make-exn:fail:read:eof](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3aread~3aeof%29%29)

    #:transparent)

Raised for a [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) error, specifically when the error is due to an unexpected end-of-file.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:read:non-char](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aread~3anon-char%29%29) [exn:fail:read](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aread%29%29) ()

    #:extra-constructor-name [make-exn:fail:read:non-char](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3aread~3anon-char%29%29)

    #:transparent)

Raised for a [read](Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29) error, specifically when the error is due to an unexpected non-character (i.e., “special”) element in the input stream.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:filesystem](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) ()

    #:extra-constructor-name [make-exn:fail:filesystem](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3afilesystem%29%29)

    #:transparent)

Raised for an error related to the filesystem (such as a file not found).
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:filesystem:exists](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem~3aexists%29%29) [exn:fail:filesystem](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) ()

    #:extra-constructor-name [make-exn:fail:filesystem:exists](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3afilesystem~3aexists%29%29)

    #:transparent)


# 10.1 Multiple Values
Raised for an error when attempting to create a file that exists already.
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:filesystem:version](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem~3aversion%29%29) [exn:fail:filesystem](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29) ()

    #:extra-constructor-name [make-exn:fail:filesystem:version](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3afilesystem~3aversion%29%29)

    #:transparent)

Raised for a version-mismatch error when loading an extension.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values
Raised for a filesystem error for which a system error code is available. The symbol part of an errno field indicates the category of the error code: 'posix indicates a C/Posix errno value, 'windows indicates a Windows system error code (under Windows, only), and 'gai indicates a getaddrinfo error code (which shows up only in [exn:fail:network:errno](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork~3aerrno%29%29) exceptions for operations that resolve hostnames, but is allowed in [exn:fail:filesystem:errno](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem~3aerrno%29%29) instances for consistency).
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:filesystem:missing-module](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem~3amissing-module%29%29) [exn:fail:filesystem](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29)

 	 	(path)

    #:extra-constructor-name

    [make-exn:fail:filesystem:missing-module](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3afilesystem~3amissing-module%29%29)

    #:transparent)

  path : [module-path?](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._module-path~3f%29%29)

Raised by the default [module name resolver](Module_Names_and_Loading.html#%28tech._module._name._resolver%29) or default [load handler](eval.html#%28tech._load._handler%29) to report a module path—a reported in the path field—whose implementation file cannot be found.


# 10.1 Multiple Values
The default [module name resolver](Module_Names_and_Loading.html#%28tech._module._name._resolver%29) raises this exception only when it is not given a syntax object as its second argument, and the default [load handler](eval.html#%28tech._load._handler%29) raises this exception only when the value of [current-module-path-for-load](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._current-module-path-for-load%29%29) is not a syntax object.
This structure type implements the [prop:exn:missing-module](#%28def._%28%28quote._~23~25kernel%29._prop~3aexn~3amissing-module%29%29) property.
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:network](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) ()

    #:extra-constructor-name [make-exn:fail:network](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3anetwork%29%29)

    #:transparent)

Raised for TCP and UDP errors.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:network:errno](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork~3aerrno%29%29) [exn:fail:network](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3anetwork%29%29) (errno)

    #:extra-constructor-name [make-exn:fail:network:errno](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3anetwork~3aerrno%29%29)

    #:transparent)

  errno : ([cons/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._cons%2Fc%29%29) [exact-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29) ([or/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29) 'posix 'windows 'gai))

Raised for a TCP or UDP error for which a system error code is available, where the errno field is as for [exn:fail:filesystem:errno](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem~3aerrno%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:out-of-memory](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aout-of-memory%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) ()

    #:extra-constructor-name [make-exn:fail:out-of-memory](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3aout-of-memory%29%29)

    #:transparent)

Raised for an error due to insufficient memory, in cases where sufficient memory is at least available for raising the exception.
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:unsupported](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aunsupported%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) ()

    #:extra-constructor-name [make-exn:fail:unsupported](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3aunsupported%29%29)

    #:transparent)


# 10.1 Multiple Values
Raised for an error due to an unsupported feature on the current platform or configuration.
>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:fail:user](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3auser%29%29) [exn:fail](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail%29%29) ()

    #:extra-constructor-name [make-exn:fail:user](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3afail~3auser%29%29)

    #:transparent)

Raised for errors that are intended to be seen by end users. In particular, the default error printer does not show the program context when printing the error message.
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:break](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) [exn](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn%29%29) (continuation)

    #:extra-constructor-name [make-exn:break](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3abreak%29%29)

    #:transparent)

  continuation : [continuation?](cont.html#%28def._%28%28quote._~23~25kernel%29._continuation~3f%29%29)

Raised asynchronously (when enabled) in response to a break request. The continuation field can be used to resume the interrupted computation in the [uncaught-exception handler](#%28tech._uncaught._exception._handler%29) or [call-with-exception-handler](#%28def._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._call-with-exception-handler%29%29) (but not [with-handlers](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._with-handlers%29%29) because it escapes from the exception context before evaluating any predicates or handlers).
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:break:hang-up](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak~3ahang-up%29%29) [exn:break](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) ()

    #:extra-constructor-name [make-exn:break:hang-up](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3abreak~3ahang-up%29%29)

    #:transparent)

Raised asynchronously for hang-up breaks. The default [uncaught-exception handler](#%28tech._uncaught._exception._handler%29) reacts to this exception type by calling the [exit handler](Exiting.html#%28tech._exit._handler%29).
>
<colgroup><col style="width: 100%" /></colgroup>

struct


# 10.1 Multiple Values

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[exn:break:terminate](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak~3aterminate%29%29) [exn:break](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3abreak%29%29) ()

    #:extra-constructor-name [make-exn:break:terminate](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-exn~3abreak~3aterminate%29%29)

    #:transparent)

Raised asynchronously for termination-request breaks. The default [uncaught-exception handler](#%28tech._uncaught._exception._handler%29) reacts to this exception type by calling the [exit handler](Exiting.html#%28tech._exit._handler%29).
>
<colgroup><col style="width: 100%" /></colgroup>

value

[prop:exn:srclocs](#%28def._%28%28quote._~23~25kernel%29._prop~3aexn~3asrclocs%29%29) : [struct-type-property?](structprops.html#%28def._%28%28quote._~23~25kernel%29._struct-type-property~3f%29%29)

A property that identifies structure types that provide a list of [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29) values. The property is normally attached to structure types used to represent exception information.


# 10.1 Multiple Values
The property value must be a procedure that accepts a single value—the structure type instance from which to extract source locations—and returns a list of [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29)s. Some [error display handlers](#%28tech._error._display._handler%29) use only the first returned location.
As an example,
> ```racket
> #lang racket
> ;; We create a structure that supports the
> ;; prop:exn:srcloc protocol. It carries
> ;; with it the location of the syntax that
> ;; is guilty.
> ( struct exn:fail:he-who-shall-not-be-named exn:fail
> ( a-srcloc )
> #:property prop:exn:srclocs
> ( lambda ( a-struct )
> ( match a-struct
> [ ( exn:fail:he-who-shall-not-be-named msg marks a-srcloc )
> ( list a-srcloc ) ] ) ) )
> ;; We can play with this by creating a form that
> ;; looks at identifiers, and only flags specific ones.
> ( define-syntax ( skeeterize stx )
> ( syntax-case stx ( )
> [ ( _ expr )
> ( cond
> [ ( and ( identifier? #' expr )
> ( eq? ( syntax-e #' expr ) ' voldemort ) )
> ( quasisyntax/loc stx
> ( raise ( exn:fail:he-who-shall-not-be-named
> "oh dear don't say his name"
> ( current-continuation-marks )
> ( srcloc ' #, ( syntax-source #' expr )
> ' #, ( syntax-line #' expr )
> ' #, ( syntax-column #' expr )
> ' #, ( syntax-position #' expr )
> ' #, ( syntax-span #' expr ) ) ) ) ) ]
> [ else
> ;; Otherwise, leave the expression alone.
> #' expr ] ) ] ) )
> ( define ( f x )
> ( * ( skeeterize x ) x ) )
> ( define ( g voldemort )
> ( * ( skeeterize voldemort ) voldemort ) )
> ;; Examples:
> ( f 7 )
> ( g 7 )
> ;; The error should highlight the use
> ;; of voldemort in g.
> ```


# 10.1 Multiple Values
> ```
(exn:srclocs? v)  →  boolean?
  v : any/c
```
Returns #t if v has the prop:exn:srclocs property, #f otherwise.

> ```
(exn:srclocs-accessor v)
   →   (exn:srclocs? .  →  . (listof srcloc))
  v : exn:srclocs?```

Returns the [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29)-getting procedure associated with v.

>
<colgroup><col style="width: 100%" /></colgroup>

struct

([struct](define-struct.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._struct%29%29)	 	[srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29) (source line column position span)

    #:extra-constructor-name [make-srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._make-srcloc%29%29)

    #:transparent)

  source : [any/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29)

  line : ([or/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29) [exact-positive-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-positive-integer~3f%29%29) #f)

  column : ([or/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29) [exact-nonnegative-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29) #f)

  position : ([or/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29) [exact-positive-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-positive-integer~3f%29%29) #f)

  span : ([or/c](data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29) [exact-nonnegative-integer?](number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29) #f)

A source location is most frequently represented by a [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29) structure. More generally, a source location has the same information as a [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29) structure, but potentially represented or accessed differently. For example, source-location information is accessed from a [syntax object](syntax-model.html#%28tech._syntax._object%29) with functions like [syntax-source](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-source%29%29) and [syntax-line](stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-line%29%29), while [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) accepts a source location as a list, vector, or another syntax object. For ports, a combination of [object-name](inspectors.html#%28def._%28%28quote._~23~25kernel%29._object-name%29%29) and [port-next-location](linecol.html#%28def._%28%28quote._~23~25kernel%29._port-next-location%29%29) provides location information, especially in a port for which counting has been enabled through [port-count-lines!](linecol.html#%28def._%28%28quote._~23~25kernel%29._port-count-lines%21%29%29).

The fields of a [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29) instance are as follows:

-   source — An arbitrary value identifying the source, often a path (see [Paths](pathutils.html)).

-   line — The line number (counts from 1) or #f (unknown).

-   column — The column number (counts from 0) or #f (unknown).

-   position — The starting position (counts from 1) or #f (unknown).

-   span — The number of covered positions (counts from 0) or #f (unknown).

See [Printing Compiled Code](printing.html#%28part._print-compiled%29) for information about the treatment of [srcloc](#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._srcloc%29%29) values that are embedded in compiled code.

> ```
(srcloc  →  string srcloc)  →  (or/c string? #f)
  srcloc : srcloc?
```