core/combinators/combinators-docs.factor

   1 USING: arrays help.markup help.syntax strings sbufs vectors
   2 kernel quotations generic generic.standard classes
   3 math assocs sequences sequences.private combinators.private
   4 effects words ;
   5 IN: combinators
   6
   7 ARTICLE: "cleave-shuffle-equivalence" "Expressing shuffle words with cleave combinators"
   8 "Cleave combinators are defined in terms of shuffle words, and mappings from certain shuffle idioms to cleave combinators are discussed in the documentation for " { $link bi } ", " { $link 2bi } ", " { $link 3bi } ", " { $link tri } ", " { $link 2tri } " and " { $link 3tri } "."
   9 $nl
  10 "Certain shuffle words can also be expressed in terms of the cleave combinators. Internalizing such identities can help with understanding and writing code using cleave combinators:"
  11 { $code
  12     ": keep  [ ] bi ;"
  13     ": 2keep [ ] 2bi ;"
  14     ": 3keep [ ] 3bi ;"
  15     ""
  16     ": dup   [ ] [ ] bi ;"
  17     ": 2dup  [ ] [ ] 2bi ;"
  18     ": 3dup  [ ] [ ] 3bi ;"
  19     ""
  20     ": tuck  [ nip ] [ ] 2bi ;"
  21     ": swap  [ nip ] [ drop ] 2bi ;"
  22     ""
  23     ": over  [ ] [ drop ] 2bi ;"
  24     ": pick  [ ] [ 2drop ] 3bi ;"
  25     ": 2over [ ] [ drop ] 3bi ;"
  26 } ;
  27
  28 ARTICLE: "cleave-combinators" "Cleave combinators"
  29 "The cleave combinators apply multiple quotations to a single value."
  30 $nl
  31 "Two quotations:"
  32 { $subsection bi }
  33 { $subsection 2bi }
  34 { $subsection 3bi }
  35 "Three quotations:"
  36 { $subsection tri }
  37 { $subsection 2tri }
  38 { $subsection 3tri }
  39 "An array of quotations:"
  40 { $subsection cleave }
  41 { $subsection 2cleave }
  42 { $subsection 3cleave }
  43 "Technically, the cleave combinators are redundant because they can be simulated using shuffle words and other combinators, and in addition, they do not reduce token counts by much, if at all. However, they can make code more readable by expressing intention and exploiting any inherent symmetry. For example, a piece of code which performs three operations on the top of the stack can be written in one of two ways:"
  44 { $code
  45     "! First alternative; uses keep"
  46     "[ 1 + ] keep"
  47     "[ 1 - ] keep"
  48     "2 *"
  49     "! Second alternative: uses tri"
  50     "[ 1 + ]"
  51     "[ 1 - ]"
  52     "[ 2 * ] tri"
  53 }
  54 "The latter is more aesthetically pleasing than the former."
  55 { $subsection "cleave-shuffle-equivalence" } ;
  56
  57 ARTICLE: "spread-shuffle-equivalence" "Expressing shuffle words with spread combinators"
  58 "Spread combinators are defined in terms of shuffle words, and mappings from certain shuffle idioms to spread combinators are discussed in the documentation for " { $link bi* } ", " { $link 2bi* } ", " { $link tri* } ", and " { $link 2tri* } "."
  59 $nl
  60 "Certain shuffle words can also be expressed in terms of the spread combinators. Internalizing such identities can help with understanding and writing code using spread combinators:"
  61 { $code
  62     ": dip   [ ] bi* ;"
  63     ": 2dip  [ ] [ ] tri* ;"
  64     ""
  65     ": nip   [ drop ] [ ] bi* ;"
  66     ": 2nip  [ drop ] [ drop ] [ ] tri* ;"
  67     ""
  68     ": rot"
  69     "    [ [ drop ] [      ] [ drop ] tri* ]"
  70     "    [ [ drop ] [ drop ] [      ] tri* ]"
  71     "    [ [      ] [ drop ] [ drop ] tri* ]"
  72     "    3tri ;"
  73     ""
  74     ": -rot"
  75     "    [ [ drop ] [ drop ] [      ] tri* ]"
  76     "    [ [      ] [ drop ] [ drop ] tri* ]"
  77     "    [ [ drop ] [      ] [ drop ] tri* ]"
  78     "    3tri ;"
  79     ""
  80     ": spin"
  81     "    [ [ drop ] [ drop ] [      ] tri* ]"
  82     "    [ [ drop ] [      ] [ drop ] tri* ]"
  83     "    [ [      ] [ drop ] [ drop ] tri* ]"
  84     "    3tri ;"
  85 } ;
  86
  87 ARTICLE: "spread-combinators" "Spread combinators"
  88 "The spread combinators apply multiple quotations to multiple values. In this case, " { $snippet "*" } " suffix signify spreading."
  89 $nl
  90 "Two quotations:"
  91 { $subsection bi* }
  92 { $subsection 2bi* }
  93 "Three quotations:"
  94 { $subsection tri* }
  95 { $subsection 2tri* }
  96 "An array of quotations:"
  97 { $subsection spread }
  98 "Technically, the spread combinators are redundant because they can be simulated using shuffle words and other combinators, and in addition, they do not reduce token counts by much, if at all. However, they can make code more readable by expressing intention and exploiting any inherent symmetry. For example, a piece of code which performs three operations on three related values can be written in one of two ways:"
  99 { $code
 100     "! First alternative; uses dip"
 101     "[ [ 1 + ] dip 1 - ] dip 2 *"
 102     "! Second alternative: uses tri*"
 103     "[ 1 + ] [ 1 - ] [ 2 * ] tri*"
 104 }
 105 "A generalization of the above combinators to any number of quotations can be found in " { $link "combinators" } "."
 106 { $subsection "spread-shuffle-equivalence" } ;
 107
 108 ARTICLE: "apply-combinators" "Apply combinators"
 109 "The apply combinators apply a single quotation to multiple values. The " { $snippet "@" } " suffix signifies application."
 110 $nl
 111 "Two quotations:"
 112 { $subsection bi@ }
 113 { $subsection 2bi@ }
 114 "Three quotations:"
 115 { $subsection tri@ }
 116 { $subsection 2tri@ }
 117 "A pair of utility words built from " { $link bi@ } ":"
 118 { $subsection both? }
 119 { $subsection either? } ;
 120
 121 ARTICLE: "retainstack-combinators" "Retain stack combinators"
 122 "Sometimes an additional storage area is needed to hold objects. The " { $emphasis "retain stack" } " is an auxilliary stack for this purpose. Objects can be moved between the data and retain stacks using a set of combinators."
 123 $nl
 124 "The dip combinators invoke the quotation at the top of the stack, hiding the values underneath:"
 125 { $subsection dip }
 126 { $subsection 2dip }
 127 { $subsection 3dip }
 128 { $subsection 4dip }
 129 "The keep combinators invoke a quotation which takes a number of values off the stack, and then they restore those values:"
 130 { $subsection keep }
 131 { $subsection 2keep }
 132 { $subsection 3keep } ;
 133
 134 ARTICLE: "curried-dataflow" "Curried dataflow combinators"
 135 "Curried cleave combinators:"
 136 { $subsection bi-curry }
 137 { $subsection tri-curry }
 138 "Curried spread combinators:"
 139 { $subsection bi-curry* }
 140 { $subsection tri-curry* }
 141 "Curried apply combinators:"
 142 { $subsection bi-curry@ }
 143 { $subsection tri-curry@ }
 144 { $see-also "dataflow-combinators" } ;
 145
 146 ARTICLE: "compositional-examples" "Examples of compositional combinator usage"
 147 "Consider printing the same message ten times:"
 148 { $code ": print-10 ( -- ) 10 [ \"Hello, world.\" print ] times ;" }
 149 "if we wanted to abstract out the message into a parameter, we could keep it on the stack between iterations:"
 150 { $code ": print-10 ( message -- ) 10 [ dup print ] times drop ;" }
 151 "However, keeping loop-invariant values on the stack doesn't always work out nicely. For example, a word to subtract a value from each element of a sequence:"
 152 { $code ": subtract-n ( seq n -- seq' ) swap [ over - ] map nip ;" }
 153 "Three shuffle words are required to pass the value around. Instead, the loop-invariant value can be partially applied to a quotation using " { $link curry } ", yielding a new quotation that is passed to " { $link map } ":"
 154 { $example
 155   ": subtract-n ( seq n -- seq' ) [ - ] curry map ;"
 156   "{ 10 20 30 } 5 subtract-n ."
 157   "{ 5 15 25 }"
 158 }
 159 "Now consider the word that is dual to the one above; instead of subtracting " { $snippet "n" } " from each stack element, it subtracts each element from " { $snippet "n" } "."
 160 $nl
 161 "One way to write this is with a pair of " { $link swap } "s:"
 162 { $code ": n-subtract ( n seq -- seq' ) swap [ swap - ] curry map ;" }
 163 "Since this pattern comes up often, " { $link with } " encapsulates it:"
 164 { $example
 165   ": n-subtract ( n seq -- seq' ) [ - ] with map ;"
 166   "30 { 10 20 30 } n-subtract ."
 167   "{ 20 10 0 }"
 168 }
 169 { $see-also "fry.examples" } ;
 170
 171 ARTICLE: "compositional-combinators" "Compositional combinators"
 172 "Certain combinators transform quotations to produce a new quotation."
 173 { $subsection "compositional-examples" }
 174 "Fundamental operations:"
 175 { $subsection curry }
 176 { $subsection compose }
 177 "Derived operations:"
 178 { $subsection 2curry }
 179 { $subsection 3curry }
 180 { $subsection with }
 181 { $subsection prepose }
 182 "These operations run in constant time, and in many cases are optimized out altogether by the " { $link "compiler" } ". " { $link "fry" } " are an abstraction built on top of these operations, and code that uses this abstraction is often clearer than direct calls to the below words."
 183 $nl
 184 "Curried dataflow combinators can be used to build more complex dataflow by combining cleave, spread and apply patterns in various ways."
 185 { $subsection "curried-dataflow" }
 186 "Quotations also implement the sequence protocol, and can be manipulated with sequence words; see " { $link "quotations" } ". However, such runtime quotation manipulation will not be optimized by the optimizing compiler." ;
 187
 188 ARTICLE: "booleans" "Booleans"
 189 "In Factor, any object that is not " { $link f } " has a true value, and " { $link f } " has a false value. The " { $link t } " object is the canonical true value."
 190 { $subsection f }
 191 { $subsection t }
 192 "A union class of the above:"
 193 { $subsection boolean }
 194 "There are some logical operations on booleans:"
 195 { $subsection >boolean }
 196 { $subsection not }
 197 { $subsection and }
 198 { $subsection or }
 199 { $subsection xor }
 200 "Boolean values are most frequently used for " { $link "conditionals" } "."
 201 { $heading "The f object and f class" }
 202 "The " { $link f } " object is the unique instance of the " { $link f } " class; the two are distinct objects. The latter is also a parsing word which adds the " { $link f } " object to the parse tree at parse time. To refer to the class itself you must use " { $link POSTPONE: POSTPONE: } " or " { $link POSTPONE: \ } " to prevent the parsing word from executing."
 203 $nl
 204 "Here is the " { $link f } " object:"
 205 { $example "f ." "f" }
 206 "Here is the " { $link f } " class:"
 207 { $example "\\ f ." "POSTPONE: f" }
 208 "They are not equal:"
 209 { $example "f \\ f = ." "f" }
 210 "Here is an array containing the " { $link f } " object:"
 211 { $example "{ f } ." "{ f }" }
 212 "Here is an array containing the " { $link f } " class:"
 213 { $example "{ POSTPONE: f } ." "{ POSTPONE: f }" }
 214 "The " { $link f } " object is an instance of the " { $link f } " class:"
 215 { $example "USE: classes" "f class ." "POSTPONE: f" }
 216 "The " { $link f } " class is an instance of " { $link word } ":"
 217 { $example "USE: classes" "\\ f class ." "word" }
 218 "On the other hand, " { $link t } " is just a word, and there is no class which it is a unique instance of."
 219 { $example "t \\ t eq? ." "t" }
 220 "Many words which search collections confuse the case of no element being present with an element being found equal to " { $link f } ". If this distinction is imporant, there is usually an alternative word which can be used; for example, compare " { $link at } " with " { $link at* } "." ;
 221
 222 ARTICLE: "conditionals-boolean-equivalence" "Expressing conditionals with boolean logic"
 223 "Certain simple conditional forms can be expressed in a simpler manner using boolean logic."
 224 $nl
 225 "The following two lines are equivalent:"
 226 { $code "[ drop f ] unless" "swap and" }
 227 "The following two lines are equivalent:"
 228 { $code "[ ] [ ] ?if" "swap or" }
 229 "The following two lines are equivalent, where " { $snippet "L" } " is a literal:"
 230 { $code "[ L ] unless*" "L or" } ;
 231
 232 ARTICLE: "conditionals" "Conditional combinators"
 233 "The basic conditionals:"
 234 { $subsection if }
 235 { $subsection when }
 236 { $subsection unless }
 237 "Forms abstracting a common stack shuffle pattern:"
 238 { $subsection if* }
 239 { $subsection when* }
 240 { $subsection unless* }
 241 "Another form abstracting a common stack shuffle pattern:"
 242 { $subsection ?if }
 243 "Sometimes instead of branching, you just need to pick one of two values:"
 244 { $subsection ? }
 245 "Two combinators which abstract out nested chains of " { $link if } ":"
 246 { $subsection cond }
 247 { $subsection case }
 248 { $subsection "conditionals-boolean-equivalence" }
 249 { $see-also "booleans" "bitwise-arithmetic" both? either? } ;
 250
 251 ARTICLE: "dataflow-combinators" "Data flow combinators"
 252 "Data flow combinators pass values between quotations:"
 253 { $subsection "retainstack-combinators" }
 254 { $subsection "cleave-combinators" }
 255 { $subsection "spread-combinators" }
 256 { $subsection "apply-combinators" }
 257 { $see-also "curried-dataflow" } ;
 258
 259 ARTICLE: "combinators-quot" "Quotation construction utilities"
 260 "Some words for creating quotations which can be useful for implementing method combinations and compiler transforms:"
 261 { $subsection cond>quot }
 262 { $subsection case>quot }
 263 { $subsection alist>quot } ;
 264
 265 ARTICLE: "call-unsafe" "Unsafe combinators"
 266 "Unsafe calls declare an effect statically without any runtime checking:"
 267 { $subsection call-effect-unsafe }
 268 { $subsection execute-effect-unsafe } ;
 269
 270 ARTICLE: "call" "Fundamental combinators"
 271 "The most basic combinators are those that take either a quotation or word, and invoke it immediately."
 272 $nl
 273 "There are two sets of combinators; they differ in whether or not the stack effect of the expected code is declared."
 274 $nl
 275 "The simplest combinators do not take an effect declaration. The compiler checks the stack effect at compile time, rejecting the program if this cannot be done:"
 276 { $subsection call }
 277 { $subsection execute }
 278 "The second set of combinators takes an effect declaration. Note that the opening parenthesis is actually part of the word name; these are parsing words, and they read a stack effect until the corresponding closing parenthesis. The stack effect of the quotation or word is then checked at runtime:"
 279 { $subsection POSTPONE: call( }
 280 { $subsection POSTPONE: execute( }
 281 "The above are syntax sugar. The underlying words are a bit more verbose but allow non-constant effects to be passed in:"
 282 { $subsection call-effect }
 283 { $subsection execute-effect }
 284 "The combinator variants that do not take an effect declaration can only be used if the compiler is able to infer the stack effect by other means. See " { $link "inference-combinators" } "."
 285 { $subsection "call-unsafe" }
 286 { $see-also "effects" "inference" } ;
 287
 288 ARTICLE: "combinators" "Combinators"
 289 "A central concept in Factor is that of a " { $emphasis "combinator" } ", which is a word taking code as input."
 290 { $subsection "call" }
 291 { $subsection "dataflow-combinators" }
 292 { $subsection "conditionals" }
 293 { $subsection "looping-combinators" }
 294 { $subsection "compositional-combinators" }
 295 { $subsection "combinators.short-circuit" }
 296 { $subsection "combinators.smart" }
 297 "More combinators are defined for working on data structures, such as " { $link "sequences-combinators" } " and " { $link "assocs-combinators" } "."
 298 { $subsection "combinators-quot" }
 299 { $subsection "generalizations" }
 300 { $see-also "quotations" } ;
 301
 302 ABOUT: "combinators"
 303
 304 HELP: call-effect
 305 { $values { "quot" quotation } { "effect" effect } }
 306 { $description "Given a quotation and a stack effect, calls the quotation, asserting at runtime that it has the given stack effect. This is a macro which expands given a literal effect parameter, and an arbitrary quotation which is not required at compile time." }
 307 { $examples
 308   "The following two lines are equivalent:"
 309   { $code
 310     "call( a b -- c )"
 311     "(( a b -- c )) call-effect"
 312   }
 313 } ;
 314
 315 HELP: execute-effect
 316 { $values { "word" word } { "effect" effect } }
 317 { $description "Given a word and a stack effect, executes the word, asserting at runtime that it has the given stack effect. This is a macro which expands given a literal effect parameter, and an arbitrary word which is not required at compile time." }
 318 { $examples
 319   "The following two lines are equivalent:"
 320   { $code
 321     "execute( a b -- c )"
 322     "(( a b -- c )) execute-effect"
 323   }
 324 } ;
 325
 326 HELP: execute-effect-unsafe
 327 { $values { "word" word } { "effect" effect } }
 328 { $description "Given a word and a stack effect, executes the word, blindly declaring at runtime that it has the given stack effect. This is a macro which expands given a literal effect parameter, and an arbitrary word which is not required at compile time." }
 329 { $warning "If the word being executed has an incorrect stack effect, undefined behavior will result. User code should use " { $link POSTPONE: execute( } " instead." } ;
 330
 331 { call-effect call-effect-unsafe execute-effect execute-effect-unsafe } related-words
 332
 333 HELP: cleave
 334 { $values { "x" object } { "seq" "a sequence of quotations with stack effect " { $snippet "( x -- ... )" } } }
 335 { $description "Applies each quotation to the object in turn." }
 336 { $examples
 337     "The " { $link bi } " combinator takes one value and two quotations; the " { $link tri } " combinator takes one value and three quotations. The " { $link cleave } " combinator takes one value and any number of quotations, and is essentially equivalent to a chain of " { $link keep } " forms:"
 338     { $code
 339         "! Equivalent"
 340         "{ [ p ] [ q ] [ r ] [ s ] } cleave"
 341         "[ p ] keep [ q ] keep [ r ] keep s"
 342     }
 343 } ;
 344
 345 HELP: 2cleave
 346 { $values { "x" object } { "y" object }
 347           { "seq" "a sequence of quotations with stack effect " { $snippet "( x y -- ... )" } } }
 348 { $description "Applies each quotation to the two objects in turn." } ;
 349
 350 HELP: 3cleave
 351 { $values { "x" object } { "y" object } { "z" object }
 352           { "seq" "a sequence of quotations with stack effect " { $snippet "( x y z -- ... )" } } }
 353 { $description "Applies each quotation to the three objects in turn." } ;
 354
 355 { bi tri cleave } related-words
 356
 357 HELP: spread
 358 { $values { "objs..." "objects" } { "seq" "a sequence of quotations with stack effect " { $snippet "( x -- ... )" } } }
 359 { $description "Applies each quotation to the object in turn." }
 360 { $examples
 361     "The " { $link bi* } " combinator takes two values and two quotations; the " { $link tri* } " combinator takes three values and three quotations. The " { $link spread } " combinator takes " { $snippet "n" } " values and " { $snippet "n" } " quotations, where " { $snippet "n" } " is the length of the input sequence, and is essentially equivalent to series of retain stack manipulations:"
 362     { $code
 363         "! Equivalent"
 364         "{ [ p ] [ q ] [ r ] [ s ] } spread"
 365         "[ [ [ p ] dip q ] dip r ] dip s"
 366     }
 367 } ;
 368
 369 { bi* tri* spread } related-words
 370
 371 HELP: to-fixed-point
 372 { $values { "object" object } { "quot" { $quotation "( object(n) -- object(n+1) )" } } { "object(n)" object } }
 373 { $description "Applies the quotation repeatedly with " { $snippet "object" } " as the initial input until the output of the quotation equals the input." }
 374 { $examples
 375     { $example
 376         "USING: combinators kernel math prettyprint sequences ;"
 377         "IN: scratchpad"
 378         ": flatten ( sequence -- sequence' )"
 379         "    \"flatten\" over index"
 380         "    [ [ 1 + swap nth ] [ nip dup 2 + ] [ drop ] 2tri replace-slice ] when* ;"
 381         ""
 382         "{ \"flatten\" { 1 { 2 3 } \"flatten\" { 4 5 } { 6 } } } [ flatten ] to-fixed-point ."
 383         "{ 1 { 2 3 } 4 5 { 6 } }"
 384     }
 385 } ;
 386
 387 HELP: alist>quot
 388 { $values { "default" "a quotation" } { "assoc" "a sequence of quotation pairs" } { "quot" "a new quotation" } }
 389 { $description "Constructs a quotation which calls the first quotation in each pair of " { $snippet "assoc" } " until one of them outputs a true value, and then calls the second quotation in the corresponding pair. Quotations are called in reverse order, and if no quotation outputs a true value then " { $snippet "default" } " is called." }
 390 { $notes "This word is used to implement compile-time behavior for " { $link cond } ", and it is also used by the generic word system. Note that unlike " { $link cond } ", the constructed quotation performs the tests starting from the end and not the beginning." } ;
 391
 392 HELP: cond
 393 { $values { "assoc" "a sequence of quotation pairs and an optional quotation" } }
 394 { $description
 395     "Calls the second quotation in the first pair whose first quotation yields a true value. A single quotation will always yield a true value."
 396     $nl
 397     "The following two phrases are equivalent:"
 398     { $code "{ { [ X ] [ Y ] } { [ Z ] [ T ] } } cond" }
 399     { $code "X [ Y ] [ Z [ T ] [ no-cond ] if ] if" }
 400 }
 401 { $errors "Throws a " { $link no-cond } " error if none of the test quotations yield a true value." }
 402 { $examples
 403     { $code
 404         "{"
 405         "    { [ dup 0 > ] [ \"positive\" ] }"
 406         "    { [ dup 0 < ] [ \"negative\" ] }"
 407         "    [ \"zero\" ]"
 408         "} cond"
 409     }
 410 } ;
 411
 412 HELP: no-cond
 413 { $description "Throws a " { $link no-cond } " error." }
 414 { $error-description "Thrown by " { $link cond } " if none of the test quotations yield a true value. Some uses of " { $link cond } " include a default case where the test quotation is " { $snippet "[ t ]" } "; such a " { $link cond } " form will never throw this error." } ;
 415
 416 HELP: case
 417 { $values { "obj" object } { "assoc" "a sequence of object/word,quotation pairs, with an optional quotation at the end" } }
 418 { $description
 419     "Compares " { $snippet "obj" } " against the first element of every pair, first evaluating the first element if it is a word. If some pair matches, removes " { $snippet "obj" } " from the stack and calls the second element of that pair, which must be a quotation."
 420     $nl
 421     "If there is no case matching " { $snippet "obj" } ", the default case is taken. If the last element of " { $snippet "cases" } " is a quotation, the quotation is called with " { $snippet "obj" } " on the stack. Otherwise, a " { $link no-cond } " error is rasied."
 422     $nl
 423     "The following two phrases are equivalent:"
 424     { $code "{ { X [ Y ] } { Z [ T ] } } case" }
 425     { $code "dup X = [ drop Y ] [ dup Z = [ drop T ] [ no-case ] if ] if" }
 426 }
 427 { $examples
 428     { $code
 429         "SYMBOL: yes  SYMBOL: no  SYMBOL: maybe"
 430         "maybe {"
 431         "    { yes [ ] } ! Do nothing"
 432         "    { no [ \"No way!\" throw ] }"
 433         "    { maybe [ \"Make up your mind!\" print ] }"
 434         "    [ \"Invalid input; try again.\" print ]"
 435         "} case"
 436     }
 437 } ;
 438
 439 HELP: no-case
 440 { $description "Throws a " { $link no-case } " error." }
 441 { $error-description "Thrown by " { $link case } " if the object at the top of the stack does not match any case, and no default case is given." } ;
 442
 443 HELP: recursive-hashcode
 444 { $values { "n" integer } { "obj" object } { "quot" { $quotation "( n obj -- code )" } } { "code" integer } }
 445 { $description "A combinator used to implement methods for the " { $link hashcode* } " generic word. If " { $snippet "n" } " is less than or equal to zero, outputs 0, otherwise calls the quotation." } ;
 446
 447 HELP: cond>quot
 448 { $values { "assoc" "a sequence of pairs of quotations" } { "quot" quotation } }
 449 { $description  "Creates a quotation that when called, has the same effect as applying " { $link cond } " to " { $snippet "assoc" } "."
 450 $nl
 451 "The generated quotation is more efficient than the naive implementation of " { $link cond } ", though, since it expands into a series of conditionals, and no iteration through " { $snippet "assoc" } " has to be performed." }
 452 { $notes "This word is used behind the scenes to compile " { $link cond } " forms efficiently; it can also be called directly,  which is useful for meta-programming." } ;
 453
 454 HELP: case>quot
 455 { $values { "assoc" "a sequence of pairs of quotations" } { "default" quotation } { "quot" quotation } }
 456 { $description "Creates a quotation that when called, has the same effect as applying " { $link case } " to " { $snippet "assoc" } "."
 457 $nl
 458 "This word uses three strategies:"
 459 { $list
 460     "If the assoc only has a few keys, a linear search is generated."
 461     { "If the assoc has a large number of keys which form a contiguous range of integers, a direct dispatch is generated using the " { $link dispatch } " word together with a bounds check." }
 462     "Otherwise, an open-coded hashtable dispatch is generated."
 463 } } ;
 464
 465 HELP: distribute-buckets
 466 { $values { "alist" "an alist" } { "initial" object } { "quot" { $quotation "( obj -- assoc )" } } { "buckets" "a new array" } }
 467 { $description "Sorts the entries of " { $snippet "assoc" } " into buckets, using the quotation to yield a set of keys for each entry. The hashcode of each key is computed, and the entry is placed in all corresponding buckets. Each bucket is initially cloned from " { $snippet "initial" } "; this should either be an empty vector or a one-element vector containing a pair." }
 468 { $notes "This word is used in the implemention of " { $link hash-case-quot } " and " { $link standard-combination } "." } ;
 469
 470 HELP: dispatch ( n array -- )
 471 { $values { "n" "a fixnum" } { "array" "an array of quotations" } }
 472 { $description "Calls the " { $snippet "n" } "th quotation in the array." }
 473 { $warning "This word is in the " { $vocab-link "kernel.private" } " vocabulary because it is an implementation detail used by the generic word system to accelerate method dispatch. It does not perform type or bounds checks, and user code should not need to call it directly." } ;