basis/sequences/merged/merged-docs.factor

   1 USING: help.markup help.syntax sequences ;
   2 IN: sequences.merged
   3
   4 ARTICLE: "sequences-merge" "Merging sequences"
   5 "When multiple sequences are merged into one sequence, the new sequence takes an element from each input sequence in turn. For example, if we merge " { $code "{ 1 2 3 }" } "and" { $code "{ \"a\" \"b\" \"c\" }" } "we get:" { $code "{ 1 \"a\" 2 \"b\" 3 \"c\" }" } "."
   6 { $subsections
   7     merge
   8     2merge
   9     3merge
  10     <merged>
  11     <2merged>
  12     <3merged>
  13 } ;
  14
  15 ABOUT: "sequences-merge"
  16
  17 HELP: merged
  18 { $class-description "A virtual sequence which presents a merged view of its underlying elements. New instances are created by calling one of " { $link <merged> } ", " { $link <2merged> } ", or " { $link <3merged> } "." }
  19 { $see-also merge } ;
  20
  21 HELP: <merged>
  22 { $values { "seqs" "a sequence of sequences to merge" } { "merged" "a virtual sequence" } }
  23 { $description "Creates an instance of the " { $link merged } " virtual sequence. The length of the created virtual sequences is the minimum length of the input sequences times the number of input sequences." }
  24 { $see-also <2merged> <3merged> merge } ;
  25
  26 HELP: <2merged>
  27 { $values { "seq1" sequence } { "seq2" sequence } { "merged" "a virtual sequence" } }
  28 { $description "Creates an instance of the " { $link merged } " virtual sequence which merges the two input sequences." }
  29 { $see-also <merged> <3merged> 2merge } ;
  30
  31 HELP: <3merged>
  32 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "merged" "a virtual sequence" } }
  33 { $description "Creates an instance of the " { $link merged } " virtual sequence which merges the three input sequences." }
  34 { $see-also <merged> <2merged> 3merge } ;
  35
  36 HELP: merge
  37 { $values { "seqs" "a sequence of sequences to merge" } { "seq" "a new sequence" } }
  38 { $description "Outputs a new sequence which merges the elements of each sequence in " { $snippet "seqs" } "." }
  39 { $examples
  40     { $example "USING: prettyprint sequences.merged ;" "{ { 1 2 } { 3 4 } { 5 6 } } merge ." "{ 1 3 5 2 4 6 }" }
  41     { $example "USING: prettyprint sequences.merged ;" "{ \"abc\" \"def\" } merge ." "\"adbecf\"" }
  42 }
  43 { $see-also 2merge 3merge <merged> } ;
  44
  45 HELP: 2merge
  46 { $values { "seq1" sequence } { "seq2" sequence } { "seq" "a new sequence" } }
  47 { $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of " { $snippet "seq1" } " and " { $snippet "seq2" } }
  48 { $see-also merge 3merge <2merged> } ;
  49
  50 HELP: 3merge
  51 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "seq" "a new sequence" } }
  52 { $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of all three sequences" }
  53 { $see-also merge 2merge <3merged> } ;