basis/sequences/product/product-docs.factor

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