/core/kernel/kernel-docs.factor

  1USING: generic help.markup help.syntax math memory
  2namespaces sequences kernel.private layouts classes
  3vectors combinators quotations strings words
  4assocs arrays math.order ;
  5IN: kernel
  6
  7HELP: eq?
  8{ $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
  9{ $description "Tests if two references point at the same object." } ;
 10
 11HELP: drop  $shuffle ;
 12HELP: 2drop $shuffle ;
 13HELP: 3drop $shuffle ;
 14HELP: 4drop $shuffle ;
 15HELP: dup   $shuffle ;
 16HELP: 2dup  $shuffle ;
 17HELP: 3dup  $shuffle ;
 18HELP: 4dup  $shuffle ;
 19HELP: nip   $shuffle ;
 20HELP: 2nip  $shuffle ;
 21HELP: over  $shuffle ;
 22HELP: 2over $shuffle ;
 23HELP: pick  $shuffle ;
 24HELP: swap  $shuffle ;
 25
 26HELP: rot   $complex-shuffle ;
 27HELP: -rot  $complex-shuffle ;
 28HELP: dupd  $complex-shuffle ;
 29HELP: swapd $complex-shuffle ;
 30
 31HELP: datastack
 32{ $values { "array" array } }
 33{ $description "Outputs an array containing a copy of the data stack contents right before the call to this word, with the top of the stack at the end of the array." } ;
 34
 35HELP: set-datastack
 36{ $values { "array" array } }
 37{ $description "Replaces the data stack contents with a copy of an array. The end of the array becomes the top of the stack." } ;
 38
 39HELP: retainstack
 40{ $values { "array" array } }
 41{ $description "Outputs an array containing a copy of the retain stack contents right before the call to this word, with the top of the stack at the end of the array." } ;
 42
 43HELP: set-retainstack
 44{ $values { "array" array } }
 45{ $description "Replaces the retain stack contents with a copy of an array. The end of the array becomes the top of the stack." } ;
 46
 47HELP: callstack
 48{ $values { "callstack" callstack } }
 49{ $description "Outputs a copy of the call stack contents, with the top of the stack at the end of the vector. The stack frame of the caller word is " { $emphasis "not" } " included." } ;
 50
 51HELP: set-callstack
 52{ $values { "callstack" callstack } }
 53{ $description "Replaces the call stack contents. Control flow is transferred immediately to the innermost frame of the new call stack." } ;
 54
 55HELP: clear
 56{ $description "Clears the data stack." } ;
 57
 58HELP: build
 59{ $values { "n" integer } }
 60{ $description "The current build number. Factor increments this number whenever a new boot image is created." } ;
 61
 62HELP: hashcode*
 63{ $values { "depth" integer } { "obj" object } { "code" fixnum } }
 64{ $contract "Outputs the hashcode of an object. The hashcode operation must satisfy the following properties:"
 65{ $list
 66    { "If two objects are equal under " { $link = } ", they must have equal hashcodes." }
 67    { "If the hashcode of an object depends on the values of its slots, the hashcode of the slots must be computed recursively by calling " { $link hashcode* } " with a " { $snippet "level" } " parameter decremented by one. This avoids excessive work while still computing well-distributed hashcodes. The " { $link recursive-hashcode } " combinator can help with implementing this logic," }
 68    { "The hashcode should be a " { $link fixnum } ", however returning a " { $link bignum } " will not cause any problems other than potential performance degradation." }
 69    { "The hashcode is only permitted to change between two invocations if the object or one of its slot values was mutated." }
 70}
 71"If mutable objects are used as hashtable keys, they must not be mutated in such a way that their hashcode changes. Doing so will violate bucket sorting invariants and result in undefined behavior. See " { $link "hashtables.keys" } " for details." } ;
 72
 73HELP: hashcode
 74{ $values { "obj" object } { "code" fixnum } }
 75{ $description "Computes the hashcode of an object with a default hashing depth. See " { $link hashcode* } " for the hashcode contract." } ;
 76
 77HELP: identity-hashcode
 78{ $values { "obj" object } { "code" fixnum } }
 79{ $description "Outputs the identity hashcode of an object. The identity hashcode is not guaranteed to be unique, however it will not change during the object's lifetime." } ;
 80
 81{ hashcode hashcode* identity-hashcode } related-words
 82
 83HELP: =
 84{ $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
 85{ $description
 86    "Tests if two objects are equal. If " { $snippet "obj1" } " and " { $snippet "obj2" } " point to the same object, outputs " { $link t } ". Otherwise, calls the " { $link equal? } " generic word."
 87}
 88{ $examples
 89    { $example "USING: kernel prettyprint ;" "5 5 = ." "t" }
 90    { $example "USING: kernel prettyprint ;" "5 005 = ." "t" }
 91    { $example "USING: kernel prettyprint ;" "5 5.0 = ." "f" }
 92    { $example "USING: arrays kernel prettyprint ;" "{ \"a\" \"b\" } \"a\" \"b\" 2array = ." "t" }
 93    { $example "USING: arrays kernel prettyprint ;" "{ \"a\" \"b\" } [ \"a\" \"b\" ] = ." "f" }
 94} ;
 95
 96HELP: equal?
 97{ $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
 98{ $contract
 99    "Tests if two objects are equal."
100    $nl
101    "User code should call " { $link = } " instead; that word first tests the case where the objects are " { $link eq? } ", and so by extension, methods defined on " { $link equal? } " assume they are never called on " { $link eq? } " objects."
102    $nl
103    "Method definitions should ensure that this is an equality relation, modulo the assumption that the two objects are not " { $link eq? } ". That is, for any three non-" { $link eq? } " objects " { $snippet "a" } ", " { $snippet "b" } " and " { $snippet "c" } ", we must have:"
104    { $list
105        { { $snippet "a = b" } " implies " { $snippet "b = a" } }
106        { { $snippet "a = b" } " and " { $snippet "b = c" } " implies " { $snippet "a = c" } }
107    }
108    "If a class defines a custom equality comparison test, it should also define a compatible method for the " { $link hashcode* } " generic word."
109}
110{ $examples
111    "An example demonstrating why this word should only be used to define methods on, and never called directly:"
112    { $example "USING: kernel prettyprint ;" "5 5 equal? ." "f" }
113    "Using " { $link = } " gives the expected behavior:"
114    { $example "USING: kernel prettyprint ;" "5 5 = ." "t" }
115} ;
116
117HELP: identity-tuple
118{ $class-description "A class defining an " { $link equal? } " method which always returns f." }
119{ $examples
120    "To define a tuple class such that two instances are only equal if they are both the same instance, inherit from the " { $link identity-tuple } " class. This class defines a method on " { $link equal? } " which always returns " { $link f } ". Since " { $link = } " handles the case where the two objects are " { $link eq? } ", this method will never be called with two " { $link eq? } " objects, so such a definition is valid:"
121    { $code "TUPLE: foo < identity-tuple ;" }
122    "By calling " { $link = } " on instances of " { $snippet "foo" } " we get the results we expect:"
123    { $unchecked-example "T{ foo } dup = ." "t" }
124    { $unchecked-example "T{ foo } dup clone = ." "f" }
125} ;
126
127HELP: clone
128{ $values { "obj" object } { "cloned" "a new object" } }
129{ $contract "Outputs a new object equal to the given object. This is not guaranteed to actually copy the object; it does nothing with immutable objects, and does not copy words either. However, sequences and tuples can be cloned to obtain a shallow copy of the original." } ;
130
131HELP: ?
132{ $values { "?" "a generalized boolean" } { "true" object } { "false" object } { "true/false" "one two input objects" } }
133{ $description "Chooses between two values depending on the boolean value of " { $snippet "cond" } "." } ;
134
135HELP: boolean
136{ $class-description "A union of the " { $link POSTPONE: t } " and " { $link POSTPONE: f } " classes." } ;
137
138HELP: >boolean
139{ $values { "obj" "a generalized boolean" } { "?" "a boolean" } }
140{ $description "Convert a generalized boolean into a boolean. That is, " { $link f } " retains its value, whereas anything else becomes " { $link t } "." } ;
141
142HELP: not
143{ $values { "obj" "a generalized boolean" } { "?" "a boolean" } }
144{ $description "For " { $link f } " outputs " { $link t } " and for anything else outputs " { $link f } "." }
145{ $notes "This word implements boolean not, so applying it to integers will not yield useful results (all integers have a true value). Bitwise not is the " { $link bitnot } " word." } ;
146
147HELP: and
148{ $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "?" "a generalized boolean" } }
149{ $description "If both inputs are true, outputs " { $snippet "obj2" } ". otherwise outputs " { $link f } "." }
150{ $notes "This word implements boolean and, so applying it to integers will not yield useful results (all integers have a true value). Bitwise and is the " { $link bitand } " word." }
151{ $examples
152    "Usually only the boolean value of the result is used, however you can also explicitly rely on the behavior that if both inputs are true, the second is output:"
153    { $example "USING: kernel prettyprint ;" "t f and ." "f" }
154    { $example "USING: kernel prettyprint ;" "t 7 and ." "7" }
155    { $example "USING: kernel prettyprint ;" "\"hi\" 12.0 and ." "12.0" }
156} ;
157
158HELP: or
159{ $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "?" "a generalized boolean" } }
160{ $description "If both inputs are false, outputs " { $link f } ". otherwise outputs the first of " { $snippet "obj1" } " and " { $snippet "obj2" } " which is true." }
161{ $notes "This word implements boolean inclusive or, so applying it to integers will not yield useful results (all integers have a true value). Bitwise inclusive or is the " { $link bitor } " word." }
162{ $examples
163    "Usually only the boolean value of the result is used, however you can also explicitly rely on the behavior that the result will be the first true input:"
164    { $example "USING: kernel prettyprint ;" "t f or ." "t" }
165    { $example "USING: kernel prettyprint ;" "\"hi\" 12.0 or ." "\"hi\"" }
166} ;
167
168HELP: xor
169{ $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "?" "a generalized boolean" } }
170{ $description "If exactly one input is false, outputs the other input. Otherwise outputs " { $link f } "." }
171{ $notes "This word implements boolean exclusive or, so applying it to integers will not yield useful results (all integers have a true value). Bitwise exclusive or is the " { $link bitxor } " word." } ;
172
173HELP: both?
174{ $values { "x" object } { "y" object } { "quot" { $quotation "( ... obj -- ... ? )" } } { "?" "a boolean" } }
175{ $description "Tests if the quotation yields a true value when applied to both " { $snippet "x" } " and " { $snippet "y" } "." }
176{ $examples
177    { $example "USING: kernel math prettyprint ;" "3 5 [ odd? ] both? ." "t" }
178    { $example "USING: kernel math prettyprint ;" "12 7 [ even? ] both? ." "f" }
179} ;
180
181HELP: either?
182{ $values { "x" object } { "y" object } { "quot" { $quotation "( ... obj -- ... ? )" } } { "?" "a boolean" } }
183{ $description "Tests if the quotation yields a true value when applied to either " { $snippet "x" } " or " { $snippet "y" } "." }
184{ $examples
185    { $example "USING: kernel math prettyprint ;" "3 6 [ odd? ] either? ." "t" }
186    { $example "USING: kernel math prettyprint ;" "5 7 [ even? ] either? ." "f" }
187} ;
188
189HELP: same?
190{ $values { "x" object } { "y" object } { "quot" { $quotation "( ... obj -- ... obj' )" } } { "?" "a boolean" } }
191{ $description "Applies the quotation to both " { $snippet "x" } " and " { $snippet "y" } ", and then checks if the results are equal." }
192{ $examples
193    { $example "USING: kernel math prettyprint ;" "4 5 [ 2/ ] same? ." "t" }
194    { $example "USING: kernel math prettyprint ;" "3 7 [ sq ] same? ." "f" }
195} ;
196
197HELP: execute
198{ $values { "word" word } }
199{ $description "Executes a word. Words which " { $link execute } " an input parameter must be declared " { $link POSTPONE: inline } " so that a caller which passes in a literal word can have a static stack effect." }
200{ $examples
201    { $example "USING: kernel io words ;" "IN: scratchpad" ": twice ( word -- ) dup execute execute ; inline\n: hello ( -- ) \"Hello\" print ;\n\\ hello twice" "Hello\nHello" }
202} ;
203
204{ execute POSTPONE: execute( } related-words
205
206HELP: (execute)
207{ $values { "word" word } }
208{ $description "Executes a word without checking if it is a word first." }
209{ $warning "This word is in the " { $vocab-link "kernel.private" } " vocabulary because it is unsafe. Calling with a parameter that is not a word will crash Factor. Use " { $link execute } " instead." } ;
210
211HELP: call
212{ $values { "callable" callable } }
213{ $description "Calls a quotation. Words which " { $link call } " an input parameter must be declared " { $link POSTPONE: inline } " so that a caller which passes in a literal quotation can have a static stack effect." }
214{ $examples
215    "The following two lines are equivalent:"
216    { $code "2 [ 2 + 3 * ] call" "2 2 + 3 *" }
217} ;
218
219{ call POSTPONE: call( } related-words
220
221HELP: keep
222{ $values { "x" object } { "quot" { $quotation "( ..a x -- ..b )" } } }
223{ $description "Call a quotation with a value on the stack, restoring the value when the quotation returns." }
224{ $examples
225    { $example "USING: arrays kernel prettyprint ;" "2 \"greetings\" [ <array> ] keep 2array ." "{ { \"greetings\" \"greetings\" } \"greetings\" }" }
226} ;
227
228HELP: 2keep
229{ $values { "x" object } { "y" object } { "quot" { $quotation "( ..a x y -- ..b )" } } }
230{ $description "Call a quotation with two values on the stack, restoring the values when the quotation returns." } ;
231
232HELP: 3keep
233{ $values { "x" object } { "y" object } { "z" object } { "quot" { $quotation "( ..a x y z -- ..b )" } } }
234{ $description "Call a quotation with three values on the stack, restoring the values when the quotation returns." } ;
235
236HELP: bi
237{ $values { "x" object } { "p" { $quotation "( ..a x -- ..b )" } } { "q" { $quotation "( ..c x -- ..d )" } } }
238{ $description "Applies " { $snippet "p" } " to " { $snippet "x" } ", then applies " { $snippet "q" } " to " { $snippet "x" } "." }
239{ $examples
240    "If " { $snippet "[ p ]" } " and " { $snippet "[ q ]" } " have stack effect " { $snippet "( x -- )" } ", then the following two lines are equivalent:"
241    { $code
242        "[ p ] [ q ] bi"
243        "dup p q"
244    }
245    "If " { $snippet "[ p ]" } " and " { $snippet "[ q ]" } " have stack effect " { $snippet "( x -- y )" } ", then the following two lines are equivalent:"
246    { $code
247        "[ p ] [ q ] bi"
248        "dup p swap q"
249    }
250    "In general, the following two lines are equivalent:"
251    { $code
252        "[ p ] [ q ] bi"
253        "[ p ] keep q"
254    }
255
256} ;
257
258HELP: 2bi
259{ $values { "x" object } { "y" object } { "p" { $quotation "( x y -- ... )" } } { "q" { $quotation "( x y -- ... )" } } }
260{ $description "Applies " { $snippet "p" } " to the two input values, then applies " { $snippet "q" } " to the two input values." }
261{ $examples
262    "If " { $snippet "[ p ]" } " and " { $snippet "[ q ]" } " have stack effect " { $snippet "( x y -- )" } ", then the following two lines are equivalent:"
263    { $code
264        "[ p ] [ q ] 2bi"
265        "2dup p q"
266    }
267    "If " { $snippet "[ p ]" } " and " { $snippet "[ q ]" } " have stack effect " { $snippet "( x y -- z )" } ", then the following two lines are equivalent:"
268    { $code
269        "[ p ] [ q ] 2bi"
270        "2dup p -rot q"
271    }
272    "In general, the following two lines are equivalent:"
273    { $code
274        "[ p ] [ q ] 2bi"
275        "[ p ] 2keep q"
276    }
277} ;
278
279HELP: 3bi
280{ $values { "x" object } { "y" object } { "z" object } { "p" { $quotation "( x y z -- ... )" } } { "q" { $quotation "( x y z -- ... )" } } }
281{ $description "Applies " { $snippet "p" } " to the three input values, then applies " { $snippet "q" } " to the three input values." }
282{ $examples
283    "If " { $snippet "[ p ]" } " and " { $snippet "[ q ]" } " have stack effect " { $snippet "( x y z -- )" } ", then the following two lines are equivalent:"
284    { $code
285        "[ p ] [ q ] 3bi"
286        "3dup p q"
287    }
288    "In general, the following two lines are equivalent:"
289    { $code
290        "[ p ] [ q ] 3bi"
291        "[ p ] 3keep q"
292    }
293} ;
294
295HELP: tri
296{ $values { "x" object } { "p" { $quotation "( x -- ... )" } } { "q" { $quotation "( x -- ... )" } } { "r" { $quotation "( x -- ... )" } } }
297{ $description "Applies " { $snippet "p" } " to " { $snippet "x" } ", then applies " { $snippet "q" } " to " { $snippet "x" } ", and finally applies " { $snippet "r" } " to " { $snippet "x" } "." }
298{ $examples
299    "If " { $snippet "[ p ]" } ", " { $snippet "[ q ]" } " and " { $snippet "[ r ]" } " have stack effect " { $snippet "( x -- )" } ", then the following two lines are equivalent:"
300    { $code
301        "[ p ] [ q ] [ r ] tri"
302        "dup p dup q r"
303    }
304    "If " { $snippet "[ p ]" } ", " { $snippet "[ q ]" } " and " { $snippet "[ r ]" } " have stack effect " { $snippet "( x -- y )" } ", then the following two lines are equivalent:"
305    { $code
306        "[ p ] [ q ] [ r ] tri"
307        "dup p over q rot r"
308    }
309    "In general, the following two lines are equivalent:"
310    { $code
311        "[ p ] [ q ] [ r ] tri"
312        "[ p ] keep [ q ] keep r"
313    }
314} ;
315
316HELP: 2tri
317{ $values { "x" object } { "y" object } { "p" { $quotation "( x y -- ... )" } } { "q" { $quotation "( x y -- ... )" } } { "r" { $quotation "( x y -- ... )" } } }
318{ $description "Applies " { $snippet "p" } " to the two input values, then applies " { $snippet "q" } " to the two input values, and finally applies " { $snippet "r" } " to the two input values." }
319{ $examples
320    "If " { $snippet "[ p ]" } ", " { $snippet "[ q ]" } " and " { $snippet "[ r ]" } " have stack effect " { $snippet "( x y -- )" } ", then the following two lines are equivalent:"
321    { $code
322        "[ p ] [ q ] [ r ] 2tri"
323        "2dup p 2dup q r"
324    }
325    "In general, the following two lines are equivalent:"
326    { $code
327        "[ p ] [ q ] [ r ] 2tri"
328        "[ p ] 2keep [ q ] 2keep r"
329    }
330} ;
331
332HELP: 3tri
333{ $values { "x" object } { "y" object } { "z" object } { "p" { $quotation "( x y z -- ... )" } } { "q" { $quotation "( x y z -- ... )" } } { "r" { $quotation "( x y z -- ... )" } } }
334{ $description "Applies " { $snippet "p" } " to the three input values, then applies " { $snippet "q" } " to the three input values, and finally applies " { $snippet "r" } " to the three input values." }
335{ $examples
336    "If " { $snippet "[ p ]" } ", " { $snippet "[ q ]" } " and " { $snippet "[ r ]" } " have stack effect " { $snippet "( x y z -- )" } ", then the following two lines are equivalent:"
337    { $code
338        "[ p ] [ q ] [ r ] 3tri"
339        "3dup p 3dup q r"
340    }
341    "In general, the following two lines are equivalent:"
342    { $code
343        "[ p ] [ q ] [ r ] 3tri"
344        "[ p ] 3keep [ q ] 3keep r"
345    }
346} ;
347
348
349HELP: bi*
350{ $values { "x" object } { "y" object } { "p" { $quotation "( x -- ... )" } } { "q" { $quotation "( y -- ... )" } } }
351{ $description "Applies " { $snippet "p" } " to " { $snippet "x" } ", then applies " { $snippet "q" } " to " { $snippet "y" } "." }
352{ $examples
353    "The following two lines are equivalent:"
354    { $code
355        "[ p ] [ q ] bi*"
356        "[ p ] dip q"
357    }
358} ;
359
360HELP: 2bi*
361{ $values { "w" object } { "x" object } { "y" object } { "z" object } { "p" { $quotation "( w x -- ... )" } } { "q" { $quotation "( y z -- ... )" } } }
362{ $description "Applies " { $snippet "p" } " to " { $snippet "w" } " and " { $snippet "x" } ", then applies " { $snippet "q" } " to " { $snippet "y" } " and " { $snippet "z" } "." }
363{ $examples
364    "The following two lines are equivalent:"
365    { $code
366        "[ p ] [ q ] 2bi*"
367        "[ p ] 2dip q"
368    }
369} ;
370
371HELP: 2tri*
372{ $values { "u" object } { "v" object } { "w" object } { "x" object } { "y" object } { "z" object } { "p" { $quotation "( u v -- ... )" } } { "q" { $quotation "( w x -- ... )" } } { "r" { $quotation "( y z -- ... )" } } }
373{ $description "Applies " { $snippet "p" } " to " { $snippet "u" } " and " { $snippet "v" } ", then applies " { $snippet "q" } " to " { $snippet "w" } " and " { $snippet "x" } ", and finally applies " { $snippet "r" } " to " { $snippet "y" } " and " { $snippet "z" } "." }
374{ $examples
375    "The following two lines are equivalent:"
376    { $code
377        "[ p ] [ q ] [ r ] 2tri*"
378        "[ [ p ] 2dip q ] 2dip r"
379    }
380} ;
381
382HELP: tri*
383{ $values { "x" object } { "y" object } { "z" object } { "p" { $quotation "( x -- ... )" } } { "q" { $quotation "( y -- ... )" } } { "r" { $quotation "( z -- ... )" } } }
384{ $description "Applies " { $snippet "p" } " to " { $snippet "x" } ", then applies " { $snippet "q" } " to " { $snippet "y" } ", and finally applies " { $snippet "r" } " to " { $snippet "z" } "." }
385{ $examples
386    "The following two lines are equivalent:"
387    { $code
388        "[ p ] [ q ] [ r ] tri*"
389        "[ [ p ] dip q ] dip r"
390    }
391} ;
392
393HELP: bi@
394{ $values { "x" object } { "y" object } { "quot" { $quotation "( obj -- ... )" } } }
395{ $description "Applies the quotation to " { $snippet "x" } ", then to " { $snippet "y" } "." }
396{ $examples
397    "The following two lines are equivalent:"
398    { $code
399        "[ p ] bi@"
400        "[ p ] dip p"
401    }
402    "The following two lines are also equivalent:"
403    { $code
404        "[ p ] bi@"
405        "[ p ] [ p ] bi*"
406    }
407} ;
408
409HELP: 2bi@
410{ $values { "w" object } { "x" object } { "y" object } { "z" object } { "quot" { $quotation "( obj1 obj2 -- ... )" } } }
411{ $description "Applies the quotation to " { $snippet "w" } " and " { $snippet "x" } ", then to " { $snippet "y" } " and " { $snippet "z" } "." }
412{ $examples
413    "The following two lines are equivalent:"
414    { $code
415        "[ p ] 2bi@"
416        "[ p ] 2dip p"
417    }
418    "The following two lines are also equivalent:"
419    { $code
420        "[ p ] 2bi@"
421        "[ p ] [ p ] 2bi*"
422    }
423} ;
424
425HELP: tri@
426{ $values { "x" object } { "y" object } { "z" object } { "quot" { $quotation "( obj -- ... )" } } }
427{ $description "Applies the quotation to " { $snippet "x" } ", then to " { $snippet "y" } ", and finally to " { $snippet "z" } "." }
428{ $examples
429    "The following two lines are equivalent:"
430    { $code
431        "[ p ] tri@"
432        "[ [ p ] dip p ] dip p"
433    }
434    "The following two lines are also equivalent:"
435    { $code
436        "[ p ] tri@"
437        "[ p ] [ p ] [ p ] tri*"
438    }
439} ;
440
441HELP: 2tri@
442{ $values { "u" object } { "v" object } { "w" object } { "x" object } { "y" object } { "z" object } { "quot" { $quotation "( obj1 obj2 -- ... )" } } }
443{ $description "Applies the quotation to " { $snippet "u" } " and " { $snippet "v" } ", then to " { $snippet "w" } " and " { $snippet "x" } ", and then to " { $snippet "y" } " and " { $snippet "z" } "." }
444{ $examples
445    "The following two lines are equivalent:"
446    { $code
447        "[ p ] 2tri@"
448        "[ [ p ] 2dip p ] 2dip p"
449    }
450    "The following two lines are also equivalent:"
451    { $code
452        "[ p ] 2tri@"
453        "[ p ] [ p ] [ p ] 2tri*"
454    }
455} ;
456
457HELP: bi-curry
458{ $values { "x" object } { "p" { $quotation "( x -- ... )" } } { "q" { $quotation "( x -- ... )" } } { "p'" { $snippet "[ x p ]" } } { "q'" { $snippet "[ x q ]" } } }
459{ $description "Partially applies " { $snippet "p" } " and " { $snippet "q" } " to " { $snippet "x" } "." }
460{ $notes
461  "The following two lines are equivalent:"
462  { $code
463    "[ p ] [ q ] bi-curry [ call ] bi@"
464    "[ p ] [ q ] bi"
465  }
466  "Higher-arity variants of " { $link bi } " can be built from " { $link bi-curry } ":"
467  { $code
468    "[ p ] [ q ] bi-curry bi == [ p ] [ q ] 2bi"
469    "[ p ] [ q ] bi-curry bi-curry bi == [ p ] [ q ] 3bi"
470  }
471  "The combination " { $snippet "bi-curry bi*" } " cannot be expressed with the non-currying dataflow combinators alone; it is equivalent to a stack shuffle preceding " { $link 2bi* } ":"
472  { $code
473    "[ p ] [ q ] bi-curry bi*"
474    "[ swap ] keep [ p ] [ q ] 2bi*"
475  }
476  "To put it another way, " { $snippet "bi-curry bi*" } " handles the case where you have three values " { $snippet "a b c" } " on the stack, and you wish to apply " { $snippet "p" } " to " { $snippet "a c" } " and " { $snippet "q" } " to " { $snippet "b c" } "."
477} ;
478
479HELP: tri-curry
480{ $values
481  { "x" object }
482  { "p" { $quotation "( x -- ... )" } }
483  { "q" { $quotation "( x -- ... )" } }
484  { "r" { $quotation "( x -- ... )" } }
485  { "p'" { $snippet "[ x p ]" } }
486  { "q'" { $snippet "[ x q ]" } }
487  { "r'" { $snippet "[ x r ]" } }
488}
489{ $description "Partially applies " { $snippet "p" } ", " { $snippet "q" } " and " { $snippet "r" } " to " { $snippet "x" } "." }
490{ $notes
491  "The following two lines are equivalent:"
492  { $code
493    "[ p ] [ q ] [ r ] tri-curry [ call ] tri@"
494    "[ p ] [ q ] [ r ] tri"
495  }
496  "Higher-arity variants of " { $link tri } " can be built from " { $link tri-curry } ":"
497  { $code
498    "[ p ] [ q ] [ r ] tri-curry tri == [ p ] [ q ] [ r ] 2tri"
499    "[ p ] [ q ] [ r ] tri-curry tri-curry bi == [ p ] [ q ] [ r ] 3tri"
500  }
501  "The combination " { $snippet "tri-curry tri*" } " cannot be expressed with the non-currying dataflow combinators alone; it handles the case where you have four values " { $snippet "a b c d" } " on the stack, and you wish to apply " { $snippet "p" } " to " { $snippet "a d" } ", " { $snippet "q" } " to " { $snippet "b d" } " and " { $snippet "r" } " to " { $snippet "c d" } "." } ;
502
503HELP: bi-curry*
504{ $values { "x" object } { "y" object } { "p" { $quotation "( x -- ... )" } } { "q" { $quotation "( y -- ... )" } } { "p'" { $snippet "[ x p ]" } } { "q'" { $snippet "[ y q ]" } } }
505{ $description "Partially applies " { $snippet "p" } " to " { $snippet "x" } ", and " { $snippet "q" } " to " { $snippet "y" } "." }
506{ $notes
507  "The following two lines are equivalent:"
508  { $code
509    "[ p ] [ q ] bi-curry* [ call ] bi@"
510    "[ p ] [ q ] bi*"
511  }
512  "The combination " { $snippet "bi-curry* bi" } " is equivalent to a stack shuffle preceding " { $link 2bi* } ":"
513  { $code
514    "[ p ] [ q ] bi-curry* bi"
515    "[ over ] dip [ p ] [ q ] 2bi*"
516  }
517  "In other words, " { $snippet "bi-curry* bi" } " handles the case where you have the three values " { $snippet "a b c" } " on the stack, and you wish to apply " { $snippet "p" } " to " { $snippet "a b" } " and " { $snippet "q" } " to " { $snippet "a c" } "."
518  $nl
519  "The combination " { $snippet "bi-curry* bi*" } " is equivalent to a stack shuffle preceding " { $link 2bi* } ":"
520  { $code
521    "[ p ] [ q ] bi-curry* bi*"
522    "[ swap ] dip [ p ] [ q ] 2bi*"
523  }
524  "In other words, " { $snippet "bi-curry* bi*" } " handles the case where you have the four values " { $snippet "a b c d" } " on the stack, and you wish to apply " { $snippet "p" } " to " { $snippet "a c" } " and " { $snippet "q" } " to " { $snippet "b d" } "."
525
526} ;
527
528HELP: tri-curry*
529{ $values
530  { "x" object }
531  { "y" object }
532  { "z" object }
533  { "p" { $quotation "( x -- ... )" } }
534  { "q" { $quotation "( y -- ... )" } }
535  { "r" { $quotation "( z -- ... )" } }
536  { "p'" { $snippet "[ x p ]" } }
537  { "q'" { $snippet "[ y q ]" } }
538  { "r'" { $snippet "[ z r ]" } }
539}
540{ $description "Partially applies " { $snippet "p" } " to " { $snippet "x" } ", " { $snippet "q" } " to " { $snippet "y" } " and " { $snippet "r" } " to " { $snippet "z" } "." }
541{ $notes
542  "The following two lines are equivalent:"
543  { $code
544    "[ p ] [ q ] [ r ] tri-curry* [ call ] tri@"
545    "[ p ] [ q ] [ r ] tri*"
546  }
547  "The combination " { $snippet "tri-curry* tri" } " is equivalent to a stack shuffle preceding " { $link 2tri* } ":"
548  { $code
549    "[ p ] [ q ] [ r ] tri-curry* tri"
550    "[ [ over ] dip over ] dip [ p ] [ q ] [ r ] 2tri*"
551  }
552} ;
553
554HELP: bi-curry@
555{ $values { "x" object } { "y" object } { "q" { $quotation "( obj -- ... )" } } { "p'" { $snippet "[ x q ]" } } { "q'" { $snippet "[ y q ]" } } }
556{ $description "Partially applies " { $snippet "q" } " to " { $snippet "x" } " and " { $snippet "y" } "." }
557{ $notes
558  "The following two lines are equivalent:"
559  { $code
560    "[ q ] bi-curry@"
561    "[ q ] [ q ] bi-curry*"
562  }
563} ;
564
565HELP: tri-curry@
566{ $values
567  { "x" object }
568  { "y" object }
569  { "z" object }
570  { "q" { $quotation "( obj -- ... )" } }
571  { "p'" { $snippet "[ x q ]" } }
572  { "q'" { $snippet "[ y q ]" } }
573  { "r'" { $snippet "[ z q ]" } }
574}
575{ $description "Partially applies " { $snippet "q" } " to " { $snippet "x" } ", " { $snippet "y" } " and " { $snippet "z" } "." }
576{ $notes
577  "The following two lines are equivalent:"
578  { $code
579    "[ q ] tri-curry@"
580    "[ q ] [ q ] [ q ] tri-curry*"
581  }
582} ;
583
584HELP: if
585{ $values { "?" "a generalized boolean" } { "true" quotation } { "false" quotation } }
586{ $description "If " { $snippet "cond" } " is " { $link f } ", calls the " { $snippet "false" } " quotation. Otherwise calls the " { $snippet "true" } " quotation."
587$nl
588"The " { $snippet "cond" } " value is removed from the stack before either quotation is called." }
589{ $examples
590    { $example
591        "USING: io kernel math ;"
592        "10 3 < [ \"Math is broken\" print ] [ \"Math is good\" print ] if"
593        "Math is good"
594    }
595}
596{ $notes { $snippet "if" } " is executed as a primitive when preceded by two literal quotations. The below definition is not executed unless one of its arguments is a non-literal quotation, such as a quotation constructed with " { $link curry } " or " { $link compose } ", or for " { $link "fry" } " or quotations including " { $link "locals" } "." } ;
597
598HELP: when
599{ $values { "?" "a generalized boolean" } { "true" quotation } }
600{ $description "If " { $snippet "cond" } " is not " { $link f } ", calls the " { $snippet "true" } " quotation."
601$nl
602"The " { $snippet "cond" } " value is removed from the stack before the quotation is called." }
603{ $examples
604    { $example
605        "USING: kernel math prettyprint ;"
606        "-5 dup 0 < [ 3 + ] when ."
607        "-2"
608    }
609} ;
610
611HELP: unless
612{ $values { "?" "a generalized boolean" } { "false" quotation } }
613{ $description "If " { $snippet "cond" } " is " { $link f } ", calls the " { $snippet "false" } " quotation."
614$nl
615"The " { $snippet "cond" } " value is removed from the stack before the quotation is called." }
616{ $examples
617    { $example
618        "USING: kernel math prettyprint sequences ;"
619        "IN: scratchpad"
620        ""
621        "CONSTANT: american-cities {"
622        "    \"San Francisco\""
623        "    \"Los Angeles\""
624        "    \"New York\""
625        "}"
626        ""
627        ": add-tax ( price city -- price' )"
628        "    american-cities member? [ 1.1 * ] unless ;"
629        ""
630        "123 \"Ottawa\" add-tax ."
631        "135.3"
632    }
633} ;
634
635HELP: if*
636{ $values { "?" "a generalized boolean" } { "true" { $quotation "( ..a ? -- ..b )" } } { "false" { $quotation "( ..a -- ..b )" } } }
637{ $description "Alternative conditional form that preserves the " { $snippet "cond" } " value if it is true."
638$nl
639"If the condition is true, it is retained on the stack before the " { $snippet "true" } " quotation is called. Otherwise, the condition is removed from the stack and the " { $snippet "false" } " quotation is called."
640$nl
641"The following two lines are equivalent:"
642{ $code "X [ Y ] [ Z ] if*" "X dup [ Y ] [ drop Z ] if" } }
643{ $examples
644    "Notice how in this example, the same value is tested by the conditional, and then used in the true branch; the false branch does not need to drop the value because of how " { $link if* } " works:"
645    { $example
646        "USING: assocs io kernel math.parser ;"
647        "IN: scratchpad"
648        ""
649        ": curry-price ( meat -- price )
650    {
651        { \"Beef\" 10 }
652        { \"Chicken\" 12 }
653        { \"Lamb\" 13 }
654    } at ;
655
656: order-curry ( meat -- )
657    curry-price [
658        \"Your order will be \" write
659        number>string write
660        \" dollars.\" write
661    ] [ \"Invalid order.\" print ] if* ;"
662        ""
663        "\"Deer\" order-curry"
664        "Invalid order."
665    }
666} ;
667
668HELP: when*
669{ $values { "?" "a generalized boolean" } { "true" { $quotation "( ..a ? -- ..a )" } } }
670{ $description "Variant of " { $link if* } " with no false quotation."
671$nl
672"The following two lines are equivalent:"
673{ $code "X [ Y ] when*" "X dup [ Y ] [ drop ] if" } } ;
674
675HELP: unless*
676{ $values { "?" "a generalized boolean" } { "false" { $quotation "( ..a -- ..a x )" } } { "x" object } }
677{ $description "Variant of " { $link if* } " with no true quotation." }
678{ $notes
679"The following two lines are equivalent:"
680{ $code "X [ Y ] unless*" "X dup [ ] [ drop Y ] if" } } ;
681
682HELP: ?if
683{ $values { "default" object } { "cond" "a generalized boolean" } { "true" { $quotation "( ..a cond -- ..b )" } } { "false" { $quotation "( ..a default -- ..b )" } } }
684{ $description "If the condition is " { $link f } ", the " { $snippet "false" } " quotation is called with the " { $snippet "default" } " value on the stack. Otherwise, the " { $snippet "true" } " quotation is called with the condition on the stack." }
685{ $notes
686"The following two lines are equivalent:"
687{ $code "[ X ] [ Y ] ?if" "dup [ nip X ] [ drop Y ] if" }
688"The following two lines are equivalent:"
689{ $code "[ ] [ ] ?if" "swap or" } } ;
690
691HELP: die
692{ $description "Starts the front-end processor (FEP), which is a low-level debugger which can inspect memory addresses and the like. The FEP is also entered when a critical error occurs." }
693{ $notes
694    "The term FEP originates from the Lisp machines of old. According to the Jargon File,"
695    $nl
696    { $strong "fepped out" } " /fept owt/ " { $emphasis "adj." } " The Symbolics 3600 LISP Machine has a Front-End Processor called a `FEP' (compare sense 2 of box). When the main processor gets wedged, the FEP takes control of the keyboard and screen. Such a machine is said to have `fepped out' or `dropped into the fep'."
697    $nl
698    { $url "http://www.jargon.net/jargonfile/f/feppedout.html" }
699} ;
700
701HELP: (clone)
702{ $values { "obj" object } { "newobj" "a shallow copy" } }
703{ $description "Outputs a byte-by-byte copy of the given object. User code should call " { $link clone } " instead." } ;
704
705HELP: declare
706{ $values { "spec" "an array of class words" } }
707{ $description "Declares that the elements at the top of the stack are instances of the classes in " { $snippet "spec" } "." }
708{ $warning "The compiler blindly trusts declarations, and false declarations can lead to crashes, memory corruption and other undesirable behavior." }
709{ $examples
710    "The optimizer cannot do anything with the below code:"
711    { $code "2 + 10 *" }
712    "However, if we declare that the top of the stack is a " { $link float } ", then type checks and generic dispatch are eliminated, and the compiler can use unsafe intrinsics:"
713    { $code "{ float } declare 2 + 10 *" }
714} ;
715
716HELP: tag
717{ $values { "object" object } { "n" "a tag number" } }
718{ $description "Outputs an object's tag number, between zero and one less than " { $link num-types } ". This is implementation detail and user code should call " { $link class } " instead." } ;
719
720HELP: special-object
721{ $values { "n" "a non-negative integer" } { "obj" object } }
722{ $description "Reads an object from the Factor VM's special object table. User code never has to read the special object table directly; instead, use one of the callers of this word." } ;
723
724HELP: set-special-object
725{ $values { "obj" object } { "n" "a non-negative integer" } }
726{ $description "Writes an object to the Factor VM's special object table. User code never has to write to the special object table directly; instead, use one of the callers of this word." } ;
727
728HELP: object
729{ $class-description
730    "The class of all objects. If a generic word defines a method specializing on this class, the method is used as a fallback, if no other applicable method is found. For instance:"
731    { $code "GENERIC: enclose ( number -- array )" "M: number enclose 1array ;" "M: object enclose ;" }
732} ;
733
734HELP: null
735{ $class-description
736    "The canonical empty class with no instances."
737}
738{ $notes
739    "Unlike " { $snippet "null" } " in Java or " { $snippet "NULL" } " in C++, this is not a value signifying empty, or nothing. Use " { $link f } " for this purpose."
740} ;
741
742HELP: most
743{ $values { "x" object } { "y" object } { "quot" { $quotation "( x y -- ? )" } } { "z" "either " { $snippet "x" } " or " { $snippet "y" } } }
744{ $description "If the quotation yields a true value when applied to " { $snippet "x" } " and " { $snippet "y" } ", outputs " { $snippet "x" } ", otherwise outputs " { $snippet "y" } "." } ;
745
746HELP: curry
747{ $values { "obj" object } { "quot" callable } { "curry" curry } }
748{ $description "Partial application. Outputs a " { $link callable } " which first pushes " { $snippet "obj" } " and then calls " { $snippet "quot" } "." }
749{ $class-description "The class of objects created by " { $link curry } ". These objects print identically to quotations and implement the sequence protocol, however they only use two cells of storage; a reference to the object and a reference to the underlying quotation." }
750{ $notes "Even if " { $snippet "obj" } " is a word, it will be pushed as a literal."
751$nl
752"This operation is efficient and does not copy the quotation." }
753{ $examples
754    { $example "USING: kernel prettyprint ;" "5 [ . ] curry ." "[ 5 . ]" }
755    { $example "USING: kernel prettyprint see ;" "\\ = [ see ] curry ." "[ \\ = see ]" }
756    { $example "USING: kernel math prettyprint sequences ;" "{ 1 2 3 } 2 [ - ] curry map ." "{ -1 0 1 }" }
757} ;
758
759HELP: 2curry
760{ $values { "obj1" object } { "obj2" object } { "quot" callable } { "curry" curry } }
761{ $description "Outputs a " { $link callable } " which pushes " { $snippet "obj1" } " and " { $snippet "obj2" } " and then calls " { $snippet "quot" } "." }
762{ $notes "This operation is efficient and does not copy the quotation." }
763{ $examples
764    { $example "USING: kernel math prettyprint ;" "5 4 [ + ] 2curry ." "[ 5 4 + ]" }
765} ;
766
767HELP: 3curry
768{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quot" callable } { "curry" curry } }
769{ $description "Outputs a " { $link callable } " which pushes " { $snippet "obj1" } ", " { $snippet "obj2" } " and " { $snippet "obj3" } ", and then calls " { $snippet "quot" } "." }
770{ $notes "This operation is efficient and does not copy the quotation." } ;
771
772HELP: with
773{ $values { "param" object } { "obj" object } { "quot" { $quotation "( param elt -- ... )" } } { "curry" curry } }
774{ $description "Partial application on the left. The following two lines are equivalent:"
775    { $code "swap [ swap A ] curry B" }
776    { $code "[ A ] with B" }
777
778}
779{ $notes "This operation is efficient and does not copy the quotation." }
780{ $examples
781    { $example "USING: kernel math prettyprint sequences ;" "1 { 1 2 3 } [ / ] with map ." "{ 1 1/2 1/3 }" }
782    { $example "USING: kernel math prettyprint sequences ;" "1000 100 5 iota [ sq + + ] with with map ." "{ 1100 1101 1104 1109 1116 }" }
783} ;
784
785HELP: compose
786{ $values { "quot1" callable } { "quot2" callable } { "compose" compose } }
787{ $description "Quotation composition. Outputs a " { $link callable } " which calls " { $snippet "quot1" } " followed by " { $snippet "quot2" } "." }
788{ $notes
789    "The following two lines are equivalent:"
790    { $code
791        "compose call"
792        "append call"
793    }
794    "However, " { $link compose } " runs in constant time, and the optimizing compiler is able to compile code which calls composed quotations."
795} ;
796
797
798HELP: prepose
799{ $values { "quot1" callable } { "quot2" callable } { "compose" compose } }
800{ $description "Quotation composition. Outputs a " { $link callable } " which calls " { $snippet "quot2" } " followed by " { $snippet "quot1" } "." }
801{ $notes "See " { $link compose } " for details." } ;
802
803{ compose prepose } related-words
804
805HELP: dip
806{ $values { "x" object } { "quot" quotation } }
807{ $description "Removes " { $snippet "x" } " from the datastack, calls " { $snippet "quot" } ", and restores " { $snippet "x" } " to the top of the datastack when " { $snippet "quot" } " is finished." }
808{ $examples
809    { $example "USING: arrays kernel math prettyprint ;" "10 20 30 [ / ] dip 2array ." "{ 1/2 30 }" }
810}
811{ $notes { $snippet "dip" } " is executed as a primitive when preceded by a literal quotation. The below definition is not executed unless its argument is a non-literal quotation, such as a quotation constructed with " { $link curry } " or " { $link compose } ", or for " { $link "fry" } " or quotations including " { $link "locals" } "." } ;
812
813HELP: 2dip
814{ $values { "x" object } { "y" object } { "quot" quotation } }
815{ $description "Removes " { $snippet "x" } " and " { $snippet "y" } " from the datastack, calls " { $snippet "quot" } ", and restores the removed objects to the top of the datastack when " { $snippet "quot" } " is finished." }
816{ $notes "The following are equivalent:"
817    { $code "[ [ foo bar ] dip ] dip" }
818    { $code "[ foo bar ] 2dip" }
819} ;
820
821HELP: 3dip
822{ $values { "x" object } { "y" object } { "z" object } { "quot" quotation } }
823{ $description "Removes " { $snippet "x" } ", " { $snippet "y" } ", and " { $snippet "z" } " from the datastack, calls " { $snippet "quot" } ", and restores the removed objects to the top of the datastack when " { $snippet "quot" } " is finished." }
824{ $notes "The following are equivalent:"
825    { $code "[ [ [ foo bar ] dip ] dip ] dip" }
826    { $code "[ foo bar ] 3dip" }
827} ;
828
829HELP: 4dip
830{ $values { "w" object } { "x" object } { "y" object } { "z" object } { "quot" quotation } }
831{ $description "Removes " { $snippet "w" } ", " { $snippet "x" } ", " { $snippet "y" } ", and " { $snippet "z" } " from the datastack, calls " { $snippet "quot" } ", and restores the removed objects to the top of the datastack when " { $snippet "quot" } " is finished." }
832{ $notes "The following are equivalent:"
833    { $code "[ [ [ [ foo bar ] dip ] dip ] dip ] dip" }
834    { $code "[ foo bar ] 4dip" }
835} ;
836
837HELP: while
838{ $values { "pred" { $quotation "( ..a -- ..b ? )" } } { "body" { $quotation "( ..b -- ..a )" } } }
839{ $description "Calls " { $snippet "body" } " until " { $snippet "pred" } " returns " { $link f } "." } ;
840
841HELP: until
842{ $values { "pred" { $quotation "( ..a -- ..b ? )" } } { "body" { $quotation "( ..b -- ..a )" } } }
843{ $description "Calls " { $snippet "body" } " until " { $snippet "pred" } " returns " { $link t } "." } ;
844
845HELP: do
846{ $values { "pred" { $quotation "( ..a -- ..b ? )" } } { "body" { $quotation "( ..b -- ..a )" } } }
847{ $description "Executes one iteration of a " { $link while } " or " { $link until } " loop." } ;
848
849HELP: loop
850{ $values
851     { "pred" quotation } }
852     { $description "Calls the quotation repeatedly until it outputs " { $link f } "." }
853{ $examples "Loop until we hit a zero:"
854    { $unchecked-example "USING: kernel random math io ; "
855    " [ \"hi\" write bl 10 random zero? not ] loop"
856    "hi hi hi" }
857    "A fun loop:"
858    { $example "USING: kernel prettyprint math ; "
859    "3 [ dup . 7 + 11 mod dup 3 = not ] loop drop"
860    "3\n10\n6\n2\n9\n5\n1\n8\n4\n0\n7" }
861} ;
862
863ARTICLE: "looping-combinators" "Looping combinators"
864"In most cases, loops should be written using high-level combinators (such as " { $link "sequences-combinators" } ") or tail recursion. However, sometimes, the best way to express intent is with a loop."
865{ $subsections
866    while
867    until
868}
869"To execute one iteration of a loop, use the following word:"
870{ $subsections do }
871"This word is intended as a modifier. The normal " { $link while } " loop never executes the body if the predicate returns false on the first iteration. To ensure the body executes at least once, use " { $link do } ":"
872{ $code
873    "[ P ] [ Q ] do while"
874}
875"A simpler looping combinator which executes a single quotation until it returns " { $link f } ":"
876{ $subsections loop } ;
877
878HELP: assert
879{ $values { "got" "the obtained value" } { "expect" "the expected value" } }
880{ $description "Throws an " { $link assert } " error." }
881{ $error-description "Thrown when a unit test or other assertion fails." } ;
882
883HELP: assert=
884{ $values { "a" object } { "b" object } }
885{ $description "Throws an " { $link assert } " error if " { $snippet "a" } " does not equal " { $snippet "b" } "." } ;
886
887HELP: become
888{ $values { "old" array } { "new" array } }
889{ $description "Replaces all references to objects in " { $snippet "old" } " with the corresponding object in " { $snippet "new" } ". This word is used to implement tuple reshaping. See " { $link "tuple-redefinition" } "." } ;
890
891ARTICLE: "shuffle-words-complex" "Complex shuffle words"
892"These shuffle words tend to make code difficult to read and to reason about. Code that uses them should almost always be rewritten using " { $link "locals" } " or " { $link "dataflow-combinators" } "."
893$nl
894"Duplicating stack elements deep in the stack:"
895{ $subsections
896    dupd
897}
898"Permuting stack elements deep in the stack:"
899{ $subsections
900    swapd
901    rot
902    -rot
903} ;
904
905ARTICLE: "shuffle-words" "Shuffle words"
906"Shuffle words rearrange items at the top of the data stack as indicated by their stack effects. They provide simple data flow control between words. More complex data flow control is available with the " { $link "dataflow-combinators" } " and with " { $link "locals" } "."
907$nl
908"Removing stack elements:"
909{ $subsections
910    drop
911    2drop
912    3drop
913    nip
914    2nip
915}
916"Duplicating stack elements:"
917{ $subsections
918    dup
919    2dup
920    3dup
921    over
922    2over
923    pick
924}
925"Permuting stack elements:"
926{ $subsections
927    swap
928}
929"There are additional, more complex stack shuffling words whose use is not recommended."
930{ $subsections
931    "shuffle-words-complex"
932} ;
933
934ARTICLE: "equality" "Equality"
935"There are two distinct notions of “sameness” when it comes to objects."
936$nl
937"You can test if two references point to the same object (" { $emphasis "identity comparison" } "). This is rarely used; it is mostly useful with large, mutable objects where the object identity matters but the value is transient:"
938{ $subsections eq? }
939"You can test if two objects are equal in a domain-specific sense, usually by being instances of the same class, and having equal slot values (" { $emphasis "value comparison" } "):"
940{ $subsections = }
941"A third form of equality is provided by " { $link number= } ". It compares numeric value while disregarding types."
942$nl
943"Custom value comparison methods for use with " { $link = } " can be defined on a generic word:"
944{ $subsections equal? }
945"Utility class:"
946{ $subsections identity-tuple }
947"An object can be cloned; the clone has distinct identity but equal value:"
948{ $subsections clone } ;
949
950ARTICLE: "assertions" "Assertions"
951"Some words to make assertions easier to enforce:"
952{ $subsections
953    assert
954    assert=
955} ;
956