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