core/grouping/grouping-docs.factor

   1 USING: help.markup help.syntax sequences strings ;
   2 IN: grouping
   3
   4 ARTICLE: "grouping" "Groups and clumps"
   5 "A virtual sequence for splitting a sequence into disjoint, fixed-length subsequences:"
   6 { $subsection groups }
   7 { $subsection <groups> }
   8 { $subsection <sliced-groups> }
   9 "A virtual sequence for splitting a sequence into overlapping, fixed-length subsequences:"
  10 { $subsection clumps }
  11 { $subsection <clumps> }
  12 { $subsection <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 "dup n groups concat sequence= ." "t" }
  17     }
  18     { "With clumps, collecting the first element of each subsequence but the last one, together with the last subseqence, yields the original sequence:"
  19         { $unchecked-example "dup n clumps unclip-last >r [ first ] map r> append sequence= ." "t" }
  20     }
  21 } ;
  22
  23 ABOUT: "grouping"
  24
  25 HELP: groups
  26 { $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."
  27 $nl
  28 "New groups are created by calling " { $link <groups> } " and " { $link <sliced-groups> } "." }
  29 { $see-also group } ;
  30
  31 HELP: group
  32 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
  33 { $description "Splits the sequence into disjoint groups of " { $snippet "n" } " elements and collects the groups into a new array." }
  34 { $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." }
  35 { $examples
  36     { $example "USING: splitting prettyprint ;" "{ 3 1 3 3 7 } 2 group ." "{ { 3 1 } { 3 3 } { 7 } }" }
  37 } ;
  38
  39 HELP: <groups>
  40 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  41 { $description "Outputs a virtual sequence whose elements are disjoint subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  42 { $examples
  43     { $example
  44         "USING: arrays kernel prettyprint sequences splitting ;"
  45         "9 >array 3 <groups> dup reverse-here concat >array ." "{ 6 7 8 3 4 5 0 1 2 }"
  46     }
  47 } ;
  48
  49 HELP: <sliced-groups>
  50 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" groups } }
  51 { $description "Outputs a virtual sequence whose elements are overlapping subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  52 { $examples
  53     { $example
  54         "USING: arrays kernel prettyprint sequences splitting ;"
  55         "9 >array 3 <sliced-groups>"
  56         "dup [ reverse-here ] each concat >array ."
  57         "{ 2 1 0 5 4 3 8 7 6 }"
  58     }
  59 } ;
  60
  61 HELP: clumps
  62 { $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."
  63 $nl
  64 "New clumps are created by calling " { $link <clumps> } " and " { $link <sliced-clumps> } "." } ;
  65
  66 HELP: clump
  67 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "array" "a sequence of sequences" } }
  68 { $description "Splits the sequence into overlapping clumps of " { $snippet "n" } " elements and collects the clumps into a new array." }
  69 { $errors "Throws an error if " { $snippet "n" } " is smaller than the length of the sequence." }
  70 { $examples
  71     { $example "USING: splitting prettyprint ;" "{ 3 1 3 3 7 } 2 clump ." "{ { 3 1 } { 1 3 } { 3 3 } { 3 7 } }" }
  72 } ;
  73
  74 HELP: <clumps>
  75 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
  76 { $description "Outputs a virtual sequence whose elements are overlapping subsequences of " { $snippet "n" } " elements from the underlying sequence." }
  77 { $examples
  78     "Running averages:"
  79     { $example
  80         "USING: splitting sequences math prettyprint kernel ;"
  81         "IN: scratchpad"
  82         ": share-price"
  83         "    { 13/50 51/100 13/50 1/10 4/5 17/20 33/50 3/25 19/100 3/100 } ;"
  84         ""
  85         "share-price 4 <clumps> [ [ sum ] [ length ] bi / ] map ."
  86         "{ 113/400 167/400 201/400 241/400 243/400 91/200 1/4 }"
  87     }
  88 } ;
  89
  90 HELP: <sliced-clumps>
  91 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "clumps" clumps } }
  92 { $description "Outputs a virtual sequence whose elements are overlapping slices of " { $snippet "n" } " elements from the underlying sequence." } ;
  93
  94 { clumps groups } related-words
  95
  96 { clump group } related-words
  97
  98 { <clumps> <groups> } related-words
  99
 100 { <sliced-clumps> <sliced-groups> } related-words