basis/sequences/generalizations/generalizations-docs.factor

   1 ! Copyright (C) 2009 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup kernel sequences quotations
   4 math arrays combinators ;
   5 IN: sequences.generalizations
   6
   7 HELP: nsequence
   8 { $values { "n" integer } { "seq" "an exemplar" } }
   9 { $description "A generalization of " { $link 2sequence } ", "
  10 { $link 3sequence } ", and " { $link 4sequence } " "
  11 "that constructs a sequence from the top " { $snippet "n" } " elements of the stack."
  12 }
  13 { $examples
  14     { $example "USING: prettyprint sequences.generalizations ;" "CHAR: f CHAR: i CHAR: s CHAR: h 4 \"\" nsequence ." "\"fish\"" }
  15 } ;
  16
  17 HELP: narray
  18 { $values { "n" integer } }
  19 { $description "A generalization of " { $link 1array } ", "
  20 { $link 2array } ", " { $link 3array } " and " { $link 4array } " "
  21 "that constructs an array from the top " { $snippet "n" } " elements of the stack."
  22 }
  23 { $examples
  24     "Some core words expressed in terms of " { $link narray } ":"
  25     { $table
  26         { { $link 1array } { $snippet "1 narray" } }
  27         { { $link 2array } { $snippet "2 narray" } }
  28         { { $link 3array } { $snippet "3 narray" } }
  29         { { $link 4array } { $snippet "4 narray" } }
  30     }
  31 } ;
  32
  33 { nsequence narray } related-words
  34
  35 HELP: firstn
  36 { $values { "n" integer } }
  37 { $description "A generalization of " { $link first } ", "
  38 { $link first2 } ", " { $link first3 } " and " { $link first4 } " "
  39 "that pushes the first " { $snippet "n" } " elements of a sequence on the stack."
  40 }
  41 { $examples
  42     "Some core words expressed in terms of " { $link firstn } ":"
  43     { $table
  44         { { $link first } { $snippet "1 firstn" } }
  45         { { $link first2 } { $snippet "2 firstn" } }
  46         { { $link first3 } { $snippet "3 firstn" } }
  47         { { $link first4 } { $snippet "4 firstn" } }
  48     }
  49 } ;
  50
  51 HELP: ?firstn
  52 { $values { "n" integer } }
  53 { $description "A generalization of " { $link ?first } " that pushes the first " { $snippet "n" } " elements of a sequence on the stack, or " { $link f }  " if the sequence is shorter than the requested number of elements." }
  54 { $examples
  55     "Some core words expressed in terms of " { $link ?firstn } ":"
  56     { $table
  57         { { $link ?first } { $snippet "1 ?firstn" } }
  58     }
  59 } ;
  60
  61 HELP: set-firstn
  62 { $values { "n" integer } }
  63 { $description "A generalization of " { $link set-first } " "
  64 "that sets the first " { $snippet "n" } " elements of a sequence from the top " { $snippet "n" } " elements of the stack." } ;
  65
  66 HELP: nappend
  67 { $values
  68     { "n" integer }
  69     { "seq" sequence }
  70 }
  71 { $description "Outputs a new sequence consisting of the elements of the top " { $snippet "n" } " sequences from the datastack in turn." }
  72 { $errors "Throws an error if any of the sequences contain elements that are not permitted in the sequence type of the first sequence." }
  73 { $examples
  74     { $example "USING: math prettyprint sequences.generalizations ;"
  75                "{ 1 2 } { 3 4 } { 5 6 } { 7 8 } 4 nappend ."
  76                "{ 1 2 3 4 5 6 7 8 }"
  77     }
  78 } ;
  79
  80 HELP: nappend-as
  81 { $values
  82     { "n" integer } { "exemplar" sequence }
  83     { "seq" sequence }
  84 }
  85 { $description "Outputs a new sequence of type " { $snippet "exemplar" } " consisting of the elements of the top " { $snippet "n" } " sequences from the datastack in turn." }
  86 { $errors "Throws an error if any of the sequences contain elements that are not permitted in the sequence type of the first sequence." }
  87 { $examples
  88     { $example "USING: math prettyprint sequences.generalizations ;"
  89                "{ 1 2 } { 3 4 } { 5 6 } { 7 8 } 4 V{ } nappend-as ."
  90                "V{ 1 2 3 4 5 6 7 8 }"
  91     }
  92 } ;
  93
  94 { nappend nappend-as } related-words
  95
  96 HELP: neach
  97 { $values { "seq..." { $snippet "n" } " sequences on the datastack" } { "quot" { $quotation ( element... -- ) } } { "n" integer } }
  98 { $description "A generalization of " { $link each } ", " { $link 2each } ", and " { $link 3each } " that can iterate over any number of sequences in parallel." } ;
  99
 100 HELP: nmap
 101 { $values { "seq..." { $snippet "n" } " sequences on the datastack" } { "quot" { $quotation ( element... -- result ) } } { "n" integer } { "result" "a sequence of the same type as the first " { $snippet "seq" } } }
 102 { $description "A generalization of " { $link map } ", " { $link 2map } ", and " { $link 3map } " that can map over any number of sequences in parallel." } ;
 103
 104 HELP: nmap-as
 105 { $values { "seq..." { $snippet "n" } " sequences on the datastack" } { "quot" { $quotation ( element... -- result ) } } { "exemplar" sequence } { "n" integer } { "result" "a sequence of the same type as " { $snippet "exemplar" } } }
 106 { $description "A generalization of " { $link map-as } ", " { $link 2map-as } ", and " { $link 3map-as } " that can map over any number of sequences in parallel." } ;
 107
 108 HELP: mnmap
 109 { $values { "m*seq" { $snippet "m" } " sequences on the datastack" } { "quot" { $quotation ( m*element -- result*n ) } } { "m" integer } { "n" integer } { "result*n" { $snippet "n" } " sequences of the same type as the first " { $snippet "seq" } } }
 110 { $description "A generalization of " { $link map } ", " { $link 2map } ", and " { $link 3map } " that can map over any number of sequences in parallel and provide any number of output sequences." } ;
 111
 112 HELP: mnmap-as
 113 { $values { "m*seq" { $snippet "m" } " sequences on the datastack" } { "quot" { $quotation ( m*element -- result*n ) } } { "n*exemplar" { $snippet "n" } " sequences on the datastack" } { "m" integer } { "n" integer } { "result*n" { $snippet "n" } " sequences on the datastack of the same types as the " { $snippet "exemplar" } "s" } }
 114 { $description "A generalization of " { $link map-as } ", " { $link 2map-as } ", and " { $link 3map-as } " that can map over any number of sequences in parallel and provide any number of output sequences of distinct types." } ;
 115
 116 HELP: nproduce
 117 { $values { "pred" { $quotation ( -- ? ) } } { "quot" { $quotation "( -- obj1 obj2 ... objn )" } } { "n" integer } { "seq..." { $snippet "n" } " arrays on the datastack" } }
 118 { $description "A generalization of " { $link produce } " that generates " { $snippet "n" } " arrays in parallel by calling " { $snippet "quot" } " repeatedly until " { $snippet "pred" } " outputs false." } ;
 119
 120 HELP: nproduce-as
 121 { $values { "pred" { $quotation ( -- ? ) } } { "quot" { $quotation "( -- obj1 obj2 ... objn )" } } { "exemplar..." { $snippet "n" } " sequences on the datastack" } { "n" integer } { "seq..." { $snippet "n" } " sequences on the datastack of the same types as the " { $snippet "exemplar" } "s" } }
 122 { $description "A generalization of " { $link produce-as } " that generates " { $snippet "n" } " sequences in parallel by calling " { $snippet "quot" } " repeatedly until " { $snippet "pred" } " outputs false." } ;
 123
 124 HELP: nmap-reduce
 125 { $values { "map-quot" { $quotation ( element... -- intermediate ) } } { "reduce-quot" { $quotation ( prev intermediate -- next ) } } { "n" integer } }
 126 { $description "A generalization of " { $link map-reduce } " that can be applied to any number of sequences." } ;
 127
 128 HELP: nall?
 129 { $values { "seqs..." { $snippet "n" } " sequences on the datastack" } { "quot" { $quotation ( element... -- ? ) } } { "n" integer } { "?" boolean } }
 130 { $description "A generalization of " { $link all? } " that can be applied to any number of sequences." } ;
 131
 132 HELP: nfind
 133 { $values { "seqs..." { $snippet "n" } " sequences on the datastack" } { "quot" { $quotation ( element... -- ? ) } } { "n" integer } { "i" integer } { "elts..." { $snippet "n" } " elements on the datastack" } }
 134 { $description "A generalization of " { $link find } " that can be applied to any number of sequences." } ;
 135
 136 HELP: nany?
 137 { $values { "seqs..." { $snippet "n" } " sequences on the datastack" } { "quot" { $quotation ( element... -- ? ) } } { "n" integer } { "?" boolean } }
 138 { $description "A generalization of " { $link any? } " that can be applied to any number of sequences." } ;
 139
 140 ARTICLE: "sequences.generalizations" "Generalized sequence words"
 141 "The " { $vocab-link "sequences.generalizations" } " vocabulary defines generalized versions of various sequence operations."
 142 { $subsections
 143     narray
 144     nsequence
 145     firstn
 146     set-firstn
 147     nappend
 148     nappend-as
 149 }
 150 "Generalized " { $link "sequences-combinators" } ":"
 151 { $subsections
 152     neach
 153     nmap
 154     nmap-as
 155     mnmap
 156     mnmap-as
 157     nproduce
 158     nproduce-as
 159 } ;
 160
 161 ABOUT: "sequences.generalizations"