| blob | 4c04301bfcf0d8cc8db1a962ea60235c0dc237be |
1 <html>
2 <head>
5 </head>
6 <body>
8 <p>The 'lazy' vocabulary adds lazy lists to Factor. This provides the
9 ability to describe infinite structures, and to delay execution of
10 expressions until they are actually used.</p>
11 <p>Lazy lists, like normal lists, are composed of a head and tail. In
12 a lazy list the head and tail are something called a 'promise'.
13 To convert a
14 'promise' into its actual value a word called 'force' is used. To
15 convert a value into a 'promise' the word to use is 'delay'.</p>
19 </table>
21 <p>Many of the lazy list words are named similar to the standard list
22 words but with an 'l' suffixed to it. Here are the commonly used
23 words and their equivalent list operation:</p>
38 </table>
42 number of items from the lazy list.</td></tr>
44 concatenate them together in a lazy manner, returning a single lazy
45 list.</td></tr>
47 that contains the same elements as the normal list.</td></tr>
48 </table>
50 <!-- delay description -->
53 <p>'delay' is used to convert a value or expression into a promise.
54 The word 'force' is used to convert that promise back to its
55 value, or to force evaluation of the expression to return a value.
56 </p>
57 <p>The value on the stack that 'delay' expects must be quoted. This is
58 a requirement to prevent it from being evaluated.
59 </p>
65 </pre>
67 <!-- force description -->
70 <p>'force' will evaluate a promises original expression
71 and leave the value of that expression on the stack.
72 </p>
73 <p>A promise can be forced multiple times but the expression
74 is only evaluated once. Future calls of 'force' on the promise
75 will returned the cached value of the original force. If the
76 expression contains side effects, such as i/o, then that i/o
77 will only occur on the first 'force'. See below for an example
79 </p>
80 <p>If a promise is itself delayed, a force will evaluate all promises
81 until a value is returned. Due to this behaviour it is generally not
82 possible to delay a promise. The example below shows what happens
83 in this case.
84 </p>
91 #! Multiple forces on a promise returns cached value
95 => hello
96 42
100 #! Forcing a delayed promise cascades up to return
101 #! original value, rather than the promise.
106 </pre>
108 <!-- lnil description -->
115 </pre>
117 <!-- lnil description -->
120 <p>Returns true if the given lazy cons is the value representing
121 the empty lazy list.</p>
124 => t
126 => [ ]
128 => t
129 </pre>
131 <!-- lcons description -->
134 <p>Provides the same effect as 'cons' does for normal lists.
135 Both values provided must be promises (ie. expressions that have
137 </p>
138 <p>As the car and cdr passed on the stack are promises, they are not
140 are called on the lazy cons.</p>
142 ( 1 ) [ "car" ] <a href="#delay">delay</a> [ "cdr" ] <a href="#delay">delay</a> <a href="#lcons">lcons</a> dup .
148 </pre>
150 <!-- lunit description -->
153 <p>Provides the same effect as 'unit' does for normal lists. It
154 creates a lazy list where the first element is the value given.</p>
157 of the list is requested.</a>
164 => t
167 </pre>
169 <!-- lcar description -->
172 <p>Provides the same effect as 'car' does for normal lists. It
173 returns the first element in a lazy cons cell. This will force
174 the evaluation of that element.</p>
180 </pre>
182 <!-- lcdr description -->
185 <p>Provides the same effect as 'cdr' does for normal lists. It
186 returns the second element in a lazy cons cell and forces it. This
187 causes that element to be evaluated immediately.</p>
189 ( 1 ) [ 1 ] <a href="#delay">delay</a> [ 5 6 + ] <a href="#delay">delay</a> <a href="#lcons">lcons</a> dup .
193 </pre>
204 </pre>
206 <!-- lnth description -->
209 <p>Provides the same effect as 'nth' does for normal lists. It
210 returns the nth value in the lazy list. It causes all the values up to
211 'n' to be evaluated.</p>
217 </pre>
219 <!-- luncons description -->
222 <p>Provides the same effect as 'uncons' does for normal lists. It
223 returns the car and cdr of the lazy list.</p>
225 ( 1 ) [ 5 ] <a href="#delay">delay</a> [ 6 ] <a href="#delay">delay</a> <a href="#lcons">lcons</a> dup .
229 5
230 </pre>
232 <!-- lmap description -->
235 <p>Lazily maps over a lazy list applying the quotation to each element.
236 A new lazy list is returned which contains the results of the
237 quotation.</p>
238 <p>When intially called nothing in the original lazy list is
240 in the list be evaluated and applied to the quotation. Ditto with <a
249 </pre>
251 <!-- lsubset description -->
254 <p>Provides the same effect as 'subset' does for normal lists. It
255 lazily iterates over a lazy list applying the predicate quotation to each
256 element. If that quotation returns true, the element will be included
257 in the resulting lazy list. If it is false, the element will be skipped.
258 A new lazy list is returned which contains all elements where the
259 predicate returned true.</p>
261 will occur. A lazy list is returned that when values are retrieved
262 from in then items are evaluated and checked against the predicate.</p>
270 </pre>
272 <!-- leach description -->
275 <p>Provides the same effect as 'each' does for normal lists. It
276 lazily iterates over a lazy list applying the quotation to each
277 element. If this operation is applied to an infinite list it will
278 never return unless the quotation escapes out by calling a continuation.</p>
286 3
287 5
288 7
289 ... for ever ...
290 </pre>
292 <!-- ltake description -->
295 <p>Iterates over the lazy list 'n' times, appending each element to a
296 lazy list. This provides a convenient way of getting elements out of
297 an infinite lazy list.</p>
302 </pre>
304 <!-- lappend description -->
307 <p>Lazily appends two lists together. The actual appending is done
308 lazily on iteration rather than immediately so it works very fast no
309 matter how large the list.</p>
311 ( 1 ) [ 1 2 3 ] <a href="#list2llist">list>llist</a> [ 4 5 6 ] <a href="#list2llist">list>llist</a> <a href="#lappend">lappend</a>
314 2
315 3
316 4
317 5
318 6
319 </pre>
321 <!-- lappend* description -->
324 <p>Given a lazy list of lazy lists, concatenate them together in a
325 lazy fashion. The actual appending is done lazily on iteration rather
326 than immediately so it works very fast no matter how large the lists.</p>
334 2
335 3
336 4
337 5
338 6
339 7
340 8
341 9
342 </pre>
344 <!-- list>llist description -->
347 <p>Converts a normal list into a lazy list. This is done lazily so the
348 initial list is not iterated through immediately.</p>
353 2
354 3
355 </pre>
358 News and updates to this software can be obtained from the authors
361 </body> </html>