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 "Monotonically splits a sequence." }
  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 } ;
  36
  37 HELP: downward-slices
  38 { $values
  39      { "seq" sequence }
  40      { "slices" "a sequence of downward-slices" }
  41 }
  42 { $description "Returns an array of monotonically decreasing slices of type " { $link downward-slice } ". Slices of one element are discarded." } ;
  43
  44 HELP: stable-slices
  45 { $values
  46     { "seq" sequence }
  47     { "slices" "a sequence of stable-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: upward-slices
  52 { $values
  53     { "seq" sequence }
  54     { "slices" "a sequence of upward-slices" }
  55 }
  56 { $description "Returns an array of monotonically increasing slices of type " { $link downward-slice } ". Slices of one element are discarded." } ;
  57
  58 HELP: trends
  59 { $values
  60     { "seq" sequence }
  61     { "slices" "a sequence of downward, stable, and upward slices" }
  62 }
  63 { $description "Returns a sorted sequence of downward, stable, or upward slices. The endpoints of some slices may overlap with each other." }
  64 { $examples
  65     { $example
  66         "USING: splitting.monotonic math prettyprint ;"
  67         "{ 1 2 3 3 2 1 } trends ."
  68         "{
  69     T{ upward-slice { to 3 } { seq { 1 2 3 3 2 1 } } }
  70     T{ stable-slice
  71         { from 2 }
  72         { to 4 }
  73         { seq { 1 2 3 3 2 1 } }
  74     }
  75     T{ downward-slice
  76         { from 3 }
  77         { to 6 }
  78         { seq { 1 2 3 3 2 1 } }
  79     }
  80 }"
  81     }
  82 } ;
  83
  84 ARTICLE: "splitting.monotonic" "Splitting trending sequences"
  85 "The " { $vocab-link "splitting.monotonic" } " vocabulary splits sequences that are trending downwards, upwards, or stably." $nl
  86 "Splitting into sequences:"
  87 { $subsections monotonic-split }
  88 "Splitting into slices:"
  89 { $subsections monotonic-split-slice }
  90 "Trending:"
  91 { $subsections
  92     downward-slices
  93     stable-slices
  94     upward-slices
  95     trends
  96 } ;
  97
  98 ABOUT: "splitting.monotonic"