extra/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 { $subsection merge }
   7 { $subsection 2merge }
   8 { $subsection 3merge }
   9 { $subsection <merged> }
  10 { $subsection <2merged> }
  11 { $subsection <3merged> } ;
  12
  13 ABOUT: "sequences-merge"
  14
  15 HELP: merged
  16 { $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> } "." }
  17 { $see-also merge } ;
  18
  19 HELP: <merged> ( seqs -- merged )
  20 { $values { "seqs" "a sequence of sequences to merge" } { "merged" "a virtual sequence" } }
  21 { $description "Creates an instance of the " { $link merged } " virtual sequence." }
  22 { $see-also <2merged> <3merged> merge } ;
  23
  24 HELP: <2merged> ( seq1 seq2 -- merged )
  25 { $values { "seq1" sequence } { "seq2" sequence } { "merged" "a virtual sequence" } }
  26 { $description "Creates an instance of the " { $link merged } " virtual sequence which merges the two input sequences." }
  27 { $see-also <merged> <3merged> 2merge } ;
  28
  29 HELP: <3merged> ( seq1 seq2 seq3 -- merged )
  30 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "merged" "a virtual sequence" } }
  31 { $description "Creates an instance of the " { $link merged } " virtual sequence which merges the three input sequences." }
  32 { $see-also <merged> <2merged> 3merge } ;
  33
  34 HELP: merge ( seqs -- seq )
  35 { $values { "seqs" "a sequence of sequences to merge" } { "seq" "a new sequence" } }
  36 { $description "Outputs a new sequence which merges the elements of each sequence in " { $snippet "seqs" } "." }
  37 { $examples
  38     { $example "USING: prettyprint sequences.merged ;" "{ { 1 2 } { 3 4 } { 5 6 } } merge ." "{ 1 3 5 2 4 6 }" }
  39     { $example "USING: prettyprint sequences.merged ;" "{ \"abc\" \"def\" } merge ." "\"adbecf\"" }
  40 }
  41 { $see-also 2merge 3merge <merged> } ;
  42
  43 HELP: 2merge ( seq1 seq2 -- seq )
  44 { $values { "seq1" sequence } { "seq2" sequence } { "seq" "a new sequence" } }
  45 { $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of " { $snippet "seq1" } " and " { $snippet "seq2" } }
  46 { $see-also merge 3merge <2merged> } ;
  47
  48 HELP: 3merge ( seq1 seq2 seq3 -- seq )
  49 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "seq" "a new sequence" } }
  50 { $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of all three sequences" }
  51 { $see-also merge 2merge <3merged> } ;