basis/splitting/monotonic/monotonic-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations classes sequences
   4 multiline ;
   5 IN: splitting.monotonic
   6
   7 HELP: monotonic-slice
   8 { $values
   9      { "seq" sequence } { "quot" quotation } { "class" class }
  10      { "slices" "a sequence of slices" }
  11 }
  12 { $description "Monotonically splits a sequence into slices of the type " { $snippet "class" } "." }
  13 { $examples
  14     { $example
  15         "USING: splitting.monotonic math prettyprint ;"
  16         "{ 1 2 3 2 3 4 } [ < ] upward-slice monotonic-slice ."
  17         <" {
  18     T{ upward-slice
  19         { from 0 }
  20         { to 3 }
  21         { seq { 1 2 3 2 3 4 } }
  22     }
  23     T{ upward-slice
  24         { from 3 }
  25         { to 6 }
  26         { seq { 1 2 3 2 3 4 } }
  27     }
  28 }">
  29     }
  30 } ;
  31
  32 HELP: monotonic-split
  33 { $values
  34      { "seq" sequence } { "quot" quotation }
  35      { "newseq" "a sequence of sequences" }
  36 }
  37 { $description "Compares pairs of elements in a sequence and collects elements into sequences while they satisfy the predicate. Once the predicate fails, a new sequence is started, and all sequences are returned in a single sequence." }
  38 { $examples
  39     { $example
  40         "USING: splitting.monotonic math prettyprint ;"
  41         "{ 1 2 3 2 3 4 } [ < ] monotonic-split ."
  42         "{ V{ 1 2 3 } V{ 2 3 4 } }"
  43     }
  44 } ;
  45
  46 HELP: downward-slices
  47 { $values
  48      { "seq" sequence }
  49      { "slices" "a sequence of downward-slices" }
  50 }
  51 { $description "Returns an array of monotonically decreasing slices of type " { $link downward-slice } ". Slices of one element are discarded." } ;
  52
  53 HELP: stable-slices
  54 { $values
  55     { "seq" sequence }
  56     { "slices" "a sequence of stable-slices" }
  57 }
  58 { $description "Returns an array of monotonically decreasing slices of type " { $link downward-slice } ". Slices of one element are discarded." } ;
  59
  60 HELP: upward-slices
  61 { $values
  62     { "seq" sequence }
  63     { "slices" "a sequence of upward-slices" }
  64 }
  65 { $description "Returns an array of monotonically increasing slices of type " { $link downward-slice } ". Slices of one element are discarded." } ;
  66
  67 HELP: trends
  68 { $values
  69     { "seq" sequence }
  70     { "slices" "a sequence of downward, stable, and upward slices" }
  71 }
  72 { $description "Returns a sorted sequence of downward, stable, or upward slices. The endpoints of some slices may overlap with each other." }
  73 { $examples
  74     { $example
  75         "USING: splitting.monotonic math prettyprint ;"
  76         "{ 1 2 3 3 2 1 } trends ."
  77         <" {
  78     T{ upward-slice
  79         { from 0 }
  80         { to 3 }
  81         { seq { 1 2 3 3 2 1 } }
  82     }
  83     T{ stable-slice
  84         { from 2 }
  85         { to 4 }
  86         { seq { 1 2 3 3 2 1 } }
  87     }
  88     T{ downward-slice
  89         { from 3 }
  90         { to 6 }
  91         { seq { 1 2 3 3 2 1 } }
  92     }
  93 }">
  94     }
  95 } ;
  96
  97 ARTICLE: "splitting.monotonic" "Splitting trending sequences"
  98 "The " { $vocab-link "splitting.monotonic" } " vocabulary splits sequences that are trending downwards, upwards, or stably." $nl
  99 "Splitting into sequences:"
 100 { $subsection monotonic-split }
 101 "Splitting into slices:"
 102 { $subsection monotonic-slice }
 103 "Trending:"
 104 { $subsection downward-slices }
 105 { $subsection stable-slices }
 106 { $subsection upward-slices }
 107 { $subsection trends } ;
 108
 109 ABOUT: "splitting.monotonic"