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