Debian Codegraph @

info/gcl/typecase.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html>
3 <!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>typecase (ANSI and GNU Common Lisp Document)</title>
7
8 <meta name="description" content="typecase (ANSI and GNU Common Lisp Document)">
9 <meta name="keywords" content="typecase (ANSI and GNU Common Lisp Document)">
10 <meta name="resource-type" content="document">
11 <meta name="distribution" content="global">
12 <meta name="Generator" content="makeinfo">
13 <link href="index.html" rel="start" title="Top">
14 <link href="Data-and-Control-Flow-Dictionary.html" rel="up" title="Data and Control Flow Dictionary">
15 <link href="multiple_002dvalue_002dbind.html" rel="next" title="multiple-value-bind">
16 <link href="case.html" rel="prev" title="case">
17 <style type="text/css">
18 <!--
19 a.summary-letter {text-decoration: none}
20 blockquote.indentedblock {margin-right: 0em}
21 div.display {margin-left: 3.2em}
22 div.example {margin-left: 3.2em}
23 div.lisp {margin-left: 3.2em}
24 kbd {font-style: oblique}
25 pre.display {font-family: inherit}
26 pre.format {font-family: inherit}
27 pre.menu-comment {font-family: serif}
28 pre.menu-preformatted {font-family: serif}
29 span.nolinebreak {white-space: nowrap}
30 span.roman {font-family: initial; font-weight: normal}
31 span.sansserif {font-family: sans-serif; font-weight: normal}
32 ul.no-bullet {list-style: none}
33 -->
34 </style>
35
36
37 </head>
38
39 <body lang="en">
40 <span id="typecase"></span><div class="header">
41 <p>
42 Next: <a href="multiple_002dvalue_002dbind.html" accesskey="n" rel="next">multiple-value-bind</a>, Previous: <a href="case.html" accesskey="p" rel="prev">case</a>, Up: <a href="Data-and-Control-Flow-Dictionary.html" accesskey="u" rel="up">Data and Control Flow Dictionary</a> &nbsp; </p>
43 </div>
44 <hr>
45 <span id="typecase_002c-ctypecase_002c-etypecase-_005bMacro_005d"></span><h4 class="subsection">5.3.47 typecase, ctypecase, etypecase [Macro]</h4>
46
47 <p><code>typecase</code> <i>keyform {!<i>normal-clause</i>}* <span class="roman">[</span>!<i>otherwise-clause</i><span class="roman">]</span></i> &rArr; <i>{<i>result</i>}*</i>
48 </p>
49 <p><code>ctypecase</code> <i>keyplace {!<i>normal-clause</i>}*</i> &rArr; <i>{<i>result</i>}*</i>
50 </p>
51 <p><code>etypecase</code> <i>keyform {!<i>normal-clause</i>}*</i> &rArr; <i>{<i>result</i>}*</i>
52 </p>
53 <p><i><span class="nolinebreak">normal-clause</span></i>&nbsp;::=<span class="roman">(</span>type&nbsp;{<i>form</i>}*<span class="roman">)</span><!-- /@w -->
54 </p>
55 <p><i><span class="nolinebreak">otherwise-clause</span></i>&nbsp;::=<span class="roman">(</span>{otherwise&nbsp;|&nbsp;t}&nbsp;{<i>form</i>}*<span class="roman">)</span><!-- /@w -->
56 </p>
57 <p><i>clause</i>&nbsp;<span class="nolinebreak">::=normal-clause</span>&nbsp;|&nbsp;<span class="nolinebreak">otherwise-clause</span><!-- /@w -->
58 </p>
59 <span id="index-otherwise-1"></span>
60
61 <span id="index-t-2"></span>
62
63 <span id="Arguments-and-Values_003a_003a-66"></span><h4 class="subsubheading">Arguments and Values::</h4>
64
65 <p><i>keyform</i>&mdash;a <i>form</i>; evaluated to produce a <i>test-key</i>.
66 </p>
67 <p><i>keyplace</i>&mdash;a <i>form</i>; evaluated initially to produce a <i>test-key</i>.
68 Possibly also used later as a <i>place</i> if no <i>types</i> match.
69 </p>
70 <p><i>test-key</i>&mdash;an object produced by evaluating <i>keyform</i> or <i>keyplace</i>.
71 </p>
72 <p><i>type</i>&mdash;a <i>type specifier</i>.
73 </p>
74 <p><i>forms</i>&mdash;an <i>implicit progn</i>.
75 </p>
76 <p><i>results</i>&mdash;the <i>values</i> returned by the <i>forms</i>
77 in the matching <i>clause</i>.
78 </p>
79 <span id="Description_003a_003a-100"></span><h4 class="subsubheading">Description::</h4>
80
81 <p>These <i>macros</i> allow the conditional execution of a body of <i>forms</i>
82 in a <i>clause</i> that is selected by matching the <i>test-key</i> on the basis
83 of its <i>type</i>.
84 </p>
85 <p>The <i>keyform</i> or <i>keyplace</i> is <i>evaluated</i> to produce the
86 <i>test-key</i>.
87 </p>
88 <p>Each of the <i>normal-clauses</i> is then considered in turn.
89 If the <i>test-key</i> is of the <i>type</i>
90 given by the <i>clauses</i>&rsquo;s <i>type</i>,
91 the <i>forms</i> in that <i>clause</i> are
92 <i>evaluated</i> as an <i>implicit progn</i>, and the <i>values</i>
93 it returns are returned as the value of the <b>typecase</b>,
94 <b>ctypecase</b>, or <b>etypecase</b> <i>form</i>.
95 </p>
96 <p>These <i>macros</i> differ only in their <i>behavior</i> when
97 no <i>normal-clause</i> matches; specifically:
98 </p>
99 <dl compact="compact">
100 <dt><b>typecase</b></dt>
101 <dd><p>If no <i>normal-clause</i> matches, and there is an <i>otherwise-clause</i>,
102 then that <i>otherwise-clause</i> automatically matches; the <i>forms</i> in
103 that <i>clause</i> are <i>evaluated</i> as an <i>implicit progn</i>,
104 and the <i>values</i> it returns are returned as the value of the <b>typecase</b>.
105 </p>
106 <p>If there is no <i>otherwise-clause</i>, <b>typecase</b> returns <b>nil</b>.
107 </p>
108 </dd>
109 <dt><b>ctypecase</b></dt>
110 <dd><p>If no <i>normal-clause</i> matches,
111 a <i>correctable</i> <i>error</i> of <i>type</i> <b>type-error</b> is signaled.
112 The offending datum is the <i>test-key</i> and
113 the expected type is <i>type equivalent</i> to <tt>(or <i>type1</i> <i>type2</i> ...)</tt>.
114 The <b>store-value</b> <i>restart</i> can be used to correct the error.
115 </p>
116 <p>If the <b>store-value</b> <i>restart</i> is invoked, its <i>argument</i> becomes the
117 new <i>test-key</i>, and is stored in <i>keyplace</i> as if by
118 <tt>(setf <i>keyplace</i> <i>test-key</i>)</tt>.
119 Then <b>ctypecase</b> starts over, considering each <i>clause</i> anew.
120 </p>
121 <p>If the <b>store-value</b> <i>restart</i> is invoked interactively,
122 the user is prompted for a new <i>test-key</i> to use.
123 </p>
124 <p>The subforms of <i>keyplace</i> might be evaluated again if
125 none of the cases holds.
126 </p>
127 </dd>
128 <dt><b>etypecase</b></dt>
129 <dd><p>If no <i>normal-clause</i> matches,
130 a <i>non-correctable</i> <i>error</i> of <i>type</i> <b>type-error</b> is signaled.
131 The offending datum is the <i>test-key</i> and
132 the expected type is <i>type equivalent</i> to <tt>(or <i>type1</i> <i>type2</i> ...)</tt>.
133 </p>
134 <p>Note that in contrast with <b>ctypecase</b>,
135 the caller of <b>etypecase</b> may rely on the fact that <b>etypecase</b>
136 does not return if a <i>normal-clause</i> does not match.
137 </p>
138 </dd>
139 </dl>
140
141 <p>In all three cases, is permissible for more than one <i>clause</i> to specify a
142 matching <i>type</i>, particularly if one is a <i>subtype</i> of another;
143 the earliest applicable <i>clause</i> is chosen.
144 </p>
145 <span id="Examples_003a_003a-74"></span><h4 class="subsubheading">Examples::</h4>
146
147 <div class="example">
148 <pre class="example">;;; (Note that the parts of this example which use TYPE-OF
149 ;;; are implementation-dependent.)
150 (defun what-is-it (x)
151 (format t &quot;~&amp;~S is ~A.~
152 x (typecase x
153 (float &quot;a float&quot;)
154 (null &quot;a symbol, boolean false, or the empty list&quot;)
155 (list &quot;a list&quot;)
156 (t (format nil &quot;a(n) ~(~A~)&quot; (type-of x))))))
157 &rArr; WHAT-IS-IT
158 (map 'nil #'what-is-it '(nil (a b) 7.0 7 box))
159 <tt> |&gt; </tt> NIL is a symbol, boolean false, or the empty list.
160 <tt> |&gt; </tt> (A B) is a list.
161 <tt> |&gt; </tt> 7.0 is a float.
162 <tt> |&gt; </tt> 7 is a(n) integer.
163 <tt> |&gt; </tt> BOX is a(n) symbol.
164 &rArr; NIL
165 (setq x 1/3)
166 &rArr; 1/3
167 (ctypecase x
168 (integer (* x 4))
169 (symbol (symbol-value x)))
170 <tt> |&gt; </tt> Error: The value of X, 1/3, is neither an integer nor a symbol.
171 <tt> |&gt; </tt> To continue, type :CONTINUE followed by an option number:
172 <tt> |&gt; </tt> 1: Specify a value to use instead.
173 <tt> |&gt; </tt> 2: Return to Lisp Toplevel.
174 <tt> |&gt; </tt> Debug&gt; <b>|&gt;&gt;</b><tt>:CONTINUE 1</tt><b>&lt;&lt;|</b>
175 <tt> |&gt; </tt> Use value: <b>|&gt;&gt;</b><tt>3.7</tt><b>&lt;&lt;|</b>
176 <tt> |&gt; </tt> Error: The value of X, 3.7, is neither an integer nor a symbol.
177 <tt> |&gt; </tt> To continue, type :CONTINUE followed by an option number:
178 <tt> |&gt; </tt> 1: Specify a value to use instead.
179 <tt> |&gt; </tt> 2: Return to Lisp Toplevel.
180 <tt> |&gt; </tt> Debug&gt; <b>|&gt;&gt;</b><tt>:CONTINUE 1</tt><b>&lt;&lt;|</b>
181 <tt> |&gt; </tt> Use value: <b>|&gt;&gt;</b><tt>12</tt><b>&lt;&lt;|</b>
182 &rArr; 48
183 x &rArr; 12
184 </pre></div>
185
186 <span id="Affected-By_003a_003a-6"></span><h4 class="subsubheading">Affected By::</h4>
187
188 <p><b>ctypecase</b> and <b>etypecase</b>, since they might signal an error,
189 are potentially affected by existing <i>handlers</i> and <b>*debug-io*</b>.
190 </p>
191 <span id="Exceptional-Situations_003a_003a-19"></span><h4 class="subsubheading">Exceptional Situations::</h4>
192
193 <p><b>ctypecase</b> and <b>etypecase</b> signal an error of <i>type</i> <b>type-error</b>
194 if no <i>normal-clause</i> matches.
195 </p>
196 <p>The <i>compiler</i> may choose to issue a warning of <i>type</i> <b>style-warning</b>
197 if a <i>clause</i> will never be selected because it is completely
198 shadowed by earlier clauses.
199 </p>
200 <span id="See-Also_003a_003a-84"></span><h4 class="subsubheading">See Also::</h4>
201
202 <p><a href="case.html">case</a>
203 ,
204 <a href="cond.html">cond</a>
205 ,
206 <a href="setf.html">setf</a>
207 ,
208 <a href="Generalized-Reference.html">Generalized Reference</a>
209 </p>
210 <span id="Notes_003a_003a-54"></span><h4 class="subsubheading">Notes::</h4>
211
212 <div class="example">
213 <pre class="example">(typecase <i>test-key</i>
214 {(<i>type</i> {<i>form</i>}*)}*)
215 &equiv;
216 (let ((#1=#:g0001 <i>test-key</i>))
217 (cond {((typep #1# '<i>type</i>) {<i>form</i>}*)}*))
218 </pre></div>
219
220 <p>The specific error message used by <b>etypecase</b> and <b>ctypecase</b> can vary
221 between implementations. In situations where control of the specific wording
222 of the error message is important, it is better to use <b>typecase</b> with an
223 <i>otherwise-clause</i> that explicitly signals an error with an appropriate
224 message.
225 </p>
226 <hr>
227 <div class="header">
228 <p>
229 Next: <a href="multiple_002dvalue_002dbind.html" accesskey="n" rel="next">multiple-value-bind</a>, Previous: <a href="case.html" accesskey="p" rel="prev">case</a>, Up: <a href="Data-and-Control-Flow-Dictionary.html" accesskey="u" rel="up">Data and Control Flow Dictionary</a> &nbsp; </p>
230 </div>
231
232
233
234 </body>
235 </html>