basis/sequences/product/product-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: assocs help.markup help.syntax quotations sequences ;
   3 IN: sequences.product
   4
   5 HELP: product-sequence
   6 { $class-description "A class of virtual sequences that present the cartesian product of their underlying set of sequences. Product sequences are constructed with the " { $link <product-sequence> } " word." }
   7 { $examples
   8 { $example """USING: arrays prettyprint sequences.product ;
   9 { { 1 2 3 } { "a" "b" "c" } } <product-sequence> >array .
  10 """ """{
  11     { 1 "a" }
  12     { 2 "a" }
  13     { 3 "a" }
  14     { 1 "b" }
  15     { 2 "b" }
  16     { 3 "b" }
  17     { 1 "c" }
  18     { 2 "c" }
  19     { 3 "c" }
  20 }""" } } ;
  21
  22 HELP: <product-sequence>
  23 { $values { "sequences" sequence } { "product-sequence" product-sequence } }
  24 { $description "Constructs a " { $link product-sequence } " over " { $snippet "sequences" } "." }
  25 { $examples
  26 { $example """USING: arrays prettyprint sequences.product ;
  27 { { 1 2 3 } { "a" "b" "c" } } <product-sequence> >array ."""
  28 """{
  29     { 1 "a" }
  30     { 2 "a" }
  31     { 3 "a" }
  32     { 1 "b" }
  33     { 2 "b" }
  34     { 3 "b" }
  35     { 1 "c" }
  36     { 2 "c" }
  37     { 3 "c" }
  38 }""" } } ;
  39
  40 { product-sequence <product-sequence> } related-words
  41
  42 HELP: product-map
  43 { $values { "sequences" sequence } { "quot" { $quotation ( ... seq -- ... value ) } } { "sequence" sequence } }
  44 { $description "Calls " { $snippet "quot" } " for every element of the cartesian product of " { $snippet "sequences" } " and collects the results from " { $snippet "quot" } " into an output sequence." }
  45 { $notes { $snippet "[ ... ] product-map" } " is equivalent to, but more efficient than, " { $snippet "<product-sequence> [ ... ] map" } "." } ;
  46
  47 HELP: product-map-as
  48 { $values { "sequences" sequence } { "quot" { $quotation ( ... seq -- ... value ) } } { "exemplar" sequence } { "sequence" sequence } }
  49 { $description "Calls " { $snippet "quot" } " for every element of the cartesian product of " { $snippet "sequences" } " and collects the results from " { $snippet "quot" } " into an output sequence the same type as the " { $snippet "exemplar" } " sequence." } ;
  50
  51 HELP: product-map>assoc
  52 { $values { "sequences" sequence } { "quot" { $quotation ( ... seq -- ... key value ) } } { "exemplar" assoc } { "assoc" assoc } }
  53 { $description "Calls " { $snippet "quot" } " for every element of the cartesian product of " { $snippet "sequences" } " and collects the results from " { $snippet "quot" } " into an output assoc." } ;
  54
  55 HELP: product-each
  56 { $values { "sequences" sequence } { "quot" { $quotation ( ... seq -- ... ) } } }
  57 { $description "Calls " { $snippet "quot" } " for every element of the cartesian product of " { $snippet "sequences" } "." }
  58 { $notes { $snippet "[ ... ] product-each" } " is equivalent to, but more efficient than, " { $snippet "<product-sequence> [ ... ] each" } "." } ;
  59
  60 { product-map product-each } related-words
  61
  62 ARTICLE: "sequences.product" "Product sequences"
  63 "The " { $vocab-link "sequences.product" } " vocabulary provides a virtual sequence and combinators for manipulating the cartesian product of a set of sequences."
  64 { $subsections
  65     product-sequence
  66     <product-sequence>
  67     product-map
  68     product-map-as
  69     product-map>assoc
  70     product-each
  71 } ;
  72
  73 ABOUT: "sequences.product"