basis/grouping/grouping-docs.factor

   1 USING: help.markup help.syntax sequences strings ;
   2 IN: grouping
   3
   4 ARTICLE: "grouping" "Groups and clumps"
   5 "Splitting a sequence into disjoint, fixed-length subsequences:"
   6 { $subsections group }
   7 "A virtual sequence for splitting a sequence into disjoint, fixed-length subsequences:"
   8 { $subsections groups <groups> <sliced-groups> }
   9 "Splitting a sequence into overlapping, fixed-length subsequences:"
  10 { $subsections clump }
  11 "A virtual sequence for splitting a sequence into overlapping, fixed-length subsequences:"
  12 { $subsections clumps <clumps> <sliced-clumps> }
  13 "The difference can be summarized as the following:"
  14 { $list
  15     { "With groups, the subsequences form the original sequence when concatenated:"
  16         { $unchecked-example
  17             "USING: grouping ;"
  18             "{ 1 2 3 4 } dup" "2 <groups> concat sequence= ." "t"
  19         }
  20     }
  21     { "With clumps, collecting the first element of each subsequence but the last one, together with the last subseqence, yields the original sequence:"
  22         { $unchecked-example
  23             "USING: grouping ;"
  24             "{ 1 2 3 4 } dup" "2 <clumps> unclip-last [ [ first ] map ] dip append sequence= ." "t"
  25         }
  26     }
  27 }
  28 $nl
  29 "A combinator built using clumps:"
  30 { $subsections monotonic? }
  31 "Testing how elements are related:"
  32 { $subsections all-eq? all-equal? } ;
  33
  34 ABOUT: "grouping"
  35
  36 HELP: groups
  37 { $class-description "Instances are virtual sequences whose elements are disjoint fixed-length subsequences of an underlying sequence. Groups are mutable and resizable if the underlying sequence is mutable and resizable, respectively."
  38 $nl
  39 "New groups are created by calling " { $link <groups> } " and " { $link <sliced-groups> } "." } ;
  40
  41 HELP: group
  42 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
  43 { $description "Splits the sequence into disjoint groups of " { $snippet "n" } " elements and collects the groups into a new array." }
  44 { $notes "If the sequence length is not a multiple of " { $snippet "n" } ", the final subsequence in the list will be shorter than " { $snippet "n" } " elements." }
  45 { $examples
  46     { $example "USING: grouping prettyprint ;" "{ 3 1 3 3 7 } 2 group ." "{ { 3 1 } { 3 3 } { 7 } }" }
  47 } ;
  48
  49 HELP: <groups>
  50 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  51 { $description "Outputs a virtual sequence whose elements are disjoint subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  52 { $examples
  53     { $example
  54         "USING: arrays kernel prettyprint sequences grouping ;"
  55         "9 >array 3 <groups> reverse! concat >array ." "{ 6 7 8 3 4 5 0 1 2 }"
  56     }
  57     { $example
  58         "USING: kernel prettyprint sequences grouping ;"
  59         "{ 1 2 3 4 5 6 } 3 <groups> first ."
  60         "{ 1 2 3 }"
  61     }
  62 } ;
  63
  64 HELP: <sliced-groups>
  65 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  66 { $description "Outputs a virtual sequence whose elements are slices of disjoint subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  67 { $examples
  68     { $example
  69         "USING: arrays kernel prettyprint sequences grouping ;"
  70         "9 >array 3 <sliced-groups>"
  71         "dup [ reverse! drop ] each concat >array ."
  72         "{ 2 1 0 5 4 3 8 7 6 }"
  73     }
  74     { $example
  75         "USING: kernel prettyprint sequences grouping ;"
  76         "{ 1 2 3 4 5 6 } 3 <sliced-groups> second ."
  77         "T{ slice { from 3 } { to 6 } { seq { 1 2 3 4 5 6 } } }"
  78     }
  79 } ;
  80
  81 HELP: clumps
  82 { $class-description "Instances are virtual sequences whose elements are overlapping fixed-length subsequences o an underlying sequence. Clumps are mutable and resizable if the underlying sequence is mutable and resizable, respectively."
  83 $nl
  84 "New clumps are created by calling " { $link <clumps> } " and " { $link <sliced-clumps> } "." } ;
  85
  86 HELP: clump
  87 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
  88 { $description "Splits the sequence into overlapping clumps of " { $snippet "n" } " elements and collects the clumps into a new array." }
  89 { $errors "Throws an error if " { $snippet "n" } " is smaller than the length of the sequence." }
  90 { $examples
  91     { $example "USING: grouping prettyprint ;" "{ 3 1 3 3 7 } 2 clump ." "{ { 3 1 } { 1 3 } { 3 3 } { 3 7 } }" }
  92 } ;
  93
  94 HELP: <clumps>
  95 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
  96 { $description "Outputs a virtual sequence whose elements are overlapping subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  97 { $examples
  98     "Running averages:"
  99     { $example
 100         "USING: grouping sequences math prettyprint kernel ;"
 101         "IN: scratchpad"
 102         "CONSTANT: share-price { 13/50 51/100 13/50 1/10 4/5 17/20 33/50 3/25 19/100 3/100 }"
 103         ""
 104         "share-price 4 <clumps> [ [ sum ] [ length ] bi / ] map ."
 105         "{ 113/400 167/400 201/400 241/400 243/400 91/200 1/4 }"
 106     }
 107     { $example
 108         "USING: kernel sequences grouping prettyprint ;"
 109         "{ 1 2 3 4 5 6 } 3 <clumps> second ."
 110         "{ 2 3 4 }"
 111     }
 112 } ;
 113
 114 HELP: <sliced-clumps>
 115 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
 116 { $description "Outputs a virtual sequence whose elements are overlapping slices of " { $snippet "n" } " elements from the underlying sequence." }
 117 { $examples
 118     { $example
 119         "USING: kernel sequences grouping prettyprint ;"
 120         "{ 1 2 3 4 5 6 } 3 <sliced-clumps> second ."
 121         "T{ slice { from 1 } { to 4 } { seq { 1 2 3 4 5 6 } } }"
 122     }
 123 } ;
 124
 125 { clumps groups } related-words
 126
 127 { clump group } related-words
 128
 129 { <clumps> <groups> } related-words
 130
 131 { <sliced-clumps> <sliced-groups> } related-words
 132
 133 HELP: monotonic?
 134 { $values { "seq" sequence } { "quot" { $quotation "( elt elt -- ? )" } } { "?" "a boolean" } }
 135 { $description "Applies the relation to successive pairs of elements in the sequence, testing for a truth value. The relation should be a transitive relation, such as a total order or an equality relation." }
 136 { $examples
 137     "Testing if a sequence is non-decreasing:"
 138     { $example "USING: grouping math prettyprint ;" "{ 1 1 2 } [ <= ] monotonic? ." "t" }
 139     "Testing if a sequence is decreasing:"
 140     { $example "USING: grouping math prettyprint ;" "{ 9 8 6 7 } [ < ] monotonic? ." "f" }
 141 } ;
 142
 143 HELP: all-equal?
 144 { $values { "seq" sequence } { "?" "a boolean" } }
 145 { $description "Tests if all elements in the sequence are equal. Yields true with an empty sequence." } ;
 146
 147 HELP: all-eq?
 148 { $values { "seq" sequence } { "?" "a boolean" } }
 149 { $description "Tests if all elements in the sequence are the same identical object. Yields true with an empty sequence." } ;
 150
 151 { monotonic? all-eq? all-equal? } related-words