basis/binary-search/binary-search-docs.factor

   1 IN: binary-search
   2 USING: help.markup help.syntax sequences kernel math.order ;
   3
   4 HELP: search
   5 { $values { "seq" "a sorted sequence" } { "quot" { $quotation "( elt -- <=> )" } } { "i" "an index, or " { $link f } } { "elt" "an element, or " { $link f } } }
   6 { $description "Performs a binary search on a sequence, calling the quotation to decide whether to end the search (" { $link +eq+ } "), search lower (" { $link +lt+ } ") or search higher (" { $link +gt+ } ")."
   7 $nl
   8 "If the sequence is non-empty, outputs the index and value of the closest match, which is either an element for which the quotation output " { $link +eq+ } ", or failing that, least element for which the quotation output " { $link +lt+ } "."
   9 $nl
  10 "If the sequence is empty, outputs " { $link f } " " { $link f } "." }
  11 { $notes "If the sequence has at least one element, this word always outputs a valid index, because it finds the closest match, not necessarily an exact one. In this respect its behavior differs from " { $link find } "." } ;
  12
  13 { find find-from find-last find-last find-last-from search } related-words
  14
  15 HELP: sorted-index
  16 { $values { "obj" object } { "seq" "a sorted sequence" } { "i" "an index, or " { $link f } } }
  17 { $description "Outputs the index and value of the element closest to " { $snippet "elt" } " in the sequence. See " { $link search } " for details." }
  18 { $notes "If the sequence has at least one element, this word always outputs a valid index, because it finds the closest match, not necessarily an exact one. In this respect its behavior differs from " { $link index } "." } ;
  19
  20 { index index-from last-index last-index-from sorted-index } related-words
  21
  22 HELP: sorted-member?
  23 { $values { "obj" object } { "seq" "a sorted sequence" } { "?" "a boolean" } }
  24 { $description "Tests if the sorted sequence contains " { $snippet "elt" } ". Equality is tested with " { $link = } "." } ;
  25
  26 { member? sorted-member? } related-words
  27
  28 HELP: sorted-memq?
  29 { $values { "obj" object } { "seq" "a sorted sequence" } { "?" "a boolean" } }
  30 { $description "Tests if the sorted sequence contains " { $snippet "elt" } ". Equality is tested with " { $link eq? } "." } ;
  31
  32 { memq? sorted-memq? } related-words
  33
  34 ARTICLE: "binary-search" "Binary search"
  35 "The " { $emphasis "binary search" } " algorithm allows elements to be located in sorted sequence in " { $snippet "O(log n)" } " time."
  36 { $subsection search }
  37 "Variants of sequence words optimized for sorted sequences:"
  38 { $subsection sorted-index }
  39 { $subsection sorted-member? }
  40 { $subsection sorted-memq? }
  41 { $see-also "order-specifiers" "sequences-sorting" } ;
  42
  43 ABOUT: "binary-search"