core/kernel/kernel-docs.factor

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