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 "Splitting a sequence into overlapping, fixed-length subsequences, wrapping around the end of the sequence:"
  12 { $subsections circular-clump }
  13 "A virtual sequence for splitting a sequence into overlapping, fixed-length subsequences:"
  14 { $subsections clumps <clumps> <sliced-clumps> }
  15 "A virtual sequence for splitting a sequence into overlapping, fixed-length subsequences:"
  16 { $subsections circular-clumps <circular-clumps> <sliced-circular-clumps> }
  17 "The difference can be summarized as the following:"
  18 { $list
  19     { "With groups, the subsequences form the original sequence when concatenated:"
  20         { $unchecked-example
  21             "USING: grouping ;"
  22             "{ 1 2 3 4 } 2 group ." "{ { 1 2 } { 3 4 } }"
  23         }
  24         { $unchecked-example
  25             "USING: grouping ;"
  26             "{ 1 2 3 4 } dup" "2 <groups> concat sequence= ." "t"
  27         }
  28     }
  29     { "With clumps, collecting the first element of each subsequence but the last one, together with the last subseqence, yields the original sequence:"
  30         { $unchecked-example
  31             "USING: grouping ;"
  32             "{ 1 2 3 4 } 2 clump ." "{ { 1 2 } { 2 3 } { 3 4 } }"
  33         }
  34         { $unchecked-example
  35             "USING: grouping assocs sequences ;"
  36             "{ 1 2 3 4 } dup" "2 <clumps> unclip-last [ keys ] dip append sequence= ." "t"
  37         }
  38     }
  39     { "With circular clumps, collecting the first element of each subsequence yields the original sequence. Collecting the " { $snippet "n" } "th element of each subsequence would rotate the original sequence " { $snippet "n" } " elements rightward:"
  40         { $unchecked-example
  41             "USING: grouping ;"
  42             "{ 1 2 3 4 } 2 circular-clump ." "{ { 1 2 } { 2 3 } { 3 4 } { 4 1 } }"
  43         }
  44         { $unchecked-example
  45             "USING: grouping assocs sequences ;"
  46             "{ 1 2 3 4 } dup" "2 <circular-clumps> keys sequence= ." "t"
  47         }
  48         { $unchecked-example
  49             "USING: grouping ;"
  50             "{ 1 2 3 4 } dup" "2 <circular-clumps> [ second ] { } map-as ." "{ 2 3 4 1 }"
  51         }
  52     }
  53 }
  54 $nl
  55 "A combinator built using clumps:"
  56 { $subsections monotonic? }
  57 "Testing how elements are related:"
  58 { $subsections all-eq? all-equal? } ;
  59
  60 ABOUT: "grouping"
  61
  62 HELP: groups
  63 { $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."
  64 $nl
  65 "New groups are created by calling " { $link <groups> } " and " { $link <sliced-groups> } "." } ;
  66
  67 HELP: group
  68 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
  69 { $description "Splits the sequence into disjoint groups of " { $snippet "n" } " elements and collects the groups into a new array." }
  70 { $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." }
  71 { $examples
  72     { $example "USING: grouping prettyprint ;" "{ 3 1 3 3 7 } 2 group ." "{ { 3 1 } { 3 3 } { 7 } }" }
  73 } ;
  74
  75 HELP: <groups>
  76 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  77 { $description "Outputs a virtual sequence whose elements are disjoint subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  78 { $examples
  79     { $example
  80         "USING: arrays kernel prettyprint sequences grouping ;"
  81         "9 iota >array 3 <groups> reverse! concat >array ." "{ 6 7 8 3 4 5 0 1 2 }"
  82     }
  83     { $example
  84         "USING: kernel prettyprint sequences grouping ;"
  85         "{ 1 2 3 4 5 6 } 3 <groups> first ."
  86         "{ 1 2 3 }"
  87     }
  88 } ;
  89
  90 HELP: <sliced-groups>
  91 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  92 { $description "Outputs a virtual sequence whose elements are slices of disjoint subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  93 { $examples
  94     { $example
  95         "USING: arrays kernel prettyprint sequences grouping ;"
  96         "9 iota >array 3 <sliced-groups>"
  97         "dup [ reverse! drop ] each concat >array ."
  98         "{ 2 1 0 5 4 3 8 7 6 }"
  99     }
 100     { $example
 101         "USING: kernel prettyprint sequences grouping ;"
 102         "{ 1 2 3 4 5 6 } 3 <sliced-groups> second ."
 103         "T{ slice { from 3 } { to 6 } { seq { 1 2 3 4 5 6 } } }"
 104     }
 105 } ;
 106
 107 HELP: clumps
 108 { $class-description "Instances are virtual sequences whose elements are overlapping fixed-length subsequences of an underlying sequence. Clumps are mutable and resizable if the underlying sequence is mutable and resizable, respectively."
 109 $nl
 110 "New clumps are created by calling " { $link <clumps> } " and " { $link <sliced-clumps> } "." } ;
 111
 112 HELP: circular-clumps
 113 { $class-description "Instances are virtual sequences whose elements are overlapping fixed-length subsequences of an underlying sequence, beginning with every element in the original sequence and wrapping around its end. Circular clumps are mutable and resizable if the underlying sequence is mutable and resizable, respectively."
 114 $nl
 115 "New clumps are created by calling " { $link <circular-clumps> } " and " { $link <sliced-circular-clumps> } "." } ;
 116
 117 HELP: clump
 118 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
 119 { $description "Splits the sequence into overlapping clumps of " { $snippet "n" } " elements and collects the clumps into a new array." }
 120 { $errors "Throws an error if " { $snippet "n" } " is larger than the length of the sequence." }
 121 { $examples
 122     { $example "USING: grouping prettyprint ;" "{ 3 1 3 3 7 } 2 clump ." "{ { 3 1 } { 1 3 } { 3 3 } { 3 7 } }" }
 123 } ;
 124
 125 HELP: circular-clump
 126 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
 127 { $description "Splits the sequence into overlapping clumps of " { $snippet "n" } " elements, wrapping around the end of the sequence, and collects the clumps into a new array." }
 128 { $errors "Throws an error if " { $snippet "n" } " is larger than the length of the sequence." }
 129 { $examples
 130     { $example "USING: grouping prettyprint ;" "{ 3 1 3 3 7 } 2 circular-clump ." "{ { 3 1 } { 1 3 } { 3 3 } { 3 7 } { 7 3 } }" }
 131 } ;
 132
 133 HELP: <clumps>
 134 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
 135 { $description "Outputs a virtual sequence whose elements are overlapping subsequences of " { $snippet "n" } " elements from the underlying sequence." }
 136 { $examples
 137     "Running averages:"
 138     { $example
 139         "USING: grouping sequences math prettyprint kernel ;"
 140         "IN: scratchpad"
 141         "CONSTANT: share-price { 13/50 51/100 13/50 1/10 4/5 17/20 33/50 3/25 19/100 3/100 }"
 142         ""
 143         "share-price 4 <clumps> [ [ sum ] [ length ] bi / ] map ."
 144         "{ 113/400 167/400 201/400 241/400 243/400 91/200 1/4 }"
 145     }
 146     { $example
 147         "USING: kernel sequences grouping prettyprint ;"
 148         "{ 1 2 3 4 5 6 } 3 <clumps> second ."
 149         "{ 2 3 4 }"
 150     }
 151 } ;
 152
 153 HELP: <circular-clumps>
 154 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
 155 { $description "Outputs a virtual sequence whose elements are overlapping subsequences of " { $snippet "n" } " elements from the underlying sequence, starting with each of its elements and wrapping around the end of the sequence." }
 156 { $examples
 157     { $example
 158         "USING: kernel sequences grouping prettyprint ;"
 159         "{ 1 2 3 4 } 3 <circular-clumps> third ."
 160         "{ 3 4 1 }"
 161     }
 162 } ;
 163
 164 HELP: <sliced-circular-clumps>
 165 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
 166 { $description "Outputs a virtual sequence whose elements are overlapping slices of " { $snippet "n" } " elements from the underlying sequence, starting with each of its elements and wrapping around the end of the sequence." }
 167 { $examples
 168     { $example
 169         "USING: arrays kernel sequences grouping prettyprint ;"
 170         "{ 1 2 3 4 } 3 <sliced-circular-clumps> third >array ."
 171         "{ 3 4 1 }"
 172     }
 173 } ;
 174
 175 { clumps circular-clumps groups } related-words
 176
 177 { clump circular-clump group } related-words
 178
 179 { <clumps> <circular-clumps> <groups> } related-words
 180
 181 { <sliced-clumps> <sliced-circular-clumps> <sliced-groups> } related-words
 182
 183 HELP: monotonic?
 184 { $values { "seq" sequence } { "quot" { $quotation "( elt elt -- ? )" } } { "?" "a boolean" } }
 185 { $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." }
 186 { $examples
 187     "Testing if a sequence is non-decreasing:"
 188     { $example "USING: grouping math prettyprint ;" "{ 1 1 2 } [ <= ] monotonic? ." "t" }
 189     "Testing if a sequence is decreasing:"
 190     { $example "USING: grouping math prettyprint ;" "{ 9 8 6 7 } [ < ] monotonic? ." "f" }
 191 } ;
 192
 193 HELP: all-equal?
 194 { $values { "seq" sequence } { "?" "a boolean" } }
 195 { $description "Tests if all elements in the sequence are equal. Yields true with an empty sequence." } ;
 196
 197 HELP: all-eq?
 198 { $values { "seq" sequence } { "?" "a boolean" } }
 199 { $description "Tests if all elements in the sequence are the same identical object. Yields true with an empty sequence." } ;
 200
 201 { monotonic? all-eq? all-equal? } related-words